调用 PutLogs 接口上传日志到指定的日志主题中。
本接口用于将结构化日志上传到指定的日志主题中。目前仅支持写入 PB 格式(Protocol Buffer)的日志数据,日志数据以日志组(LogGroup)的形式展示。日志服务 PB 格式请参考数据编码方式。
上传日志时支持通过负载均衡模式和 HashKey 路由 Shard 模式写入。
日志上传相关的接口(PutLogs、WebTracks)共用一个调用频率和流量限制的额度,具体限制如下:
说明
参数 | 参数类型 | 是否必选 | 示例值 | 说明 |
---|---|---|---|---|
Content-Type | String | 必选 | application/x-protobuf | 日志内容的格式。需要设置为 |
x-tls-bodyrawsize | String | 必选 | 1024 | 请求体的原始大小(压缩前),单位为 Byte。 |
x-tls-hashkey | String | 可选 | 7fffffffffffffffffffffffffffffff | 日志组的 HashKey,用于指定当前日志组要写入的分区(Shard)。
|
x-tls-compresstype | String | 可选 | lz4 | 请求体的压缩格式。默认不压缩。支持设置为:
|
Content-MD5 | String | 可选 | 70B68AE****A1A62724DDE5D5E4 | HTTP 请求中 Body 内容的 MD5 哈希值,用于验证请求体内容的完整性,确保数据在传输过程中没有被篡改或损坏。格式为 32 位的十六进制字符串。 说明 使用 LogCollector 或 SDK 调用 PutLogs 接口时,日志服务会默认添加该请求头。 |
下表仅列出该接口特有的请求参数和部分公共参数。更多信息请见公共参数。
参数 | 类型 | 是否必选 | 示例值 | 描述 |
---|---|---|---|---|
TopicId | String | 是 | 4a********* | 日志主题 ID。 |
说明
日志服务 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 值。
|
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. | 服务器内部错误。 |