1. 前言

安装使用C++ SDK可以帮助开发者快速接入使用天翼云的日志服务相关功能。

2. 使用条件

2.1. 先决条件

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

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

2、已获取AccessKey 和 SecretKey。

3、已安装c++ 运行环境，推荐安装c++11或以上版本。

2.2. 下载及安装

从官方渠道下载ctyun_lts_cpp_sdk.zip压缩包，放到相应位置后并解压。“ctyun_lts_cpp_sdk”目录中sample_putlogs.cpp为SDK的使用示例代码。

2.1.1. 依赖

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

libcurl-devel   (7.6.1)
openssl-devel  (1.1.1)
protobuf       (3.5.0)
lz4            (v1.8.3)
boost          (1.66.0)

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

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

2.1.2. 编译使用

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

2、执行以下命令：

mkdir build
cd build
cmake .. -DCMAKE_INSTALL_PREFIX=..
make
make install

其中make 主要做的工作有：为.proto文件生成对应的.pb.cc、.pb.h，以及编译出静态库文件libltssdk.a。

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

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

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

g++ sample_putlogs.cpp -I./include -L./lib/ -lcurl -lcrypto -llz4 -lprotobuf -lltssdk

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

make sample_putlogs

6、执行可执行文件。

./sample_putlogs

3. SDK使用设置

3.1. 基本使用

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

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

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

3、日志项目编码：logProject，在使用SDK前，需要确保您有至少一个已经存在的日志项目，日志项目就是您要将日志上传到的地方。

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

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

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

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

示例代码：同步上传

int main(int argc, char **argv)
{
    string ak =  "your accessKey";   
    string sk =  "your secretKey";   
    string logProject = "log project Code";  
    string logUnit = "log unit Code";       
    string endpoint = "endpoint";          
    int log_num = 10;  //每次发送10条日志

    vector<LogItem> logItems;
    for (int k = 0; k < log_num; k++)
    {
        int64_t logTimestamp = GetCurrentTimeStamp(3);
        string oriMessage = "c++ sdk test oriMessage";
        map<std::string, boost::any> contents;
        map<std::string, boost::any> labels;
        contents["level"] = string("error");
        contents["unit_id"] = 3.1415926;
        labels["user_tag"] = string("string");
        LogItem logItem;
        logItem.logTimestamp = logTimestamp;
        logItem.oriMessage = oriMessage;
        logItem.contents = contents;
        logItem.labels = labels;
        logItems.push_back(logItem);
    }

    try
    {
        Client *client = new Client(endpoint, ak, sk);
        for (int i = 0; i < 100; i++)
        { // 发送100次
            PutLogResponse logResponse = client->PutLogs(logProject, logUnit, logItems);
            cout << "statusCode:" << logResponse.statusCode << ", message:" << logResponse.message << ", error:" << logResponse.error << endl;
        }
        cout << "send all success" << endl;
    }
    catch (LOGException &e)
    {
        cout << e.GetExceptionErrorCode() << ":" << e.GetExceptionMessage() << endl;
    }
}

示例代码：异步批量上传

int main(int argc, char **argv)
{
    string ak =  "your accessKey";
    string sk =  "your secretKey";
    string logProject = "log project Code";
    string logUnit = "log unit Code";
    string endpoint = "endpoint";
    int log_num = 10;  //每次发送10条日志

    vector<LogItem> logItems;
    for (int k = 0; k < log_num; k++)
    {
        int64_t logTimestamp = GetCurrentTimeStamp(3);
        string oriMessage = "c++ sdk test oriMessage";
        map<std::string, boost::any> contents;
        map<std::string, boost::any> labels;
        contents["level"] = string("error");
        contents["unit_id"] = 3.1415926;
        labels["user_tag"] = string("string");

        LogItem logItem;
        logItem.logTimestamp = logTimestamp;
        logItem.oriMessage = oriMessage;
        logItem.contents = contents;
        logItem.labels = labels;
        logItems.push_back(logItem);
    }
    try
    {
        ProducerConfig producerConfig = ProducerConfig();                    //使用默认producer配置
        ClientConfig clientConfig(endpoint, ak, sk, logProject);//可使用不同client配置，生成多个client,如果希望使用同一个，logProject默认设置为"" 即可
        Client *client =  createClient(clientConfig); 
        map<string, Client *> clientPool;
        clientPool.insert(make_pair(client->GetLogProject(), client));

        IoWorker ioWorker(clientPool, producerConfig.getMaxWorkerCount());    //线程池
        LogAccumulator logAccumulator(producerConfig, ioWorker);              //日志累加器
        Mover mover(logAccumulator, ioWorker, producerConfig.getLingerMs());  //定时器
        Producer producer(producerConfig, ioWorker, logAccumulator, mover);   //日志发送器
        producer.start();   

        for (int i=0;i<5000;i++){
            producer.sendLogsCallback(logProject,logUnit,logItems);
        }
        std::this_thread::sleep_for(std::chrono::milliseconds(5000));
        for (int i = 0; i < 5000; i++)
        {
            producer.sendLogsCallback(logProject, logUnit, logItems);
        }
        std::this_thread::sleep_for(std::chrono::milliseconds(3000));
        producer.safeClose();
    }
    catch (exception &e)
    {
        cout<<e.what()<<endl;
    }
}

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

4.1. 关于Client的操作

此操作是初始化Client。用户需要配置至少3个关键的参数才够初始化Client。初始化Client之后，其包含的配置信息如下：

 示例代码：初始化Client配置

Client *client = new Client(endpoint, ak, sk);
//或者
ClientConfig clientConfig(endpoint, ak, sk);
Client *client = createClient(clientConfig); 

4.2. 关于Log的操作

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

LogItem类型的日志格式如下如下。

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

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

vector<LogItem> logItems;
for (int k = 0; k < 10; k++) {
   int64_t logTimestamp = GetCurrentTimeStamp(3);
   string oriMessage = "c++ sdk test oriMessage";
   map<std::string, boost::any> contents;
   map<std::string, boost::any> labels;
   contents["level"] = string("error");
   contents["unit_id"] = 3.1415926;
   labels["user_tag"] = string("string");
   LogItem logItem;
   
     logItem.logTimestamp = logTimestamp;
     logItem.oriMessage = oriMessage;
     logItem.contents = contents;
     logItem.labels = labels;
     logItems.push_back(logItem);
}

4.3. 关于日志上传的操作

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

示例代码：上传日志

LogResponse logResponse = client->PutLogs(logProject, logUnit, logItems);
cout<<logResponse.statusCaode<<":"<<logResponse.message<<":"<<logResponse.error<<endl;

logResponse 是LogResponse 格式的返回响应体，如下表格式：

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