PostLogStoreLogs

Last Updated: Nov 08, 2017

Writes log data in a specified LogStore. Currently, only log groups in PB format can be written. There are two writing modes:

  • Load balancing: The system automatically writes all writable shards in the LogStore in load balancing mode. This method is highly available for writing (SLA: 99.95%), applicable to scenarios in which data writing and consumption are independent of shards, for example, non-reordering.
  • Key hashing: A key is needed for data writing. The server will automatically write shards within the key range. For example, the system can hash a producer (for example, an instance) to a fixed shard based on the name to ensure orderly writing and consumption on the shard (it can ensure that during merging or splitting a key appears only on one shard at a time point, refer to Shard Data Model).

Request syntax

Load balancing

  1. POST /logstores/<logstorename>/shards/lb HTTP/1.1
  2. Authorization: <AuthorizationString>
  3. Content-Type: application/x-protobuf
  4. Content-Length: <Content Length>
  5. Content-MD5: <Content MD5>
  6. Date: <GMT Date>
  7. Host: <Project Endpoint>
  8. x-log-apiversion: 0.6.0
  9. x-log-bodyrawsize: <BodyRawSize>
  10. x-log-compresstype: lz4
  11. x-log-signaturemethod: hmac-sha1
  12. <Compressed log data in PB format>

Key hasing

The system adds an x-log-hashkey to the header to determine which shard the key falls on. This parameter is optional. If you leave it blank, the system will automatically switch to the load balancing mode.

  1. POST /logstores/<logstorename>/shards/lb HTTP/1.1
  2. Authorization: <AuthorizationString>
  3. Content-Type: application/x-protobuf
  4. Content-Length: <Content Length>
  5. Content-MD5: <Content MD5>
  6. Date: <GMT Date>
  7. Host: <Project Endpoint>
  8. x-log-apiversion: 0.6.0
  9. x-log-bodyrawsize: <BodyRawSize>
  10. x-log-compresstype: lz4
  11. x-log-hashkey : 14d2f850ad6ea48e46e4547edbbb27e0
  12. x-log-signaturemethod: hmac-sha1
  13. <Compressed log data in PB format>

Request parameters

Name Type Required Description
logstorename String Yes The LogStore name of the logs to write.

Request header

In key hashing mode, an x-log-hashkey request header is needed (refer to the preceding example). For details about the public request header of the API, refer to Public Request Header.

Response header

No special response header is available. For details about the public response header of the API, refer to Public Response Header.

Response element

After the request is successful, there are no response elements.

Detailed description

  • A maximum of 3 MB or 4,096 logs can be written on the PutLogs interface. Once the logs written in exceed 3MB or 4096 lines, the entire request fails, and no logs are written into the LogStore.
  • The server checks the format of the logs written on the PutLogs interface. (For log formats, refer to Core Concept). Once any log does not comply with the specification, the entire request fails, and no logs are written.

Error code

In addition to general error codes of the API, the following special error codes may be returned:

HTTP Status Code Error Code Error Message Description
400 PostBodyInvalid Protobuffer content cannot be parsed. Protobuffer content cannot be parsed.
400 InvalidTimestamp Invalid time stamps are in logs. Invalid time stamps are found in logs.
400 InvalidEncoding Non-UTF8 characters are in logs. Non-UTF8 characters are found in logs.
400 InvalidKey Invalid keys are in logs. Invalid keys are found in logs.
400 PostBodyTooLarge Logs must be less than 3M and 4096 lines. Logs must be less than 3 MB and 4,096 lines.
400 PostBodyUncompressError Body is uncompressed fail. Decompressing logs failed.
499 PostBodyInvalid The post data time is out of range The log time is out of [-7 × 24 hours, +15 minutes].
404 LogStoreNotExist logstore {Name} not exist. The LogStore does not exist.

The {name} variable in the above error messages will be replaced by the actual logstore name.

Example

Request example:
  1. POST /logstores/sls-test-logstore
  2. {
  3. "Content-Length": 118,
  4. "Content-Type":"application/x-protobuf",
  5. "x-log-bodyrawsize":1356,
  6. "Host": "ali-test-project.cn-hangzhou-devcommon-intranet.sls.aliyuncs.com",
  7. "Content-MD5":"6554BD042149C844761C2C094A8FECCE",
  8. "Date":"Thu, 12 Nov 2015 06:54:26 GMT",
  9. "x-log-apiversion": "0.6.0",
  10. "x-log-compresstype":"lz4"
  11. "x-log-signaturemethod": "hmac-sha1",
  12. "Authorization":"LOG 94to3z418yupi6ikawqqd370:zLyKtgyGpwyv7ntXZs2dY2wWIg4="
  13. }
  14. <Binary data from logs in PB format compressed with LZ4>
Response example:
  1. Header
  2. {
  3. "date": "Thu, 12 Nov 2015 06:53:03 GMT",
  4. "connection": "close",
  5. "x-log-requestid": "5644160399248C060600D216",
  6. "content-length": "0",
  7. "server": "nginx/1.6.1"
  8. }
Thank you! We've received your feedback.