Writes logs to a specified Logstore.

Description

  • Log Service checks the format of the logs that are written by the PutLogs operation. If a log does not meet the format requirements, the request fails and the log is not written.
  • You can write logs only in the Protocol Buffers (protobuf) format. The logs are displayed as a log group.
  • You can write logs in one of the following modes:
    • LoadBalance: In this mode, Log Service writes logs to a shard based on the status of all writable shards. This ensures high availability, with a service level agreement (SLA) of 99.95%. The mode applies to scenarios in which data writes and consumption are irrelevant to shards. For example, you can use this mode if you do not need to preserve the order of logs.
    • KeyHash: In this mode, a key field is added in the URL parameter. Log Service writes logs to a shard based on the key field. This field is optional. If you do not specify this field, Log Service writes logs in the LoadBalance mode. For example, Log Service can hash an instance as a producer, to a fixed shard based on the name of the instance. This ensures that data in the shard is written and consumed in a strict order. A key is included only in one shard at a time even when the shard is merged or split. For more information, see Shards.
  • You can call the PutLogs operation to write up to 3 MB log group data or 4,096 logs each time. The content value of each log cannot be greater than 1 MB. If one of the preceding limits is exceeded, the request will fail and no log data will be written.

Protobuf log data

The following tables describe the fields of compressed log data in the protobuf format. For more information, see Data model and Data encoding.
  • Log
    Field Type Required Description
    Time Int Yes The time when the log was generated.
    Contents List Yes. This field must contain at least one element. The list of log fields. For more information, 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.
  • LogTag
    Field Type Required Description
    Key String Yes The name of the custom key.
    Value String Yes The value of the custom key.
  • LogGroup
    Field Type Required Description
    Logs List Yes The list of logs. For more information, see the Log field table.
    Topic String No The subject of the log. This filed is user-defined and is used to differentiate 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 more information, see the LogTag 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
    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
    <Compressed log data in the protobuf format>

Request parameters

  • Request headers

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

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

Response parameters

  • Response headers

    The PutLogs operation does not have operation-specific response headers. For information about the common response headers of Log Service API operations, see Common response headers.

  • Response elements

    No response element is returned after the request succeeds.

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 that is 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"
    }

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 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 failed 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: [-168 hours, +15 minutes].
404 LogStoreNotExist logstore {Name} does not exist. The error message returned because the specified Logstore does not exist.

For more information about the error codes, see Common error codes.