有奖捉虫:云通信与企业服务文档专题,速来> HOT

功能描述

本接口用于将日志写入到指定的日志主题。系统根据当前日志主题下所有可读写的分区,遵循负载均衡原则自动分配写入的目标分区。

示例

POST /structuredlog?topic_id=xxxxxxxx-xxxx-xxxx-xxxx HTTP/1.1
Host: <Region>.cls.tencentyun.com
Authorization: <AuthorizationString>
Content-Type: application/x-protobuf

<LogGroupList 的 PB 格式打包内容>

内外网域名

日志服务请求域名区分内外网形式:
内网域名格式形如${region}.cls.tencentyun.com ,内网域名仅对同地域访问生效,即云服务器或云产品通过内网域名访问相同地域的日志服务。
外网域名格式形如${region}.cls.tencentcs.com,访问源端接入 Internet 网后,正常情况均能访问日志服务外网域名。
region字段是日志服务区域简称,例如北京区域填写ap-beijing,完整区域列表格式参见 地域列表
ap-beijing - 北京
ap-shanghai - 上海
ap-guangzhou - 广州
ap-chengdu - 成都
...
此外日志服务还为用户提供以下两种不同的日志上传模式:
压缩上传模式
非压缩上传模式
使用压缩上传模式时,用户日志将在采集端先以 lz4 格式压缩,之后再将压缩完成后的日志数据上传到日志存储端。通过使用压缩上传模式,用户可以减少日志上传流量(日志写流量),从而节省费用。

示例

POST /structuredlog?topic_id=xxxxxxxx-xxxx-xxxx-xxxx HTTP/1.1
Host: <Region>.cls.tencentyun.com
Authorization: <AuthorizationString>
Content-Type: application/x-protobuf
x-cls-compress-type:lz4

<LogGroupList 的 PB 格式压缩包内容>
使用非压缩上传模式时,用户日志将以原始大小上传,相比于压缩上传模式,非压缩模式将会产生更高的日志写流量费用。

示例

POST /structuredlog?topic_id=xxxxxxxx-xxxx-xxxx-xxxx HTTP/1.1
Host: <Region>.cls.tencentyun.com
Authorization: <AuthorizationString>
Content-Type: application/x-protobuf

<LogGroupList 的 PB 格式打包内容>

签名方法

注意:
仅支持 v1 签名方法。
签名方法请参见 签名方法

请求

请求行

POST /structuredlog

请求头

x-cls-hashkey 请求头表示日志根据 hashkey 路由写入到 CLS 对应范围的主题分区,以保证写入到的每个主题分区是严格有序的,便于消费时有序消费。
字段名
类型
位置
是否必选
含义
x-cls-hashkey
string
header
根据 hashkey 写入相应范围的主题分区

请求参数

字段名
类型
位置
是否必选
含义
topic_id
string
query
日志主题 ID ,表示数据上传的目标日志主题,可在 日志主题列表 查看日志主题 ID
logGroupList
message
pb
logGroup 列表,封装好的日志组列表内容,建议 logGroup 数量不要超过5个
LogGroup 说明:
字段名
是否必选
含义
logs
日志数组,表示有多个 Log 组成的集合,一个 Log 表示一条日志,一个 LogGroup 中 Log 个数不能超过10000
contextFlow
保持上下文的 UID,该字段目前暂无效用
filename
日志文件名
source
日志来源,一般使用机器 IP 作为标识
logTags
日志的标签列表
Log 说明:
字段名
是否必选
含义
time
日志时间(Unix 格式时间戳),支持秒、毫秒,建议采用毫秒
contents
key-value 格式的日志内容,表示一条日志里的多个 key-value 组合
Content 说明:
字段名
是否必选
含义
key
单条日志里某个字段组的 key 值,不能以_开头
value
单条日志某个字段组的 value 值,单条日志 value 不能超过1MB,LogGroup 中所有 value 总和不能超过5MB
注意:
value 赋值必须为 string 类型。如果期望在日志检索分析时, value 被当作其他类型,例如 long 或者 double,可在为该字段配置键值索引时指定 value 类, 详情请参见 索引配置

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

响应

响应示例

HTTP/1.1 200 OK
Content-Length: 0

响应头

除公共响应头部外,无特殊响应头部。

响应参数

无。

错误码

参见 错误码

PB 编译示例

说明:
目前 protoc 官方支持 Java、C++、Python 等语言的编译,详情请参见 protoc
本示例将说明如何使用官方 protoc 编译工具将 PB 描述文件 编译生成为 C++ 语言可调用的上传日志接口。

1. 安装 Protocol Buffer

1. 下载 Protocol Buffer 。示例版本为 protobuf 2.6.1,环境为 Centos 7.3 系统。
wget https://main.qcloudimg.com/raw/d7810aaf8b3073fbbc9d4049c21532aa/protobuf-2.6.1.tar.gz
2. 解压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
3. 开始编译和安装,配置环境变量,执行命令如下:
./configure
make && make install
export PATH=$PATH:/usr/local/protobuf-2.6.1/bin
4. 编译成功后,您可以使用以下命令查看版本, 如果返回 liprotoc x.x.x则表示编译成功:
protoc --version

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 代码实现文件,如下图所示:




4. 调用

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