文档中心

日志服务

日志管理

PutLogs

调用 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，否则索引创建失败。

注意事项

日志服务采用火山引擎统一的签名机制。详细说明，请参考签名机制。

请求说明

请求方式：POST

请求地址：https://{tls-endpoint}/PutLogs

请求头

参数	参数类型	是否必选	示例值	说明
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 压缩格式。
Content-MD5	String	可选	70B68AE****A1A62724DDE5D5E4	HTTP 请求中 Body 内容的 MD5 哈希值，用于验证请求体内容的完整性，确保数据在传输过程中没有被篡改或损坏。格式为 32 位的十六进制字符串。说明使用 LogCollector 或 SDK 调用 PutLogs 接口时，日志服务会默认添加该请求头。

请求参数

下表仅列出该接口特有的请求参数和部分公共参数。更多信息请见公共参数。

Query

参数	类型	是否必选	示例值	描述
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 键值对集合。
OptionalTimeNs	oneof OptionalTimeNs	可选	纳秒级别的日志时间戳。

OptionalTimeNs 说明

参数	类型	是否必选	描述
TimeNs	fixed32	可选	纳秒级别的日志时间戳。上传纳秒时间戳后，日志服务支持通过纳秒时间戳排序日志。详细说明，请参考按照高精度时间戳排序日志。

LogContent 说明

参数	类型	是否必选	描述
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。

返回参数

本接口无特有的返回参数。更多信息请见返回结构。

请求示例

返回示例

错误码

下表为您列举了该接口与业务逻辑相关的错误码。公共错误码请参见公共错误码文档。

错误码（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.	服务器内部错误。

最近更新时间：2026.02.06 15:54:27

这个页面对您有帮助吗？

有用

无用