Writes log data to a specified Logstore.

Only log groups in the Protocol Buffers (Protobuf) format can be written to a specified Logstore. For more information, see Data encoding method.
Note Log data is packaged in log groups.
You can write log data in either of the following modes:
  • LoadBalance mode: In this mode, Log Service automatically writes logs to all writable shards in a Logstore. This mode provides high availability (SLA: 99.95%) in data writes. It applies to scenarios where data writes and reads are irrelevant to shards, for example, where ordering is not considered.
  • KeyHash mode: In this mode, a key is required in data writes. Log Service automatically writes data to the shard whose MD5 value range contains the key value. For example, Log Service can hash an instance as a producer to a fixed shard based on the name. This ensures that data is written and consumed in a strict order in the shard. The key is included only in the MD5 value range of a shard at a time even when the shard is merged or split. For more information, see Shard.

Protobuf data

The following table describes the fields of compressed log data in the Protobuf format. For more information, see Data model and Data encoding method.
  • Log
    Field Type Required Description
    Time Integer Yes The time when the log was collected.
    Contents List Yes. This field must contain at least one element. The list of log fields. For information about the field elements, see the content field table.
  • Content
    Field Type Required Description
    Key String Yes The name of the custom key.
    Value String Yes The value of the custom key.
  • Log tag
    Field Type Required Description
    Key String Yes The name of the custom key.
    Value String Yes The value of the custom key.
  • Log group
    Field Type Required Description
    Logs List Yes A list of logs. For information about the field elements, see the log field table.
    Topic String No A user-defined field in a log. This field identifies a group of logs.
    Source String No The source of the log, for example, the IP address of the machine where the log is generated.
    LogTags List Yes The list of log tags. For information about the field element, see the log tag field table.

Request syntax

  • LoadBalance mode
    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
    <Compressed log data in the Protobuf format>
  • KeyHash mode
    You can add the x-log-hashkey field to the request header to specify the shard whose MD5 value range contains the key value. This field is optional. If you do not specify this field, Log Service automatically writes log data in the LoadBalance mode.
    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-hashkey : 14d2f850ad6ea48e46e4547edbbb27e0
    x-log-signaturemethod: hmac-sha1
    <Compressed log data in the Protobuf format>

Request parameters

  • Request header

    In the KeyHash mode, you must add the x-log-hashkey header. For more information, see the preceding example.

    For information about common request headers of Log Service API operations, see Common request headers.

  • Request parameters
    Parameter Type Required Description
    logstorename string Yes The name of the Logstore to which logs are written.

Response parameters

  • Response headers

    This operation does not return special response headers. For information about common response headers of Log Service API operations, see Common response headers.

  • Response elements

    No response element is returned after the request succeeds.

Detailed description

  • You can call this operation to write at most 3 MB of log group data or 4,096 logs at a time. The size of values in each log cannot be greater than 1 MB. If these limits are exceeded, the request will fail and no log data will be written.
  • Log Service checks the format of log data written by the PutLogs API operation. For information about the log formats, see Overview. If any log does not meet the format requirements, the request will fail and no log data will be written.

Error codes

This operation also returns the following special error codes in addition to the common error codes of Log Service API operations. For more information, see Common error codes.
HTTP status code Error code Error message Description
400 PostBodyInvalid Protobuffer content cannot be parsed. The error message returned because the logs in the Protobuf format cannot be parsed.
400 InvalidTimestamp Invalid timestamps are in logs. The error message returned because the logs contain invalid timestamps.
400 InvalidEncoding Non-UTF8 characters are in logs. The error message returned because the logs contain non-UTF-8 encoded characters.
400 InvalidKey Invalid keys are in logs. The error message returned because the logs contain invalid keys.
400 PostBodyTooLarge Logs must be less than or equal to 3 MB and 4096 entries. The error message returned because the size of logs is greater than 3 MB or the number of logs exceeds 4,096.
400 PostBodyUncompressError Failed to decompress logs. The error message returned because the logs fail to be decompressed.
499 PostBodyInvalid The post data time is out of range The error message returned because the log timestamp is not within the valid range: [-7 × 24 hours, + 15 minutes].
404 LogStoreNotExist logstore {Name} does not exist. The error message returned because the specified Logstore does not exist.
Note The {name} variable in the preceding error message will be replaced with a specific Logstore name.

Examples

  • Sample requests
    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>"
    }
    <Binary data obtained after logs in the Protobuf format are compressed with the LZ4 algorithm>
  • Sample success responses
    Header
    {   
        "date": "Thu, 12 Nov 2015 06:53:03 GMT",
        "connection": "close",
        "x-log-requestid": "5644160399248C060600D216",
        "content-length": "0",
        "server": "nginx/1.6.1"
    }