GetCursor

Last Updated: Mar 31, 2017

The GetCursor is used to get the cursor based on the time. The following diagram shows the relationship between the cursor and the project, LogStore, and shard:

  • A project has multiple logstores.
  • Each logstore can have multiple shards.
  • A cursor can be used to get the location of the specified log.

relation

Request syntax

  1. GET /logstores/ay42/shards/2?type=cursor&from=1402341900 HTTP/1.1
  2. Authorization: <AuthorizationString>
  3. Date: <GMT Date>
  4. Host: <Project Endpoint>
  5. x-log-apiversion: 0.6.0

Request parameters

Parameter Name Type Required or Not Description
shard string Yes
type string Yes Cursor
from string Yes Time point (in UNIX seconds), or begin, end
LogStore lifecycle:

The lifecycle of a logstore is specified by the lifeCycle field in the attribute. For example, it is assumed that the current time is 2015-11-11 09:00:00 and the lifecycle is 24. Therefore, the consumable data time section in each shard is [2015-11-10 09:00:00, 2015-11-11 09:00:00]. The time here is the server time.

Using the parameter “from”, you can locate the logs within the lifecycle in the shard. Assuming that the logstore lifecycle is [begin_time,end_time) and the parameter “from” is set to from_time, then:

  1. from_time <= begin_time or from_time == "begin" : Returns the cursor location corresponding to begin_time.
  2. from_time >= end_time or from_time == "end" : Returns the cursor location for writing the next entry at the current time point (no data at this cursor location currently).
  3. from_time > begin_time and from_time < end_time : Returns the cursor location for the first data packet whose receipt time at the server is >= from_time.

Request header

No special request header is available. 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

  1. {
  2. "cursor": "MTQ0NzI5OTYwNjg5NjYzMjM1Ng=="
  3. }

Detailed description

N/A

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
404 LogStoreNotExist Logstore {Name} not exist
400 ParameterInvalid Parameter From is not valid
400 ShardNotExist Shard {ShardID} not exist
500 InternalServerError Specified Server Error Message
400 LogStoreWithoutShard the logstore has no shard

Example

Request example:
  1. GET /logstores/sls-test-logstore/shards/0?type=cursor&from=begin
  2. Header:
  3. {
  4. "Content-Length": 0,
  5. "x-log-signaturemethod": "hmac-sha1",
  6. "x-log-bodyrawsize": 0,
  7. "User-Agent": "log-python-sdk-v-0.6.0",
  8. "Host": "ali-test-project.cn-hangzhou-devcommon-intranet.sls.aliyuncs.com",
  9. "Date": "Thu, 12 Nov 2015 03:56:57 GMT",
  10. "x-log-apiversion": "0.6.0",
  11. "Content-Type": "application/json",
  12. "Authorization": "LOG 94to3z418yupi6ikawqqd370:+vo0Td6PrN0CGoskJoOiAsnkXgA="
  13. }
Response example:
  1. Header:
  2. {
  3. "content-length": "41",
  4. "server": "nginx/1.6.1",
  5. "connection": "close",
  6. "date": "Thu, 12 Nov 2015 03:56:57 GMT",
  7. "content-type": "application/json",
  8. "x-log-requestid": "56440E0999248C070600C6AA"
  9. }
  10. Body:
  11. {
  12. "cursor": "MTQ0NzI5OTYwNjg5NjYzMjM1Ng=="
  13. }
Thank you! We've received your feedback.