更新时间: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查看)>>