PutLogs 接口用于向指定的 Logstore 中写入日志数据。

目前仅支持写入PB 格式的日志数据。
说明 日志数据以 LogGroup 的形式写入。
写入时有两种模式:
  • 负载均衡模式(LoadBalance):自动根据 Logstore 下所有可写的 Shard 进行负载均衡写入。该方法写入可用性较高(SLA:99.95%),适合写入消费数据与 Shard 无关的场景,例如不保序。
  • Key 路由 Shard 模式(KeyHash):在URL参数中增加key字段,用来判断数据写入哪个 Shard 的 range 中。该参数为可选参数,不设置时自动切换负载均衡写入模式。 例如,可以将某个生产者(例如 instance)根据名称 Hash 固定到 Shard 上,这样就能保证写入与消费在该 Shard 上的数据是严格有序的(在 Merge/Split 过程中能够严格保证对于 Key 在一个时间点只会出现在一个 Shard 上,请参见分区)。

PB 数据

PB 格式日志压缩数据字段描述如下。详情请参见数据模型数据编码方式
  • Log
    字段名称 类型 是否必须 描述
    Time Int 日志时间。
    Contents List 是,至少包含一个元素 日志字段列表,每个元素类型请参见 Content 字段表格。
  • Content
    字段名称 类型 是否必须 描述
    Key String 自定义 key 名称。
    Value String 自定义 key 对应的值。
  • LogTag
    字段名称 类型 是否必须 描述
    Key String 自定义 key 名称。
    Value String 自定义 key 对应的值。
  • LogGroup
    字段名称 类型 是否必须 描述
    Logs List 日志列表,每个元素请参见Log 字段表格。
    Topic String 用户自定义字段,用以标记一批日志。
    Source String 日志的来源。例如产生该日志机器的 IP 地址。
    LogTags List 日志的标签列表,每个元素请参见 LogTag。

请求语法

  • 负载均衡模式
    POST /logstores/<logstorename>/shards/lb HTTP/1.1
    Authorization: <AuthorizationString>
    Content-Type: application/x-protobuf
    Content-Length: <Content Length>
    Content-MD5: <Content MD5>
    Date: <GMT Date>
    Host: <Project Endpoint>
    x-log-apiversion: 0.6.0
    x-log-bodyrawsize: <BodyRawSize>
    x-log-compresstype: lz4
    x-log-signaturemethod: hmac-sha1
    <PB 格式日志压缩数据>
  • Key 路由 Shard 模式
    POST /logstores/<logstorename>/shards/route?key=14d2f850ad6ea48e46e4547edbbb27e0
    Authorization: <AuthorizationString>
    Content-Type: application/x-protobuf
    Content-Length: <Content Length>
    Content-MD5: <Content MD5>
    Date: <GMT Date>
    Host: <Project Endpoint>
    x-log-apiversion: 0.6.0
    x-log-bodyrawsize: <BodyRawSize>
    x-log-compresstype: lz4
    x-log-signaturemethod: hmac-sha1
    <PB 格式日志压缩数据>

请求参数

  • 请求头

    关于 Log Service API 的公共请求头,请参见公共请求头

  • 请求参数
    名称 类型 必选 描述
    logstorename string 需要写入日志的 Logstore 名称。

响应参数

  • 响应头

    PutLogs 接口无特有响应头。关于 Log Service API 的公共响应头,请参见公共响应头

  • 响应元素

    成功后无任何响应元素。

细节描述

  • PutLogs 接口每次可以写入的日志组数据量上限为 3MB 或者 4096 条,日志组中每条日志下的 Value 部分不超过 1MB 大小。只要日志数据量超过这两条上限中的任意一条则整个请求失败,且无任何日志数据成功写入。
  • 服务端会对每次 PutLogs 写入的日志数据做格式检查,只要日志数据中有任何一条日志不符合规范,则整个请求失败且无任何日志数据成功写入。具体日志格式要求请参见基本概念

错误码

除了返回 Log Service API 的通用错误码,还可能返回如下特有错误码:
HTTP 状态码(Status Code) 错误码(Error Code) 错误消息(Error Message) 描述(Description)
400 PostBodyInvalid Protobuffer content cannot be parsed. Protobuffer 内容不能够解析。
400 InvalidTimestamp Invalid timestamps are in logs. 日志内容中有无效的日志时间戳。
400 InvalidEncoding Non-UTF8 characters are in logs. 日志内容中有非 UTF8 字符。
400 InvalidKey Invalid keys are in logs. 日志内容中有无效的 key。
400 PostBodyTooLarge Logs must be less than or equal to 3 MB and 4096 entries. 日志内容包含的日志必须小于 3MB 和 4096 条。
400 PostBodyUncompressError Failed to decompress logs. 日志内容解压失败。
499 PostBodyInvalid The post data time is out of range 日志中时间范围不在 [-7*24Hour, +15Min] 有效范围内。
404 LogStoreNotExist logstore {Name} does not exist. 日志库(Logstore)不存在。
说明 上表错误消息中 {name} 表示该部分会被具体的 LogstoreName 来替换。

示例

  • 请求示例
    POST /logstores/sls-test-logstore
    {
        "Content-Length": 118,
        "Content-Type":"application/x-protobuf",
        "x-log-bodyrawsize":1356,
        "Host": "ali-test-project.cn-hangzhou-devcommon-intranet.sls.aliyuncs.com",
        "Content-MD5":"6554BD042149C844761C2C094A8FECCE",
        "Date":"Thu, 12 Nov 2015 06:54:26 GMT",
        "x-log-apiversion": "0.6.0",
        "x-log-compresstype":"lz4"
        "x-log-signaturemethod": "hmac-sha1",
        "Authorization":"LOG <yourAccessKeyId>:<yourSignature>"
    }
    <PB 格式日志使用 Lz4 压缩后的二进制数据>
  • 响应示例
    Header
    {   
        "date": "Thu, 12 Nov 2015 06:53:03 GMT",
        "connection": "close",
        "x-log-requestid": "5644160399248C060600D216",
        "content-length": "0",
        "server": "nginx/1.6.1"
    }