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

接口说明

  • 服务端会对每次PutLogs写入的日志数据做格式检查,只要日志数据中有任何一条日志不符合规范,则整个请求失败且无任何日志数据成功写入。
  • 目前仅支持写入PB格式的日志数据,日志数据以LogGroup的形式展示。
  • 日志数据写入时有两种模式:
    • 负载均衡模式(LoadBalance):自动根据Logstore下所有可写的Shard进行负载均衡写入。该方法写入可用性较高(SLA:99.95%),适合写入消费数据与Shard无关的场景,例如不保序。
    • Key路由Shard模式(KeyHash):在URL参数中增加key字段,用来判断数据写入哪个Shard的range中。该参数为可选参数,不设置时自动切换负载均衡写入模式。例如,可以将某个生产者(例如instance)根据名称Hash固定到Shard上,这样就能保证写入与消费在该Shard上的数据是严格有序的(在Merge/Split过程中能够严格保证对于Key在一个时间点只会出现在一个Shard上,请参见分区)。
  • PutLogs接口每次可以写入的日志组数据量上限为3 MB或者4096条,日志组中每条日志下的Value部分不超过1 MB大小。只要日志数据量超过这两条上限中的任意一条则整个请求失败,且无任何日志数据成功写入。

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 sample-logtail-config 需要写入日志的Logstore名称。

返回数据

  • 响应头

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

  • 响应元素

    成功后无任何响应元素。

示例

  • 请求示例
    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"
    }

错误码

HTTP状态码 错误码 错误消息 描述
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. 日志内容包含的日志必须小于3 MB和4096条。
400 PostBodyUncompressError Failed to decompress logs. 日志内容解压失败。
400 PostBodyInvalid The post data time is out of range 日志中时间范围不在[-7*24Hour,+15Min]有效范围内。
404 LogStoreNotExist logstore {Name} does not exist. 日志库不存在。

更多错误码,请参见通用错误码