文档中心

PutLogs

最近更新时间：2023.11.13 16:31:27

首次发布时间：2022.05.11 11:26:48

调用 PutLogs 接口上传日志到指定的日志主题中。

使用说明

本接口用于将结构化日志上传到指定的日志主题中。目前仅支持写入 PB 格式（Protocol Buffer）的日志数据，日志数据以日志组（LogGroup）的形式展示。日志服务 PB 格式请参考数据编码方式。
上传日志时支持通过负载均衡模式和 HashKey 路由 Shard 模式写入。

HashKey 路由 Shard 模式：写入日志时，将数据有序写入到指定 Shard 中。适用于数据写入和消费对有序性要求较高的场景。例如，可以将某个生产者根据名称 Hash 固定到 Shard 上，这样就能保证写入与消费在该 Shard 上的数据是严格有序的，在合并、分裂过程中能够严格保证对于 Key 在一个时间点只会出现在一个 Shard 上。
此时需要设置 HashKey，日志服务会将数据写入到包含该 Key 值的 Shard 中。HashKey 的取值范围为 [00000000000000000000000000000000-ffffffffffffffffffffffffffffffff)。
负载均衡模式：自动根据负载均衡原则将数据包写入当前可用的任一 Shard 中。该模式适用于写入和消费行为与 Shard 无关的场景，例如不保序。

日志上传相关的接口（PutLogs、WebTracks）共用一个调用频率和流量限制的额度，具体限制如下：

接口的总请求频率限制为 500 次/Shard/秒，超出请求频率限制会报错 ExceedQPSLimit。
接口的总流量限制为 5MiB/Shard/s，每个 Shard 中日志解压后的流量限制为 30MiB/s，超出流量限制会报错 ExceedRateLimit。大流量场景下建议开启 Shard 自动分裂，以免影响数据写入效率。

说明

一个 LogGroupList 不可超过 5MiB，每次可以写入的原始日志大小上限为 5MiB，日志组中每条日志不超过 1MiB，一个 LogGroup 中 Log 个数不能超过 10000 条。服务端会对每次 PutLogs 请求写入的日志数据进行长度检查，如果超出限制则整个请求失败且无任何日志数据成功写入。
配置字段的键值索引时，如果未开启统计、未配置分词符且未开启包含中文，或未开启统计时，字段长度不可超过 32KiB，否则索引创建失败。

URI

请求方法	POST
URI	`https://tls-{Region}.ivolces.com/PutLogs`
传输协议	HTTPS

请求头

参数	参数类型	是否必选	示例值	说明
Content-Type	String	必选	application/x-protobuf	日志内容的格式。需要设置为`application/x-protobuf`，表示使用 PB 格式上传日志。
x-tls-bodyrawsize	String	必选	1024	请求体的原始大小（压缩前），单位为 Byte。
x-tls-hashkey	String	可选	7fffffffffffffffffffffffffffffff	日志组的 HashKey，用于指定当前日志组要写入的分区（Shard）。未设置此参数，表示使用默认的负载均衡模式写入日志，将数据包写入当前可用的任一 Shard 中。设置此参数表示采集日志时使用 HashKey 路由 Shard 模式，日志服务会将数据写入到包含指定 Key 值的 Shard 中。此参数的取值范围为 [00000000000000000000000000000000-ffffffffffffffffffffffffffffffff)。
x-tls-compresstype	String	可选	lz4	请求体的压缩格式。默认不压缩。支持设置为： lz4：压缩格式为 lz4。 zlib：压缩格式为 zlib。如果通过 Windows SDK 上传日志，仅支持使用 zlib 压缩格式。

URI请求参数

参数	类型	是否必选	示例值	描述
TopicId	String	是	4a*********	日志主题 ID。

Body请求参数

说明

日志服务 PB 格式请参考数据编码方式。

参数	类型	是否必选	示例值	描述
LogGroupList	Message	是	true	LogGroup 列表，其中包括封装好的日志组列表内容。说明 LogGroupList 的总大小不能超过 5MiB。

LogGroup 说明：

参数	类型	是否必选	描述
Logs	repeated Log	必选	日志数组，由一个或多个 Log 组成，每个 Log 表示一条日志。说明一个 LogGroup 中 Log 数量不能超过 10000。
Filename	String	可选	日志文件名。
Source	String	可选	日志来源，通常使用机器 IP 作为标识。
LogTags	repeated LogTag	可选	日志组（LogGroup）的自定义标签字段（LogTag）列表，由一个或多个 LogTag 组成。设置 LogTags 之后，日志服务会为该 PutLogs 请求传入的所有日志内容添加该标签字段。

Log 说明：

参数	类型	是否必选	描述
Time	Integer	必选	日志时间，格式为 Unix 格式时间戳，支持秒或毫秒，建议采用毫秒。
Contents	repeated LogContent	可选	日志内容，由一个或多个 LogContent 组成，每个 LogContent 为一条日志里的 key-value 键值对集合。

Content 说明：

参数	类型	是否必选	描述
Key	String	必选	单条日志里某个字段组的 key 值。 Key 为 UTF-8 编码字符串，支持字母、数字、空格、下划线（）、连字符（-）和斜线（/），并且不支持以下划线（）开头、以空格开头或结尾。字符串大小为 1~128 字节。 `__content__` 为仅配置全文索引时存放日志全文使用的字段，键值索引请勿使用该字段。不可使用如下字段： `__time__` `__source__` `__path__` `__tls_key__` `__tls_time__` `__mq_offset__` `__package_offset__`
Value	String	必选	字段值，需满足上传要求。

参数

类型

是否必选

描述

Key

String

必选

单条日志里某个字段组的 key 值。

Key 为 UTF-8 编码字符串，支持字母、数字、空格、下划线（）、连字符（-）和斜线（/），并且不支持以下划线（）开头、以空格开头或结尾。字符串大小为 1~128 字节。
__content__ 为仅配置全文索引时存放日志全文使用的字段，键值索引请勿使用该字段。
不可使用如下字段：
- __time__
- __source__
- __path__
- __tls_key__
- __tls_time__
- __mq_offset__
- __package_offset__

Value

String

必选

字段值，需满足上传要求。

LogTag 说明：

参数	类型	是否必选	描述
Key	String	必选	自定义的标签字段 key。
Value	String	必选	自定义的标签字段 value。

响应参数

无

示例

请求示例

POST https://tls-{Region}.volces.com/PutLogs?TopicId=c1
Content-Type: application/x-protobuf
x-tls-hashkey: 7fffffff
x-tls-compresstype: lz4
x-tls-bodyrawsize: 1024
...
<PB格式的LogGroupList>

响应示例

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8 
...

错误码

错误码（Code）	HTTP 状态码	错误信息（Message）	说明
InvalidArgument	400	Invalid argument key %s, value %s, please check argument.	参数不合法。
DeserializeFailed	400	Deserialization failed, please check argument.	反序列化失败
TopicNotExist	404	Topic does not exist.	日志主题不存在。
InternalServerError	500	We encountered an unexpected server error, please try again later.	服务器内部错误。

更多信息，请参考通用错误码。