文档

PutLogs

更新时间:

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

接口说明

  • 服务端会对每次PutLogs写入的日志数据做格式检查,只要日志数据中有任何一条日志不符合规范,则整个请求失败且无任何日志数据成功写入。

  • 目前仅支持写入PB格式的日志数据,日志数据以LogGroup的形式展示。

  • 日志数据写入时有两种模式:

    • 负载均衡模式(LoadBalance):自动根据Logstore下所有可写的Shard进行负载均衡写入。该方法写入可用性较高,适合不保证顺序的数据消费场景。

    • Key路由Shard模式(KeyHash):在URL参数中增加Key字段,用来判断数据写入哪个Shard中。该参数为可选参数,不设置时自动切换为负载均衡写入模式。例如,可以将某个生产者(例如instance)根据名称Hash固定到Shard上,这样就能保证写入与消费在该Shard上的数据是严格有序的(在合并、分裂过程中能够严格保证对于Key在一个时间点只会出现在一个Shard上,请参见分区(Shard))。

  • PutLogs接口每次可以写入的原始日志大小上限为10 MB,日志组中每条日志下的Value部分建议不超过1 MB。历史版本的SDK可能存在不同限制,建议升级到最新的版本解决。

  • 在SDK参考中,日志服务提供Java和Python SDK等PutLogs的使用示例。更多信息,请参见Java SDK快速入门Python SDK快速入门等。

PB数据

PB格式日志压缩数据字段描述如下。详情请参见数据模型数据编码方式

  • Log

    参数名称

    数据类型

    是否必填

    描述

    Time

    Integer

    日志时间。Unix时间戳格式,表示从1970-1-1 00:00:00 UTC计算起的秒数。

    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: LOG yourAccessKeyId:yourSignature
    Content-Type: application/x-protobuf
    Content-Length: Content Length
    Content-MD5: Content MD5
    Date: GMT Date
    Host: ProjectName.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: LOG yourAccessKeyId:yourSignature
    Content-Type: application/x-protobuf
    Content-Length: Content Length
    Content-MD5: Content MD5
    Date: GMT Date
    Host: ProjectName.Endpoint
    x-log-apiversion: 0.6.0
    x-log-bodyrawsize: BodyRawSize
    x-log-compresstype: lz4
    x-log-signaturemethod: hmac-sha1
    <PB 格式日志压缩数据>

其中,Host由Project名称和日志服务Endpoint构成,您需要在Host中指定Project。

请求参数

  • 请求头

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

  • 请求参数

    参数名称

    数据类型

    是否必填

    示例值

    描述

    projectName

    String

    ali-test-project

    Project名称。

    logstoreName

    String

    sample-logtail-config

    Logstore名称。

返回数据

  • 响应头

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

  • 响应元素

    返回HTTP状态码200,则表示请求成功。该接口调用成功后无任何响应元素。

示例

  • 请求示例

    POST /logstores/sls-test-logstore/shards/lb
    {
        "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
    {   
        "Access-control-allow-origin" : "*", 
        "Date" : "Wed, 11 Nov 2015 08:28:20 GMT",
        "Server" : "Tengine",
        "Content-Length" : 0, 
        "x-log-requestid" : "5642FC2399248C8F7B0145FD",
        "Connection" : "close"
    }

错误码

HTTP状态码

错误码

错误消息

描述

400

PostBodyInvalid

Protobuffer content cannot be parsed.

Protobuffer内容不合法,无法解析。

400

InvalidTimestamp

Invalid timestamps are in logs.

日志内容中有无效的日志时间戳。

400

InvalidEncoding

Non-UTF8 characters are in logs.

日志内容中有非UTF-8字符。

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.

日志内容解压失败。具体操作,请参见SDK数据压缩原理

400

PostBodyInvalid

The post data time is out of range

日志中时间范围不在[-7*24小时 + 15分钟]有效范围内。

404

LogStoreNotExist

logstore logstoreName does not exist.

Logstore不存在。

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

  • 本页导读 (1)
文档反馈