Queries a cursor based on a specified point in time.

Description

  • Host consists of a project name and a Log Service endpoint. You must specify a project in Host.
  • The following list describes the relationships among a cursor, project, Logstore, and shard:
    • A project can have multiple Logstores.
    • A Logstore can have multiple shards.
    • You can use a cursor to locate a log in a shard.

Debugging

OpenAPI Explorer automatically calculates the signature value. For your convenience, we recommend that you call this operation in OpenAPI Explorer. OpenAPI Explorer dynamically generates the sample code of the operation for different SDKs.

Request headers

This operation uses only common request headers. For more information, see Common request parameters.

Request syntax

GET /logstores/{logstore}/shards/{shardId}?type=cursor HTTP/1.1

Request parameters

Parameter Type Position Required Example Description
logstore String Path Yes sls-test-logstore

The name of the Logstore.

shardId Integer Path Yes 1

The ID of the shard.

from String Query Yes begin

The point in time that you want to use to query a cursor. Set the value to a UNIX timestamp or a string such as begin and end.

You can use the from parameter to locate a log in a shard within the lifecycle of a Logstore. If the lifecycle of a Logstore is [begin_time,end_time) and the from parameter is set to from_time, the cursor that is returned varies based on the following conditions:

  • from_time ≤ begin_time or from_time = "begin": The cursor that corresponds to begin_time is returned.
  • from_time ≥ end_time or from_time = "end": The cursor that corresponds to the next log to write based on the current time is returned. The cursor currently points to no data.
  • from_time > begin_time and from_time < end_time: The cursor that corresponds to the first packet received by Log Service later than or at from_time is returned.
Note The lifecycle of a Logstore is specified by the TTL field in the attributes of the Logstore. For example, the data of a Logstore is received at 2018-11-11 09:00:00, and the value of the TTL field of the Logstore is 5. The data in each shard of the Logstore can be consumed within the time range [2018-11-05 09:00:00,2018-11-11 09:00:00). The time range is determined based on the time on the Log Service side. For more information, see Data retention period.

Response parameters

Parameter Type Example Description
Server String nginx

The name of the server.

Content-Type String application/json

The content type of the response body.

Content-Length String 0

The length of the response body.

Connection String close

Indicates whether the connection is persistent. Valid values:

  • close: The connection is non-persistent. A new TCP connection is established for each HTTP request.
  • keep-alive: The connection is persistent. After a TCP connection is established, the connection remains open, and no more time or bandwidth is consumed to establish new connections.
Date String Sun, 27 May 2018 08:25:04 GMT

The time at which the response was returned.

x-log-requestid String 5B0A6B60BB6EE39764D458B5

The ID of the request. This is a unique ID generated by Log Service.

cursor String MTQ0NzI5OTYwNjg5NjYzMjM1Ng==

The value of the cursor.

Examples

Sample requests

GET /logstores/sls-test-logstore/shards/0?type=cursor&from=begin HTTP/1.1
Host:ali-test-project.cn-hangzhou.log.aliyuncs.com
Content-Type:application/json

Sample success responses

JSON format

HTTP/1.1 200 OK
Content-Type:application/json

{
  "cursor" : "MTQ0NzI5OTYwNjg5NjYzMjM1Ng=="
}

Error codes

For a list of error codes, visit the API Error Center.

HTTP status code

Error code

Error message

Description

400

ParameterInvalid

ParameterInvalid

The error message returned because the specified parameter is invalid.

400

ShardNotExist

Shard ShardID does not exist.

The error message returned because the specified shard does not exist.

400

LogStoreWithoutShard

The logstore has no shard.

The error message returned because no shards exist in the specified Logstore.

404

ProjectNotExist

Project does not exist.

The error message returned because the specified project does not exist.

404

LogStoreNotExist

Logstore does not exist.

The error message returned because the specified Logstore does not exist.

500

InternalServerError

Specified Server Error Message.

The error message returned because an internal server error has occurred.

For more information, see Common error codes.