1. 前言

安装使用Go SDK可以帮助开发者快速接入使用天翼云的日志服务相关功能，目前支持同步上传，异步批量上传等功能。

2. 使用条件

2.1. 先决条件

用户需要具备以下条件才能够使用云日志服务 SDK Go版本：

1、已开通云日志服务，并创建了日志项目和日志单元，获取到相应编码（logProject、logUnit）。

2、已获取AccessKey 和 SecretKey。

3、已安装Go开发环境，推荐安装Go1.19或以上版本。

2.2. 下载及安装

下载压缩包，放到相应位置后并解压。“ctyun_lts_go_sdk”目录中“example”为SDK的使用示例代码。

1、将解压后的代码包的"lts"目录整个复制到您的项目中。

2、更新依赖项，在您的go项目中执行命令：

go mod tidy 

3、当您的代码中要使用SDK时，在代码的import中，添加lts包。假设您的项目为lts_sdk_go_demo，则进行如下操作。这样您就可以顺利使用SDK的功能：

import(
    "lts_sdk_go_demo/lts"
)

如果您想直接使用SDK，则可以进行如下步骤处理：

4、进入到ctyun_lts_go_sdk 目录下，删除go.mod 、go.sum文件。

5、执行命令，初始化您的项目：

go mod init ctyun_lts_go_sdk ;

6、接着执行命令：

go mod tidy 

7、进入example目录下，运行sample_putlogs.go示例

go run sample_putlogs.go

8、或者进入example目录下，构建您的go项目，执行命令，以生成二进制文件。

go build -o sample_putlogs  sample_putlogs.go       (linux 环境)
go build -o sample_putlogs.exe  sample_putlogs.go    (windows 环境)

9、运行sample_putlogs示例：

./sample_putlogs         (linux 环境)
sample_putlogs.exe       (windows 环境)

3. SDK基本使用

3.1. 基本使用

使用 SDK访问云日志服务，需要设置正确的 AccessKey、SecretKey 和endpoint，所有的服务可以使用同一 key 凭证来进行访问，但不同的服务地区需要使用不同的 endpoint 进行访问，详情参考天翼云官网-SDK接入概述。在调用前SDK，需要已知以下参数：

• 云日志服务访问地址。详情请查看访问地址（Endpoint）。

• key凭证：accessKey和secretKey 。详情请查看如何获取访问密钥（AK/SK）。

• 日志项目编码：logProject，在使用SDK前，需要确保您有至少一个已经存在的日志项目。

• 日志单元编码：logUnit，在使用SDK前，需要确保日志项目中有至少一个已经存在的日志单元。

• 待上传的日志：logItem，在使用SDK前，需要确保日志已按照特定格式组织。

目前通过SDK将日志上传有两种上传形式：同步上传和异步批量上传，详细文档参考代码内README文件。

1、同步上传：当调用日志上传接口时，sdk会立即进行http请求调用，并返回发送结果。这种方式结构简单，可用于发送频率不高的场景。

2、异步批量上传：当调用日志上传接口时，后台线程会将日志进行累积，当达到发送条件时，会进行一次合并发送。对于需要频繁调用发送接口的场景，这种方式性能更卓越，更高效。

示例代码：同步上传

import (
	"ctyun_lts_go_sdk/lts"
	"fmt"
	"time"
)
func main() {
	ak := "your accessKey"
	sk := "your secretKey"
	logProject := "log project Code"
	logUnit := "log unit Code"
	endpoint := "https://xxx-lts.ctyun.cn"
	clientConfig := lts.InitClientConfig(endpoint, ak, sk)
	client, err := lts.CreateClient(clientConfig)
	if err != nil {
		fmt.Println("client initialization failed, err:", err)
		return
	}
	logTimestamp := time.Now().UnixNano()
	originMsg := "go sdk test oriMessage"
	contents := make(map[string]any)
	contents["contentInt"] = logTimestamp
	contents["contentString"] = "contents test string"
	contents["contentDouble"] = 3.1415926
	contents["contentBool"] = "true"
	labels := make(map[string]any)
	labels["user_tag"] = "string"
	logItem := lts.GenerateLogItem(logTimestamp, originMsg, contents, labels)
	logItems := lts.NewLogItems()
	for i := 0; i < 10; i++ {
		logItems.AddLogItem(logItem)
	}
	for j := 0; j < 100; j++ {
		response, err := client.PutLogs(logProject, logUnit, logItems)
		if err != nil {
			fmt.Println("Put log failed: ", err)
		} else {
			fmt.Println("Response message: ", response.Message)
		}
	}}

示例代码：异步批量上传

import (
	"ctyun_lts_go_sdk/lts"
	"ctyun_lts_go_sdk/lts/producer"
	"fmt"
	"time"
)
func main() {
	ak := "your accessKey"
	sk := "your secretKey"
	logProject := "log project Code"
	logUnit := "log unit code"
	endpoint := "your endpoint"

	producerConfig := producer.GetDefaultProducerConfig() //使用默认配置
	producerConfig.AllowLogLevel = "warn"                 //也可自定义设置
	producerConfig.LingerMs = 2000
	producerInstance := producer.InitProducer(producerConfig)

	// 可以根据clientConfig 创建多个client,client间互不影响
	clientConfig := lts.InitClientConfig(endpoint, ak, sk)

	err := producerInstance.BuildClient(clientConfig)
	if err != nil {
		fmt.Println("client initialization failed, err:", err)
		return
	}

	//启动后台的异步线程
	producerInstance.Start()

	for i := 0; i < 1000; i++ {
		err = producerInstance.SendLogs(logProject, logUnit, GenerateLog()) //不接收发送结果，不返回每条日志发送结果
		//err = producerInstance.SendLogsWithCallBack(logProject2, logUnit2, GenerateLog()) //接受每条日志发送结果，回调

		if err != nil {
			fmt.Println(err)
		}
	}

	fmt.Println("Send completion")
	//SafeClose会等待所有任务结束
	producerInstance.SafeClose()
}

4. 服务代码示例-同步上传

4.1. 关于Client的操作

此操作是获取Client的默认配置。至少需要4个关键的参数，config配置如下：

示例代码：获取创建client

clientConfig := lts.InitClientConfig(endpoint, ak, sk)
//也可以进行自定义参数值
clientConfig.RequestTimeOut=30 * time.Second
clientConfig.UserAgent=”log-sdk-go/1.6.0’

client, err := lts.CreateClient(clientConfig)

4.2. 关于Log的操作

此操作用于生成待上传的日志，日志上传只能上传LogItem格式的日志，logItems是一个数组类型，里面包含若干条LogItem日志，格式如下：

其中LogItem类型需要的参数如下：

注意：单条日志长度最大限制为1MB，单个包最大限制为5MB，其中Contents和Labels的key的长度不超过64字符，仅支持数字、字母、下划线、连字符(-)、点(.),且必须以字母开头。value类型最好使用字符串（string）和数字类型（int,double），其他类型建议先转为字符串类型，并且value值不能为空或空字符串。

示例代码：组装生成1条日志

logTimestamp := time.Now().UnixNano()
originMsg := "go sdk test oriMessage"
contents := make(map[string]any)
contents["contentInt"] = logTimestamp
contents["contentString"] = "contents test string"
contents["contentDouble"] = 3.1415926
contents["contentBool"] = "true"
labels := make(map[string]any)
labels["user_tag"] = "string"
logItem := lts.GenerateLogItem(logTimestamp, originMsg, contents, labels)
logItems := lts.NewLogItems()
logItems.AddLogItem(logItem)

//如果只需要日志原文,构造一条日志
logItem := lts.GenerateLogItemWithM(originMsg)

//如果只需要日志原文和分词,构造一条日志
logItem := lts.GenerateLogItemWithMC(originMsg,contents)

4.3. 关于日志上传的操作

此操作用于日志上传服务，需要传入的参数有三个，分别是logProject(日志项目编码)，logUnit(日志单元编码)，logItems（要上传的日志）。

示例代码：上传日志,默认使用lz4压缩

response, err := client.PutLogs(logProject, logUnit, logItems) 
if err != nil {
     fmt.Println("Put log failed: ", err.Error())
} else {
     fmt.Println("message: ", response.Message)
}

response 是Response格式的返回响应体，如下表格式：

日志服务相关错误编码(部分):