动态与公告

产品动态

公告

新手指引

产品简介

产品概述

产品优势

地域和访问域名

规格与限制

基本概念

购买指南

计费概述

产品定价

按量计费（后付费）

欠费说明

清理日志服务资源

成本优化

常见问题

快速入门

一分钟入门指南

入门指南

使用 Demo 日志快速体验 CLS

操作指南

资源管理

权限管理

日志采集

指标采集

日志存储

指标存储

检索分析（日志主题）

检索分析（指标主题）

仪表盘

数据处理

投递与消费

监控告警

云产品中心

DataSight 独立控制台

历史文档

实践教程

日志采集

检索分析

仪表盘

监控告警

投递和消费

成本优化

开发者指南

通过 iframe 内嵌 CLS（旧方案）

通过 Grafana 使用 CLS

API 文档

History

Introduction

API Category

Making API Requests

Topic Management APIs

Log Set Management APIs

Index APIs

Topic Partition APIs

Machine Group APIs

Collection Configuration APIs

Log APIs

Metric APIs

Alarm Policy APIs

Data Processing APIs

Kafka Protocol Consumption APIs

CKafka Shipping Task APIs

Kafka Data Subscription APIs

COS Shipping Task APIs

SCF Delivery Task APIs

Scheduled SQL Analysis APIs

COS Data Import Task APIs

Data Types

Error Codes

常见问题

健康监测问题解释

采集相关

检索分析相关

其他问题

服务等级协议

CLS 政策

隐私协议

数据处理和安全协议

联系我们

词汇表

使用 API 上传日志

PDF

聚焦模式

字号

最后更新时间： 2024-01-20 17:14:28

功能描述
本接口用于将日志写入到指定的日志主题。
日志服务提供以下两种模式：
负载均衡模式
哈希路由模式
系统根据当前日志主题下所有可读写的分区，遵循负载均衡原则自动分配写入的目标分区。该模式适合消费不保序的场景。
示例
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 - 成都
...
系统根据携带的哈希值（x-cls-hashkey）将数据写入到符合范围要求的目标分区。例如，可以将某个日志源端通过 hashkey 与某个主题分区强绑定，这样可以保证数据在该分区上写入和消费是严格保序的。
示例
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-hashkey: xxxxxxxxxxxxxxxxxxxxxxxx
﻿
<LogGroupList 的 PB 格式打包内容>
说明：
PB 描述文件格式以及编译步骤，请参阅 PB 编译示例。
﻿
此外日志服务还为用户提供以下两种不同的日志上传模式：
压缩上传模式
非压缩上传模式
使用压缩上传模式时，用户日志将在采集端先以 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 格式打包内容>
请求
请求行
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
LogTag 说明：
字段名
是否必选
含义
key
是
自定义的标签 key
value
是
自定义的标签 key 对应的 value 值
响应
响应示例
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结尾。
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 头文件引入代码中，调用接口进行数据格式封装。

帮助和支持

本页内容是否解决了您的问题？

您也可以联系销售或提交工单以寻求帮助。

填写满意度调查问卷，共创更好文档体验。

文档反馈

字段名	类型	位置	是否必须	含义
x-cls-hashkey	string	header	否	根据 hashkey 写入相应范围的主题分区

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

tencent cloud

日志服务

使用 API 上传日志

功能描述

示例

内外网域名

示例

示例

示例

请求

请求行

请求头

请求参数

响应

响应示例

响应头

响应参数

错误码

PB 编译示例

1. 安装 Protocol Buffer

2. 创建 PB 描述文件

3. 编译生成

4. 调用

帮助和支持