1. 前言

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

2. 使用条件

2.1. 先决条件

用户需要具备以下条件才能够使用LTS SDK C版本：

1、购买并订阅了天翼云的云日志服务，并创建了日志项目和日志单元，获取到相应编码（logProject、logUnit）。

2、已获取AccessKey 和 SecretKey。

3、已安装C 运行环境。

2.2. 下载及安装

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

2.2.1. 依赖

cmake2.8或更新版本，GCC 4.9或更新版本。以下库及其相关头文件，可在对应Linux发行版的包管理器中安装，括号中给出的是经过验证的版本。

libcurl-devel   (7.6.1)
openssl-devel   (1.1.1k)
protobuf-c      (1.3.0-6.el8)
lz4             (v1.8.3)
json-c          (0.13.1-2.el8)

对于 CentOS 安装，可用如下命令搭建依赖环境。

yum install gcc-c++
yum install cmake
yum install libcurl-devel openssl-devel libuuid-devel 
yum install lz4-devel.x86_64
yum install protobuf-c-devel.x86_64
yum install json-c-devel.x86_64

2.2.2. 编译使用

1、进入ctyun_lts_c_sdk目录下，里面有CMakelists.txt文件。

2、执行build.sh，其包含以下命令。

!#bin/bash

# generate .pb-c.c  .pb-c.h  from .proto
protoc-c --proto_path=./protoc --c_out=./ common.proto resource.proto logs.proto
echo "generate 6 file (common|resource|logs).(pb-c.c|pb-c.h)"

mkdir build
cd build
rm -rf *

# cmake install location is ..
cmake .. -DCMAKE_INSTALL_PREFIX=..
make
make install

其中make 主要做的工作有：为.proto文件生成对应的.pb-c.c、.pb-c.h，以及动态链接构建出库文件libltssdk.a，存放在lib目录下。

3、将ctyun_lts_c_sdk目录下的头文件，全部移动到您项目的对应目录下，（如果直接使用SDK 则可以不用移动）。

4、之后你就可以在你的项目内使用SDK了，只需要引入对应的头文件即可。

5、编译您的程序，在您目录下内编译您的程序，构建出可执行文件， 如sample_putlogs.c。

gcc sample_putlogs.c -o sample_putlogs -I./ -L./lib/ -lltssdk -lssl -llz4 -lcurl -lprotobuf-c -lcrypto  -ljson-c

或者 根据主目录中的Makefile 文件。执行以下命令,也能实现上面的构建出可执行文件。

make sample_putlogs

6、执行你的可执行文件。

./sample_putlogs

3. SDK使用设置

3.1. 基本使用

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

• 云日志服务访问地址。详情请查看访问地址（Endpoint）。
• key凭证：accessKey和secretKey 。详情请查看如何获取访问密钥（AK/SK）。
• 日志项目编码：logProject，在使用SDK前，需要确保您有至少一个已经存在的日志项目。
• 日志单元编码：logUnit，在使用SDK前，需要确保日志项目中有至少一个已经存在的日志单元。
• 待上传的日志：logItem，在使用SDK前，需要确保日志已按照特定格式组织。

参数	参数类型	描述	是否必须
endpoint	string	域名	是
accessKey	string	AccessKey，简称ak	是
secretKey	string	SecretKey ，简称sk	是
logProject	string	日志项目编码	是
logUnit	string	日志单元编码	是

示例代码：SDK使用示例

#include <stdio.h>
#include <stdlib.h>
#include "log_config.h"
#include "log_item.h"
#include "log_client.h"
#include "log_response.h"
int main(void) {
char *accessKey = "your accessKey";
    char *secretKey = "your secretKey";
    char *endpoint = "endpoint";    
    char *logProject = "log project Code";
    char *logUnit = "log unit Code";
    
    Client *client = Client_new(endpoint,accessKey,secretKey);
    if (client == NULL)
    {
        printf("client init failed\n");
        return 0;
    }
    int log_size=10; //send 10 logs once
    LogItems *logItems = LogItems_new(log_size);
    for (size_t i = 0; i < log_size; i++){
        LogItem *logItem = LogItem_new("c sdk test messgae."); 
        LogItem_add_int_content(logItem,"content_int",10);
        LogItem_add_double_content(logItem,"content_double",3.1415);
        LogItem_add_string_content(logItem,"content_string","info");
        LogItem_add_string_label(logItem,"user_tag","string");
        LogItems_add_logitem(logItems,logItem);
    }
   for (size_t i = 0; i < 10; i++){    //send 10 times
        LogResponse *response = Client_putlogs(client,logProject,logUnit,logItems);
    if(response != NULL) {
            printf("%d , response :statusCode:%s , message:%s ,  error:%s\n",i,response->statusCode,response->message,response->error);
        }
        else {
            printf("response is null");
        }
        LogResponse_free(response);
    }
    LogItems_free(logItems);
    Client_free(client);
    return 0;
}

4. LTS服务代码示例

4.1. 关于Client的操作

4.1.1 Client_new

此操作是使用config去初始化client，client包含的配置信息如下：

参数	参数类型	描述	是否必须
endpoint	char*	域名	是
accessKey	char*	AccessKey，简称ak	是
secretKey	char*	SecretKey ，简称sk	是
userAgent	char*	使用的SDK信息标识	否
requestTimeout	int	http请求超时时间，默认30s	否
compressType	int	日志压缩算法	否
securityToken	TokenInfo*	获取的token信息	否
httpCurl	CURL*	定义的CURL ，用于http请求	否

示例代码：初始化创建Client

 Client *client = Client_new(endpoint,accessKey,secretKey);

4.1.2. Client_getToken

此操作是为client注入token信息，这一步需要使用ak和sk信息换取临时凭证TokenInfo，其中包含了token随机串和过期时间两个参数。这一步需要去访问CTIAM的api接口，调用api接口，传入ak/sk/endpoint信息，返回token信息。

TokenInfo信息如下：

参数	类型	描述
token	char*	token 随机串
expireTime	long long	过期时间，默认30分钟

获取TokenInfo这一步在Client 初始化时会自动调用。用户默认可以不用进行这一步操作。

4.2. 关于Log的操作

4.2.1. logItem_new

此操作用于生成待上传的日志，其中LogItem

参数	类型	描述	是否必须
logTimestamp	int64_t	时间戳，单位纳秒	是
oriMessage	char*	原始日志内容	是
contents_key	char **	contents的key，数组类型	否
contents_types	ValueType*	contents 的类型：int,double,char*	否
contents_values	void **	contents的value，数组类型	否
contents_size	size_t	contents key，value的 数组大小	否
labels_key	char **	labels的key，数组类型	否
labels_types	ValueType*	labels的类型：int,double,char*	否
labels_values	void **	labels的value，数组类型	否
labels_size	size_t	labels key，value的 数组大小	否

ValueType格式指示的是value值的类型：

typedef enum {
    VALUE_TYPE_STRING,
    VALUE_TYPE_INT,
    VALUE_TYPE_DOUBLE,
} ValueType;

4.2.2 LogItems_new

LogItems是Logitems 的数组类型，里面可以包含若干条日志，client可以一次性上传多条日志，如下：

参数	类型	描述	是否必须
items	LogItem* *	LogItem 数组类型	是
items_size	size_t	LogItem 数组的大小	是
max_items	size_t	LogItem 数组的最大大小	是

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

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

int log_size=10;
LogItems *logItems = LogItems_new(log_size);
for (size_t i = 0; i < log_size; i++){
    LogItem *logItem = LogItem_new("c sdk test messgae."); 
    LogItem_add_int_content(logItem,"content_int",10);
    LogItem_add_double_content(logItem,"content_double",3.1415);
    LogItem_add_string_content(logItem,"content_string","info");
    LogItem_add_string_label(logItem,"user_tag","string");
    LogItems_add_logitem(logItems,logItem);
}

4.3. 关于日志上传的操作

4.3.1. Client_putlogs()

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

参数	类型	描述	是否必须
logProject	char*	日志项目编码	是
logUnit	char*	日志单元编码	是
logItems	LogItems*	日志数据（多条）	是

示例代码：上传日志

LogResponse *response = Client_putlogs(client,logProject,logUnit,logItems);

4.3.2. Client_putlogs_once()

此操作用于日志上传服务，需要传入的参数有三个，分别是logProject(日志项目编码)，logUnit(日志单元编码)，logItem（要上传的日志）。类似与putlogs，但是putlogs_once只上传一条日志。

参数	类型	描述	是否必须
logProject	char*	日志项目编码	是
logUnit	char*	日志单元编码	是
logItem	LogItem*	日志数据（单条）	是

LogItem *logItem = LogItem_new("c sdk test messgae.");
LogResponse *response = Client_putlogs(client,logProject,logUnit,logItem);

4.3.3. LogResponse

logResponse 是putlogs方法的返回响应体，如下表格式：

参数	类型	描述	示例
statusCode	char*	返回码，取值范围：0：-正常、-1：严重错误,其他自定义
message	char*	状态描述	SUCCESS
error	char*	参考错误编码列表

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

statusCode	error	message
-1	LTS_8000	请求失败，请稍候重试，或提交工单反馈
-1	LTS_8001	内容不合法，无法解析
-1	LTS_8004	日志内容包含的日志必须小于[x] MB和[y]条
-1	LTS_8006	日志内容解压失败
-1	LTS_8007	Token失效，请重新获取
-1	LTS_8009	无云日志服务产品实例，请先开通云日志服务
-1	LTS_8010	日志项目不存在
-1	LTS_8011	日志单元不存在
-1	LTS_8013	在1个日志项目下,写入流量最大限制:200MB/s
-1	LTS_8014	在1个日志项目下,写入次数最大限制:1000次/s
-1	LTS_8015	在1个日志单元下,写入流量最大限制:100MB/s
-1	LTS_8016	在1个日志单元下,写入次数最大限制:500次/s
-1	LTS_18000	调用ITIAM的接口失败