Golang SDK 已经开源，开源地址为： datarangers-sdk-go。建议使用最新版本。${version} 表示 SDK 的版本号。
下载 SDK：
go get github.com/volcengine/datarangers-sdk-go
或者更新本地的 SDK：
go get -u github.com/volcengine/datarangers-sdk-go
或者在go.mod里面添加sdk 依赖：
require ( github.com/volcengine/datarangers-sdk-go ${version} )
如果 ${version} 没有传，表示最新的版本。
go 版本要求 >=1.17
增长分析的 SDK 支持多种上报模式，需要先选择使用模式。
模式 | 使用场景 | 部署复杂性 | 可靠性 | 上报性能 | 备注 |
|---|---|---|---|---|---|
HTTP | 绝大多数场景都可以使用，如果跨网络时延比较高，可以使用批量方式。 | 简单 | 高 | 高，支持批量上报 | 可以参考 “最佳实践”-->"查看上报时延"章节内容来查看上报的时延。 |
FILE | 不推荐 | 复杂 | 很高 | 低，写文件之后还需要使用logagent来进行上报 | |
KAFKA | 同一个网络，建议使用该模式。 | 简单 | 很高 | 高 | SDK版本>=1.1.4，私有化4.1版本（含）开始支持。 |
推荐使用 HTTP 的方式，同时使用 logagent 来补报因为网络抖动等原因导致失败的数据。
SDK 使用前需要先初始化，然后使用其提供的接口进行上报。
推荐使用配置的方式进行初始化
package main import ( // 引入 sdk sdk "github.com/volcengine/datarangers-sdk-go" ) func main() { // 初始化, YAML_PATH 替换成真实的配置文件 sdk.InitByFile("{YAML_PATH}") //... 接口调用 // 避免程序立刻退出 time.Sleep(60 * time.Second) }
需要配置sdk.mode=http
sdk: mode: http env: saas_native # 设置环境信息为 SaaS 云原生 # logLevel: debug http: addr: https://gator.volces.com #上报的IP 或 域名 appKeys: ${APP_ID}: ${APP_KEY} #asyn: # routine: 20 #建议小于1024，并发数目 # queueSize: 10240
云原生的 http.addr 地址为：https://gator.volces.com
sdk: mode: http # logLevel: debug http: addr: https://mcs.ctobsnssdk.com # 国内地址，国际: https://mcs.tobsnssdk.com appKeys: ${APP_ID}: ${APP_KEY} openapi: addr: https://analytics.volcengineapi.com # 国内地址，国际: https://analytics.byteplusapi.com ak: ${OPENAPI_AK} sk: ${OPENAPI_SK} #asyn: # routine: 20 #建议小于1024，并发数目 # queueSize: 10240
sdk: mode: http # logLevel: debug http: addr: ${SDK_DOMAIN} #上报的IP 或 域名，注意加上 http://，或者https:// # timeout: 30 # secenods #asyn: # routine: 20 #建议小于1024，并发数目 # queueSize: 10240
如果跨网络时延比较大、或者追求更高的QPS，可以开启批量上报的方式。
batch: enable: true # size: 20 # waitTimeMs: 100
该模式只在私有化支持
设置sdk.mode=file
sdk: mode: file # logLevel: debug file: path: logs1/datarangers.log errPath: logs1/error-datarangers.log # maxSize: 100 #Mb # maxBackups: 0 #日志最多保存数目 # maxAge: 0 #days #asyn: # routine: 20 #建议小于1024，并发数目 # queueSize: 10240
使用该模式，埋点事件只是记录到磁盘中，还需要配合logagent一起使用，数据才能上报到 DataFinder，关于logagent的使用，请联系客户经理获取。
该模式只在私有化支持
设置sdk.mode=kafka
sdk: mode: kafka kafka: # kafka brokers，如果有多个，则配置多个 kafka_brokers: - 127.0.0.1:9192
自定义sdk.SysConf，然后进行初始化
package main import ( sdk "github.com/volcengine/datarangers-sdk-go" ) func main() { // 初始化，设置相关参数 sysconf := &sdk.SysConf{ ... } sdk.InitBySysConf(sysconf) // 避免程序立刻退出 time.Sleep(60 * time.Second) }
import ( sdk "github.com/volcengine/datarangers-sdk-go" ) sysconf := &sdk.SysConf{ // 设置模式 SdkConfig: sdk.SdkConfig{ Mode: sdk.MODE_HTTP, Env: sdk.ENV_SAAS_NATIVE, }, // 设置domain和appKey HttpConfig: sdk.HttpConfig{ HttpAddr: "https://gator.volces.com", }, // 可以设置多个app，这里注意替换成真实的参数 AppKeys: map[int64]string{ int64(appId): os.Getenv("SDK_APP_KEY_1"), }, } sdk.InitBySysConf(sysconf)
import ( sdk "github.com/volcengine/datarangers-sdk-go" ) appId, _ := strconv.Atoi(os.Getenv("SDK_APP_1")) sysconf := &sdk.SysConf{ // 设置模式 SdkConfig: sdk.SdkConfig{ Mode: sdk.MODE_HTTP, }, // 设置domain和appKey HttpConfig: sdk.HttpConfig{ HttpAddr: "https://mcs.ctobsnssdk.com", }, // 可以设置多个app，这里注意替换成真实的参数 AppKeys: map[int64]string{ int64(appId): os.Getenv("SDK_APP_KEY_1"), }, // 设置openapi domain, AK,SK，这里注意替换成真实的参数 OpenapiConfig: sdk.OpenapiConfig{ HttpAddr: "https://analytics.volcengineapi.com", Ak: os.Getenv("OPENAPI_AK"), Sk: os.Getenv("OPENAPI_SK"), }, } sdk.InitBySysConf(sysconf)
import ( sdk "github.com/volcengine/datarangers-sdk-go" ) sysconf := &sdk.SysConf{ // 设置模式 SdkConfig: sdk.SdkConfig{ Mode: sdk.MODE_HTTP, }, // 设置sdk domain，这里注意替换成真实的参数 HttpConfig: sdk.HttpConfig{ HttpAddr: os.Getenv("SDK_DOMAIN"), }, } sdk.InitBySysConf(sysconf)
该模式只在私有化支持
设置sdk.mode=file
import ( sdk "github.com/volcengine/datarangers-sdk-go" ) sysconf := &sdk.SysConf{ // 设置模式 SdkConfig: sdk.SdkConfig{ Mode: sdk.MODE_FILE, }, // 配置保存的路径 FileConfig: sdk.FileConfig{ Path: "logs/datarangers.log", ErrPath: "logs/error-datarangers.log", }, } sdk.InitBySysConf(sysconf)
该模式只在私有化支持
设置sdk.mode=kafka
import ( sdk "github.com/volcengine/datarangers-sdk-go" ) func main() { // 初始化 sdk.InitBySysConf(&sdk.SysConf{ // 设置模式 SdkConfig: sdk.SdkConfig{ Mode: sdk.MODE_KAFKA, }, // 设置sdk kafka broker 地址，这里注意替换成真实的参数。broker 格式一般为ip:port，比如 127.0.0.1:9192 KafkaConfig: &sdk.KafkaConfig{ KafkaBrokers: []string{os.Getenv("SDK_KAFKA_BROKER_1"), os.Getenv("SDK_KAFKA_BROKER_2")}, }, }) }
配置模块 | 配置项 | 含义 | 备注 |
|---|---|---|---|
sdk | mode | 上报模式(不区分大小写)：http、file。 | |
env | 枚举类型，saas 表示云上SaaS-非云原生环境，pri表示私有化环境，saas_native 表示SaaS-云原生，非必须，sdk可以根据配置自动判定。 | ||
logLevel | 日志级别，默认是trace。支持配置： | ||
asyn | routine | 异步协程池核心协程数，默认是20。 | |
queueSize | 异步队列大小，默认是10240。 | ||
http | addr | DataFinder 的域名或者ip，支持http和https，例如为 https://{具体域名地址}
在SaaS-云原生环境中配置为：
| |
timeout | http 超时时间。 | ||
batch | enable | boolean类型，表示是否开启批量上报。默认是false，不使用批量。 | 只支持http模式，且SaaS暂不支持批量上报。 |
size | 批量上报的数量。 | ||
waitTimeMs | 批量上报，不足batchSize的时候，最大等待时间。 | ||
file | path | 保存日志的文件目录，需要保证文件的写权限，默认是 | file 模式下的配置；http 模式下，上报失败的报文记录在 |
maxSize | 单个文件最大数量，默认是100m。 | ||
maxBackup | 最大备份文件数量，默认是0，表示会保留所有文件。 | ||
maxAge | 最大保存的天数，默认是0，表示会保留所有文件。 | ||
errPath | 上报失败保存日志的文件目录，需要保证文件的写权限，默认是 | ||
kafka | kafka_brokers | 数组格式，kafka的 brokers地址 | |
topic | topic，默认是 sdk_origin_event | ||
sync_kafka_producer_conf.required_acks | 同步模式，-1：等待所有副本 0：等待本地 | ||
sync_kafka_producer_conf.retry_config.max | 消息发送最大重试次数 | ||
sync_kafka_producer_conf.flush_config.bytes | 消息发送，超过字节数强制flush | ||
sync_kafka_producer_conf.flush_config.messages | 消息发送，超过消息数强制flush | ||
sync_kafka_producer_conf.flush_config.frequency_ms | 消息发送，超过一段时间强制flush | ||
sync_kafka_producer_conf.flush_config.max_messages | 消息发送，缓冲区最大消息数 | ||
openapi | addr | openapi的域名
| 如果在SaaS-非云原生上需要进行item和用户属性上报，需要配置openapi，其他情况不需要进行配置。 |
ak | openapi的ak，请联系客户经理获取。 | ||
sk | openapi的sk，请联系客户经理获取。 | ||
不涉及 | appKeys | SaaS-非云原生以及SaaS-云原生环境，上报设置的appkeys，可以设置多个。多个可以的方式为：
|
启动会打印如下日志，可以通过监测启动日志来确定配置是否符合预期。主要关注下SdkConfig.Mode``，``HttpConfig 等配置。
[DEBUG:]2023/02/27 15:54:20 user config :{"SdkConfig":{"Mode":"file","Env":"pri","LogLevel":""},"BatchConfig":{"Enable":false,"Size":0,"WaitTimeMs":0},"FileConfig":{"EventSendEnable":false,"Path":"logs/datarangers.log","MaxSize":100,"MaxBackup":0,"MaxAge":0,"ErrPath":"logs/error-datarangers.log"},"HttpConfig":{"HttpAddr":"","SocketTimeOut":0,"Headers":null},"AsynConfig":{"Routine":20,"QueueSize":10240},"OpenapiConfig":{"HttpAddr":"","Ak":"","Sk":""},"VerifyConfig":{"Url":""},"AppKeys":null}
参考 “JAVA SDK” 文档中，“验证配置”中的 HTTP 模式方式。
查看配置 file.path 的文件目录下是否有文件，是否有文件内容。校验文件内容是否正确，可以直接拷贝一行数据，使用http的方式进行上报。
查看kafka topic: sdk_origin_event 是否有数据上来，kafka 的使用方式参考文档：Kafka订阅(私有化) 增长分析-火山引擎
使用前，需要先初始化sdk，初始化参考“SDK 初始化”，初始化之后就可以使用接口进行上报了。
// SendEvent // eventParam : 事件属性 // custom : 用户自定义事件公共属性 // Deprecated: instead of SendEventInfo func SendEvent(appType AppType, appid int64, uuid string, eventname string, eventParam map[string]interface{}, custom map[string]interface{}, did ...int64) error // SendEventInfo 上报事件信息 // event: 事件信息 // custom: 事件公共属性 func SendEventInfo(appType AppType, appId int64, uuid string, event *EventV3, custom map[string]interface{}) error // SendEventInfoWithItem 上报携带item的事件 // event: 事件信息 // custom: 事件公共属性 // itemList: item 信息 func SendEventInfoWithItem(appType AppType, appId int64, uuid string, event *EventV3, custom map[string]interface{}, itemList []*Item) error // SendEventInfos 上报多个事件 // events: 事件信息 // custom: 事件公共属性 func SendEventInfos(appType AppType, appId int64, uuid string, events []*EventV3, custom map[string]interface{}) error // SendEventWithHeader 使用header上报事件 // header: 事件的header // event: 事件信息 func SendEventWithHeader(appType AppType, appId int64, hd *Header, event *EventV3) error // SendProfile // profileAction ：用户公共属性操作类型 // profileParam : 用户公共属性 func SendProfile(apptype AppType, appid int64, uuid string, profileAction ProfileActionType, profileParam map[string]interface{}, did ...int64) error // ItemSet 设置item 属性 // itemName: item 名称 // itemParamList: item 属性信息 func ItemSet(appid int64, itemName string, itemParamList []map[string]interface{}) error
SDK DEMO可前往开源example文件夹中查看：demo链接。
// 应用id appId := {APP_ID} // 用户id uuid := {uuid} // 事件公共属性，如果不需要的话，可以传nil commonParams := map[string]interface{}{ "common_string1": "common_value1", "common_int1": 13, } eventName := "app_send_event_info" eventV3 := &sdk.EventV3{ Event: eventName, Params: map[string]interface{}{ "app_send_event_param1": "value1", "app_send_event_param2": "value2", }, } sdk.SendEventInfo(sdk.APP, appId, uuid, eventV3, commonParams)
// 应用id appId := example.AppId // 用户id uuid := example.Uuid // 用户属性 properties := map[string]interface{}{ "list": []string{"a"}, "profile_a": "param_11", } sdk.ProfileSet(sdk.APP, appId, uuid, properties)
// 应用id appId := example.AppId // item属性 itemParamList := []map[string]interface{}{ {"id": 121, "category": "economics"}, {"id": 122, "category": "literature"}, {"id": 123, "category": "fiction"}, {"id": 124, "category": "fiction"}, {"id": 125, "category": "fiction"}, } err := sdk.ItemSet(appId, "book", itemParamList)
// 应用id appId := {APP_ID} // 用户id uuid := {uuid} // 事件公共属性，如果不需要的话，可以传nil commonParams := map[string]interface{}{ "common_string1": "common_value1", "common_int1": 13, } eventName := "app_send_event_info" // 事件发生时间 localTimeMs := time.Now().UnixMilli() eventV3 := &sdk.EventV3{ Event: eventName, LocalTimeMs: &localTimeMs, Params: map[string]interface{}{ "app_send_event_param1": "value1", "app_send_event_param2": "value2", }, } sdk.SendEventInfo(sdk.APP, appId, uuid, eventV3, commonParams)
v1.1.0，v1.1.1，v1.1.2 这3个版本上报过用户属性，需要处理；如果只是上报事件，那么不需要处理：>=v1.1.3,或者使用其他方式上报数据，在升级前需要联系客户经理处理下数据，否则会导致新的用户属性上报不生效。