日志服务
视频服务与安全产品捉虫活动邀您参加！> HOT
文档中心>日志服务>API 文档>日志相关接口>上传日志

上传日志

最近更新时间：2024-07-25 01:23:02

我的收藏

本页目录：

1. 接口描述

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

提示

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

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

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

功能描述

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

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

字段名 类型 位置 必须 含义
logGroupList message pb 是 logGroup 列表，封装好的日志组列表内容，建议 logGroup 数量不要超过5个

LogGroup 说明：

字段名 是否必选 含义
logs 是 日志数组，表示有多个 Log 组成的集合，一个 Log 表示一条日志，一个 LogGroup 中 Log 个数不能超过10000
contextFlow 否 LogGroup 的唯一ID，需要使用上下文功能时传入。格式："{上下文ID}-{LogGroupID}"。
上下文ID：唯一标识一个上下文（连续滚动的一系列日志文件，或者是需要保序的一系列日志），16进制64位整型字符串。
LogGroupID：连续递增的一串整型，16进制64位整型字符串。样例："102700A66102516A-59F59"。
filename 否 日志文件名
source 否 日志来源，一般使用机器 IP 作为标识
logTags 否 日志的标签列表

Log 说明：

字段名 是否必选 含义
time 是 日志时间（Unix 格式时间戳），支持秒、毫秒，建议采用毫秒
contents 否 key-value 格式的日志内容，表示一条日志里的多个 key-value 组合

Content 说明：

字段名 是否必选 含义
key 是 单条日志里某个字段组的 key 值，不能以_开头
value 是 单条日志某个字段组的 value 值，单条日志 value 不能超过1MB，LogGroup 中所有 value 总和不能超过5MB

LogTag 说明：

字段名 是否必选 含义
key 是 自定义的标签 key
value 是 自定义的标签 key 对应的 value 值

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 调用，请求参数都放在请求头中。

参数名称 必选 类型 描述
X-TC-Action 是 String 公共参数，本接口取值：UploadLog。
X-TC-Version 是 String 公共参数，本接口取值：2020-10-16。
X-TC-Region 是 String 公共参数，详见产品支持的 地域列表。
X-CLS-TopicId 是 String 主题id
示例值：f6c4fa6f-367a-4f14-8289-1ff6f77ed975
X-CLS-CompressType 否 String 压缩方法
示例值：lz4

3. 输出参数

参数名称 类型 描述
RequestId String 唯一请求 ID，由服务端生成，每次请求都会返回（若请求因其他原因未能抵达服务端，则该次请求不会获得 RequestId）。定位问题时需要提供该次请求的 RequestId。

4. 示例

示例1 上传日志

上传日志

输入示例

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

{
    "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。

命令行工具

6. 错误码

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

错误码 描述
FailedOperation 操作失败。
FailedOperation.MissingContent 无效的Content。
FailedOperation.ReadQpsLimit 读qps超过限制。
FailedOperation.TopicClosed 日志主题已关闭。
FailedOperation.TopicIsolated 日志主题已隔离。
FailedOperation.WriteQpsLimit 写qps超过限制。
FailedOperation.WriteTrafficLimit 写流量超过限制。
InternalError 内部错误。
InvalidParameter 参数错误。
InvalidParameter.Content 无效的Content。
LimitExceeded.LogSize 日志大小超过限制。
LimitExceeded.Tag tag超过限制。
MissingParameter 缺少参数错误。
OperationDenied 操作被拒绝。
OperationDenied.ACLFailed ACL校验失败。
OperationDenied.AccountDestroy 账户已销毁。
OperationDenied.AccountIsolate 账户欠费。
OperationDenied.AccountNotExists 账户不存在。
ResourceNotFound.PartitionNotExist 分区不存在。
ResourceNotFound.TopicNotExist 日志主题不存在。
UnsupportedOperation 操作不支持。
中国站
文档反馈
文档活动
message-icon联系我们
目录