上传日志

1. 接口描述

接口请求域名： cls.tencentcloudapi.com 。

提示

为了保障您日志数据的可靠性以及更高效地使用日志服务，建议您使用CLS优化后的接口上传结构化日志。

同时我们给此接口专门优化定制了多个语言版本的SDK供您选择，SDK提供统一的异步发送、资源控制、自动重试、优雅关闭、感知上报等功能，使上报日志功能更完善，详情请参考SDK采集。

同时云API上传日志接口也支持同步上传日志数据，如果您选择继续使用此接口请参考下文。

功能描述

本接口用于将日志写入到指定的日志主题。

日志服务提供以下两种模式：

负载均衡模式

系统根据当前日志主题下所有可读写的分区，遵循负载均衡原则自动分配写入的目标分区。该模式适合消费不保序的场景。

哈希路由模式

系统根据携带的哈希值（X-CLS-HashKey）将数据写入到符合范围要求的目标分区。例如，可以将某个日志源端通过 hashkey 与某个主题分区强绑定，这样可以保证数据在该分区上写入和消费是严格保序的。

输入参数(pb二进制流，位于body中)

LogGroup 说明：

Log 说明：

Content 说明：

LogTag 说明：

PB 编译示例

本示例将说明如何使用官方 protoc 编译工具将 PB 描述文件 编译生成为 C++ 语言可调用的上传日志接口。

说明：

目前 protoc 官方支持 Java、C++、Python 等语言的编译，详情请参见 protoc。

1. 安装 Protocol Buffer

下载 Protocol Buffer ，解压并安装。示例版本为 protobuf 2.6.1，环境为 Centos 7.3 系统。 解压protobuf-2.6.1.tar.gz压缩包至/usr/local目录并进入该目录，执行命令如下：

tar -zxvf protobuf-2.6.1.tar.gz -C /usr/local/ && cd /usr/local/protobuf-2.6.1

开始编译和安装，配置环境变量，执行命令如下：

[root@VM_0_8_centos protobuf-2.6.1]# ./configure 
[root@VM_0_8_centos protobuf-2.6.1]# make && make install
[root@VM_0_8_centos protobuf-2.6.1]# export PATH=$PATH:/usr/local/protobuf-2.6.1/bin

编译成功后，您可以使用以下命令查看版本：

[root@VM_0_8_centos protobuf-2.6.1]# protoc --version
liprotoc 2.6.1

2. 创建 PB 描述文件

PB 描述文件是通信双方约定的数据交换格式，上传日志时须将规定的协议格式编译成对应语言版本的调用接口，然后添加到工程代码里，详情请参见 protoc 。

以日志服务所规定的 PB 数据格式内容为准， 在本地创建 PB 消息描述文件 cls.proto。

注意：

PB 描述文件内容不可更改，且文件名须以.proto结尾。

cls.proto 内容（PB 描述文件）如下：

package cls;

message Log
{
    message Content
    {
        required string key   = 1; // 每组字段的 key
        required string value = 2; // 每组字段的 value
    }
    required int64   time     = 1; // 时间戳，UNIX时间格式
    repeated Content contents = 2; // 一条日志里的多个kv组合
}

message LogTag
{
    required string key       = 1;
    required string value     = 2;
}

message LogGroup
{
    repeated Log    logs        = 1; // 多条日志合成的日志数组
    optional string contextFlow = 2; // 目前暂无效用
    optional string filename    = 3; // 日志文件名
    optional string source      = 4; // 日志来源，一般使用机器IP
    repeated LogTag logTags     = 5;
}

message LogGroupList
{
    repeated LogGroup logGroupList = 1; // 日志组列表
}

3. 编译生成

此例中，使用 proto 编译器生成 C++ 语言的文件，在 cls.proto 文件的同一目录下，执行如下编译命令：

protoc --cpp_out=./ ./cls.proto 

说明：

--cpp_out=./表示编译成 cpp 格式并输出当前目录下，./cls.proto表示位于当前目录下的 cls.proto 描述文件。

编译成功后，会输出对应语言的代码文件。此例会生成 cls.pb.h 头文件和 cls.pb.cc 代码实现文件，如下所示：

[root@VM_0_8_centos protobuf-2.6.1]# protoc --cpp_out=./ ./cls.proto
[root@VM_0_8_centos protobuf-2.6.1]# ls
cls.pb.cc cls.pb.h cls.proto

4. 调用

将生成的 cls.pb.h 头文件引入代码中，调用接口进行数据格式封装。

默认接口请求频率限制：100000次/秒。

注意：本接口只能使用 POST application/octet-stream 调用。

2. 输入参数

以下请求参数列表仅列出了接口请求参数和部分公共参数，完整公共参数列表见 公共请求参数。
注意：此接口仅支持 application/octet-stream 类型，只能使用签名方法 V3 调用，请求参数都放在请求头中。

3. 输出参数

4. 示例

示例1 上传日志

上传日志

输入示例

POST / HTTP/1.1
Host: cls.tencentcloudapi.com
Content-Type: application/octet-stream
X-TC-Action: UploadLog
<公共请求参数>

{
    "HashKey": "abc",
    "TopicId": "abc",
    "CompressType": "abc"
}

输出示例

{
    "Response": {
        "RequestId": "6ef60bec-0242-43af-bb20-270359fb54a7"
    }
}

5. 开发者资源

腾讯云 API 平台

腾讯云 API 平台 是综合 API 文档、错误码、API Explorer 及 SDK 等资源的统一查询平台，方便您从同一入口查询及使用腾讯云提供的所有 API 服务。

SDK

云 API 3.0 提供了配套的开发工具集（SDK），支持多种编程语言，能更方便的调用 API。

• Tencent Cloud SDK 3.0 for Python: GitHub Gitee
• Tencent Cloud SDK 3.0 for Java: GitHub Gitee
• Tencent Cloud SDK 3.0 for PHP: GitHub Gitee
• Tencent Cloud SDK 3.0 for Go: GitHub Gitee
• Tencent Cloud SDK 3.0 for .NET: GitHub Gitee
• Tencent Cloud SDK 3.0 for C++: GitHub Gitee

命令行工具

• Tencent Cloud CLI 3.0

6. 错误码

以下仅列出了接口业务逻辑相关的错误码，其他错误码详见 公共错误码。