1. Golang SDK Usage Instructions

Before using, please read the data model introduction.

2. Integrating Sensors Analytics SDK

Integrate Sensors Analytics SDK into Golang code to collect and analyze user data using Sensors Analytics.

We recommend using the official Golang tool to manage Golang projects and obtain Sensors Analytics SDK:

go get github.com/sensorsdata/sa-sdk-go

Or update the existing SDK locally:

go get -u github.com/sensorsdata/sa-sdk-go

You can also download the source code of Sensors Analytics SDK from GitHub.

The SDK requires Golang 1.6 or above and does not depend on any third-party libraries.Currently, Golang SDK does not support Windows.

2.1. Initialize Sensors Analytics SDK

2.1.1. Get the configuration information

First, obtain the URL and Token for data receiving from the Sensors Analytics homepage (for Cloud version).

2.1.2. Initialize the SDK in the program

In the code snippet for initializing the program, construct an instance of the Sensors Analytics SDK, using ConcurrentLoggingConsumer as an example:

import sdk "github.com/sensorsdata/sa-sdk-go" // 从神策分析配置页面中获取数据接收的 URL SA_SERVER_URL := "YOUR_SERVER_URL" // 初始化一个 Consumer，用于数据发送 consumer, err := sdk.InitConcurrentLoggingConsumer("/data/sa/access.log", true) //... // 使用 Consumer 来构造 SensorsAnalytics 对象 sa := sdk.InitSensorsAnalytics(consumer, "default", false) defer sa.Close() properties := map[string]interface{}{ "price": 12, "name": "apple", } // 记录用户事件 err = sa.Track("ABCDEFG1234567", "ViewProduct", properties, false)

The user program should hold this instance until the program ends. Before the program exits, it needs to explicitly close using the Close() method, otherwise, some cached data may be lost.

When using Sensors Analytics, after importing the Sensors Analytics SDK, first initialize a consumer, and then initialize the Sensors Analytics object.

• The interface for initializing the Sensors Analytics object is:

// c 为 consumer，projectName 为项目名，timeFree 为是否导入历史数据 // 默认情况下，神策会过滤发生时间比较久远数据（例如 10 天之前，具体取决于服务端设置），如果想导入历史数据，可以通过开启 timeFree 选项来绕过这个限制。 func InitSensorsAnalytics(c consumers.Consumer, projectName string, timeFree bool) SensorsAnalytics

• Example

sa := sdk.InitSensorsAnalytics(consumer, "default", false) // 退出函数前调用 Close，回收资源，发送缓存中的数据 defer sa.Close() // ...

Now we can use the Sensors Analytics SDK normally. To learn more about SDK usage, you can jump to the section at the end of this article about controlling the Sensors Analytics SDK.

3. Set up Sensors Analytics SDK

The Golang SDK consists of the following two components:

• SensorsAnalytics: Interface object for sending data, the constructor requires a Consumer instance
• Consumer: The Consumer will perform actual data sending

In order to allow developers to access data more flexibly, the Sensors Analytics SDK implements the following Consumers:

• LoggingConsumer
• ConcurrentLoggingConsumer
• DebugConsumer
• DefaultConsumer
• BatchConsumer

3.1. LoggingConsumer (recommended)

Used to output data to a specified directory and split files by day, it supports specifying whether to split by hour through parameters. It is generally used to process real-time data, generate log files, and import them using tools like LogAgent.

• Initialization interface

// filename 为输出文件前缀，hourRotate 为是否按小时切割 func InitLoggingConsumer(filename string, hourRotate bool) (*consumers.LoggingConsumer, error)

• Example

import sdk "github.com/sensorsdata/sa-sdk-go" // 初始化 LoggingConsumer consumer, err := sdk.InitLoggingConsumer("/data/sa/access.log", false) // ... // 使用 Consumer 来构造 SensorsAnalytics 对象 sa := sdk.InitSensorsAnalytics(consumer, "default", false) defer sa.Close() // ...

The first parameter of LoggingConsumer is the prefix for saving files, and the second parameter indicates whether to enable splitting by hour. The default is to split by day at 0:00 and keep all files.

• When the splitting by hour is disabled, the file will be saved as prefix.YYYY-MM-DD (For example, assuming the prefix is /data/sa/access.log and the current date is 2018-04-13, the output file will be /data/sa/access.log.2018-03-13)
• When the splitting by hour is enabled, it will split at the beginning of each hour, and the file will be saved as prefix.YYYY-MM-DD.H (For example, assuming the prefix is /data/sa/access.log and the current time is 14:00 on 2018-04-13, the output file will be /data/sa/access.log.2018-03-13.14)

// 按小时切分 consumer, err := sdk.InitLoggingConsumer("/data/sa/access.log", true)

Note: Please do not use multiple processes to write to the same log file, as it may cause data loss or disorder. If you need to write with multiple processes, please use ConcurrentLoggingConsumer.

3.2. ConcurrentLoggingConsumer (recommended)

Used to output data to a specified directory and automatically split files by day. It supports splitting by hour as well. The meanings of the parameters are the same as LoggingConsumer. The difference is that it supports writing to the same file with multiple processes.

• Initialization Interface

// filename 为输出文件前缀，hourRotate 为是否按小时切割 func InitConcurrentLoggingConsumer(filename string, hourRotate bool) (*consumers.ConcurrentLoggingConsumer, error)

• Example

import sdk "github.com/sensorsdata/sa-sdk-go" // 初始化 ConcurrentLoggingConsumer consumer, err := sdk.InitConcurrentLoggingConsumer("/data/sa/access.log", true) // ... // 使用 Consumer 来构造 SensorsAnalytics 对象 sa := sdk.InitSensorsAnalytics(consumer, "default", false) // 程序结束前调用 Close() ，让 Consumer 刷新所有缓存数据到文件中 defer sa.Close() // ...

Note: The real_time_file_name parameter in the LogAgent configuration file must be commented out, otherwise the data cannot be imported correctly. Customers using LoggingConsumer are advised to switch to ConcurrentLoggingConsumer as follows:

• Step 1 Stop the LogAgent and comment out the real_time_file_name parameter in the LogAgent configuration.
• Step 2 Add the current time suffix ".YYYY-MM-DD" to the file with the real_time_file_name in the log directory.
• Step 3 Upgrade the backend program to switch to ConcurrentLoggingConsumer.
• Step 4 Restart the LogAgent.

3.3. DebugConsumer (for testing purposes)

Used to verify the correctness of data import. For more information about Debug mode, please go to the relevant page for details. Please note: Debug mode is a mode set up for developers to facilitate debugging. In this mode, the data is verified line by line, and an exception is thrown when the verification fails. The performance is much lower than normal mode. Using Debug mode in the online environment will seriously affect performance and may cause crashes. Please replace or close Debug mode before the product goes online.

• Initialization Interface

// url是接收端url，writeData表示是否校验数据，timeout是发送超时时间，单位是毫秒 // writeData为 // true - 校验数据，并将数据导入到神策分析中 // false - 校验数据，但不进行数据导入 func InitDebugConsumer(url string, writeData bool, timeout int) (*consumers.DebugConsumer, error)

• Example

import sdk "github.com/sensorsdata/sa-sdk-go" // 神策分析数据接收的 URL SA_SERVER_URL := "YOUR_SERVER_URL" // 发送数据的超时时间，单位毫秒 SA_REQUEST_TIMEOUT := 100000 // Debug 模式下，是否将数据导入神策分析 // true - 校验数据，并将数据导入到神策分析中 // false - 校验数据，但不进行数据导入 SA_DEBUG_WRITE_DATA := true // 初始化 Debug Consumer consumer, err := sdk.InitDebugConsumer(SA_SERVER_URL, SA_DEBUG_WRITE_DATA, SA_REQUEST_TIMEOUT) // ... // 使用 Consumer 来构造 SensorsAnalytics 对象 sa := sdk.InitSensorsAnalytics(consumer, "default", false) defer sa.Close() // ...

3.4. DefaultConsumer

Usually used in scenarios where small-scale historical data is imported. Since the data is sent directly over the network, if there is a network exception, it may cause data to be resent or lost. Therefore, it should not be used in any online service.Ordinary Consumer implementation that sends data to the receiving server line by line synchronously.

• Initialization Interface

// url 是接收端 URL，timeout 是发送超时时间，单位是毫秒 func InitDefaultConsumer(url string, timeout int) (*consumers.DefaultConsumer, error)

• Example

import sdk "github.com/sensorsdata/sa-sdk-go" // 神策分析数据接收的 URL SA_SERVER_URL := "YOUR_SERVER_URL" // 发送数据的超时时间，单位毫秒 SA_REQUEST_TIMEOUT := 100000 // 初始化 Default Consumer consumer, err := sdk.InitDefaultConsumer(SA_SERVER_URL, SA_REQUEST_TIMEOUT) // ... // 使用 Consumer 来构造 SensorsAnalytics 对象 sa := sdk.InitSensorsAnalytics(consumer, "default", false) defer sa.Close() // ...

3.5. BatchConsumer

Usually used to import small-scale historical data or offline/omni-directional import data scenarios. Since the data is sent directly over the network, if there is a network exception, it may cause data to be resent or lost. Therefore, it should not be used in any online service.Consumer that sends data in batches, only sends data when a specified amount of data is reached.

• Initialization Interface

// url是接收端url，max是最大缓存条数，timeout是发送超时时间，单位是毫秒 func InitBatchConsumer(url string, max, timeout int) (*consumers.BatchConsumer, error)

• Example

import sdk "github.com/sensorsdata/sa-sdk-go" // 神策分析数据接收的 URL SA_SERVER_URL := "YOUR_SERVER_URL" // 发送数据的超时时间，单位毫秒 SA_REQUEST_TIMEOUT := 100000 // 当缓存的数据量达到参数值时，批量发送数据 SA_BULK_SIZE := 100 // 初始化 Batch Consumer consumer, err := sdk.InitBatchConsumer(SA_SERVER_URL, SA_BULK_SIZE, SA_REQUEST_TIMEOUT) // ... // 使用 Consumer 来构造 SensorsAnalytics 对象 sa := sdk.InitSensorsAnalytics(consumer, "default", false) defer sa.Close() // ...

4. API Interface

For the documentation on the use of API interfaces, refer to the Introduction to Basic API Usage Documentation.