更新时间：2023.05.04 18:04:29
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.14
增长分析的 SDK 支持多种上报模式，需要先选择使用模式。
HTTP 模式，使用范围广，部署简单，QPS 高。SDK 直接通过http接口进行上报。
FILE 模式 (只支持私有化)，部署复杂，需要在服务器上多部署logagent进程服务。由 SDK 先将文件写到本地磁盘，然后通过logagent监听磁盘文件，由logagent使用http接口进行上报。
| 模式 | 使用场景 | 部署复杂性 | 可靠性 | 上报性能 | 备注 |
|---|---|---|---|---|---|
HTTP | 绝大多数场景都可以使用，如果跨网络时延比较高，可以使用批量方式。 | 简单 | 高 | 高，支持批量上报 | 可以参考 “最佳实践”-->"查看上报时延"章节内容来查看上报的时延。 |
FILE | 不推荐 | 复杂 | 很高 | 低，写文件之后还需要使用logagent来进行上报 |
推荐使用 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 # 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
domain
SaaS版国内站：https://mcs.ctobsnssdk.com
SaaS版国际站: https://mcs.tobsnssdk.com
SaaS云原生版：https://gator.volces.com
openapiConfig: openapi配置，如果在saas上需要进行item和用户属性上报，需要配置，其他情况不需要进行配置
openapiConfig.domain： openapi的域名
SaaS版国内站: https://analytics.volcengineapi.com
SaaS版国际站: https://analytics.byteplusapi.com
SaaS云原生版: https://analytics.volcengineapi.com
openapiConfig.ak：openapi的ak， 请联系客户经理获取
openapiConfig.sk: openapi的sk ，请联系客户经理获取
sdk: mode: http # logLevel: debug http: addr: ${SDK_DOMAIN} #上报的IP 或 域名，注意加上 http://，或者https:// headers: Host: ${SDK_HOST} # host，私有化环境Host的配置在安装部署的那台机器上，查看/home/{INSTALL_USER}/DataRangersDeploy/conf_rangers.yml中配置项sdk.report.host。 INSTALL_USER 为安装用户，一般是datarangers或者minibase # timeout: 30 # secenods #asyn: # routine: 20 #建议小于1024，并发数目 # queueSize: 10240
如果跨网络时延比较大、或者追求更高的QPS，可以开启批量上报的方式。
batch: enable: true # size: 20 # waitTimeMs: 100
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
该模式只在私有化支持
设置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.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" ) appId, _ := strconv.Atoi(os.Getenv("SDK_APP_1")) sysconf := &sdk.SysConf{ // 设置模式 SdkConfig: sdk.SdkConfig{ Mode: sdk.MODE_HTTP, }, // 设置domain和appKey, 不需要设置HOST 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, }, // 设置domain和host，这里注意替换成真实的参数 HttpConfig: sdk.HttpConfig{ HttpAddr: os.Getenv("SDK_DOMAIN"), Headers: map[string]interface{}{ "Host": os.Getenv("SDK_HOST"), }, }, } sdk.InitBySysConf(sysconf)
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, 不需要设置HOST HttpConfig: sdk.HttpConfig{ HttpAddr: "https://gator.volces.com", }, // 可以设置多个app，这里注意替换成真实的参数 AppKeys: map[int64]string{ int64(appId): os.Getenv("SDK_APP_KEY_1"), }, } 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 | 上报模式(不区分大小写)：http、file。 | |
| env | 枚举类型，saas 表示云上，pri表示私有化，saas_native 表示云原生，非必须，sdk可以根据配置自动判定。 | ||
logLevel | 日志级别，默认是trace。支持配置： | ||
| asyn | routine | 异步协程池核心协程数，默认是20。 | |
| queueSize | 异步队列大小，默认是10240。 | ||
http | addr | DataFinder 的域名或者ip，支持http和https，例如为 https://{具体域名地址}
在SaaS云原生环境中配置为：
| |
headers.Host | datarangers.sdk.headers为http请求中headers字段内容,在私有化环境中必须要添加Host。 | 在SaaS上不需要进行配置。Host 没有 http:// 、https://。 | |
| timeout | http 超时时间。 | ||
batch | enable | boolean类型，表示是否开启批量上报。默认是false，不使用批量。 | 只支持http模式，且SaaS暂不支持批量上报。 |
| size | 批量上报的数量。 | ||
| waitTimeMs | 批量上报，不足batchSize的时候，最大等待时间。 | ||
file | path | 保存日志的文件目录，需要保证文件的写权限，默认是 | file 模式下的配置；http 模式下，上报失败的报文记录在 |
| maxSize | 单个文件最大数量，默认是100m。 | ||
| maxBackup | 最大备份文件数量，默认是0，表示会保留所有文件。 | ||
| maxAge | 最大保存的天数，默认是0，表示会保留所有文件。 | ||
errPath | 上报失败保存日志的文件目录，需要保证文件的写权限，默认是 | ||
openapi | addr |
| 如果在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的方式进行上报。
使用前，需要先初始化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
参考代码：
https://github.com/volcengine/datarangers-sdk-go/tree/release/v2.0.1/_example
// 应用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)
如果服务端能够获取到client_ip，device_model等用户的设备信息，可以使用入参为Header的接口上报。否则默认情况下，对于事件的公共属性均为null或unknown。
SaaS 上用户属性需要先在系统中创建之后再上报，参考<<User Profile API (服务端-SaaS)>>
Item属性需要先在系统中创建之后再上报，参考<<业务对象（Item）数据接入（SaaS查看）>>