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的接口失敗