上传结构化日志

最近更新时间:2019-09-09 19:28:57

功能描述

本接口用于上传日志到指定的日志主题。

请求

请求示例

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

<LogGroupListPB 格式打包内容>
说明:

PB 描述文件格式以及编译步骤,请参阅 PB 编译示例

请求行

POST /structuredlog

请求头

除公共头部外,无特殊请求头部。

请求参数

字段名 类型 位置 必须 含义
topic_id string query 日志主题 ID ,表示数据上传的目标日志主题,可在 日志主题列表 查看日志主题 ID
logGroupList message pb 日志组列表,封装好的日志组列表内容

LogGroup 说明:

字段名 是否必选 含义
logs 日志数组,表示有多个 Log 组成的集合,一个 Log 表示一条日志,一个 LogGroup 中 Log 个数不能超过10000
contextFlow 保持上下文的 UID,该字段目前暂无效用
filename 日志文件名
source 日志来源,一般使用机器 IP 作为标识

Log 说明:

字段名 是否必选 含义
time 日志时间(UNIX格式时间戳),单位:毫秒、秒,建议使用毫秒,如果使用秒为单位请注意部分语言得到的是毫秒级,需要转换
contents key-value 格式的日志内容,表示一条日志里的多个 key-value 组合

Content 说明:

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

响应

响应示例

HTTP/1.1 200 OK
Content-Length: 0

响应头

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

响应参数

无。

错误码

参见 错误码

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 目录并进入该目录,执行命令如下:

[root@VM_0_8_centos]# 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结尾。
  • 由于 Protobuf 格式对键值对中的 key 名称没有唯一性要求,因此需要主动避免出现该情况,否则会影响正常使用。

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 LogGroup
{
    repeated Log    logs        = 1; // 多条日志合成的日志数组
    optional string contextFlow = 2; // 目前暂无效用
    optional string filename    = 3; // 日志文件名
    optional string source      = 4; // 日志来源,一般使用机器IP
}
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 头文件引入代码中,调用接口进行数据格式封装。