Queries logs in a Logstore of a specified project.

Description

  • If the number of logs in a Logstore significantly changes, Log Service cannot predict the number of times you must call this API operation to obtain complete results. In this case, you must check the value of the x-log-progress parameter in the returned results of each request. You can also call this API operation again to obtain the complete results based on the value of this parameter. Each time you call this operation, the same number of charge units (CUs) are consumed.
  • After a log is written to a Logstore, you can call the GetHistograms and GetLogs operations to query the log. The latency of the query varies based on the type of the log. Log Service classifies logs into the following two types based on the log timestamp:
    • Real-time data: The difference between the time in a log of this type and the current time on the server is within the interval (-180 seconds, 900 seconds]. For example, if a log was generated at 12:03:00 UTC, September 25, 2014 and the server received the log at 12:05:00 UTC, September 25, 2014, the server processes the log as real-time data. Logs of this type are generated in standard query scenarios.

    • Historical data: The difference between the time in a log of this type and the current time on the server is within the interval [-604,800 seconds, -180 seconds). For example, if a log was generated at 12:00:00 UTC, September 25, 2014 and the server received the log at 12:05:00 UTC, September 25, 2014, the server processes the log as historical data. Logs of this type are generated in data supplement scenarios.

      After real-time data is written to a Logstore, the data can be queried with a maximum latency of 3 seconds. The latency of 99.9% of queries is within 1 second.

Note Log Service calculates the difference between the time in a log (__time__ field) and the time when the server receives the log (__tag__:__recieve_time__ field). If the difference is within the interval (-180 seconds, 900 seconds], the log is real-time data. If the difference is within the interval [-604,800 seconds, -180 seconds), the log is historical data.

Request headers

The GetLogs operation does not have operation-specific request headers and uses only common request headers. For more information, see Common request headers.

Request syntax

GET /logstores/{logstoreName}/index HTTP/1.1

Request parameters

Parameter Type Position Required Example Description
logstorename String Path Yes nginx-demo

The name of the Logstore.

type String Query Yes log

The type of the data in the Logstore. This parameter must be set to log in the GetLogs operation.

from Long Query Yes 1627268185

The start time of the time range that is specified in the request. This parameter specifies the time when log data is written to a Logstore.

  • The time ranges that are used in this operation are left-closed and right-open intervals. Each interval includes the specified start time, but does not include the specified end time. These intervals are specified by the from and to parameters in the request. If you set the from and to parameters to the same value, the time range is invalid and an error message is returned.
  • The start time is a timestamp that follows the UNIX time format. It is the number of seconds that have elapsed since 00:00:00 UTC, Thursday, January 1, 1970.
to Long Query Yes 1627269085

The end time of the time range that is specified in the request. This parameter specifies the time when log data is written to a Logstore.

  • The time ranges that are used in this operation are left-closed and right-open intervals. Each interval includes the specified start time, but does not include the specified end time. These intervals are specified by the from and to parameters in the request. If you set the from and to parameters to the same value, the time range is invalid and an error message is returned.
  • The end time is a timestamp that follows the UNIX time format. It is the number of seconds that have elapsed since 00:00:00 UTC, Thursday, January 1, 1970.
topic String Query No topic

The topic of the logs. The default value is double quotation marks (""). For more information, see Topic.

query String Query Yes status: 401 | SELECT remote_addr,COUNT(*) as pv GROUP by remote_addr ORDER by pv desc limit 5

The search statement or analytic statement. For more information, see Log search overview and Log analysis overview.

If you add set session parallel_sql=true; to the analytic statement in the query parameter, Dedicated SQL is used. For example, you can set the query parameter to * | set session parallel_sql=true; select count(*) as pv.

Note If you specify an analytic statement in the query parameter, the line and offset parameters are invalid for this operation. In this case, we recommend that you set the line and offset parameters to 0 and use a LIMIT clause to limit the number of entries to return on each page. For more information, see Paged query.
line Long Query No 100

The maximum number of logs to return for the request. This parameter is valid only when the query parameter is set to a search statement. Minimum value: 0. Maximum value: 100. Default value: 100.

offset Long Query No 0

The line from which the query starts. This parameter is valid only when the query parameter is set to a search statement. Default value: 0.

reverse Boolean Query No false

Specifies whether to return logs in reverse order by log timestamp. The log timestamps are accurate to minutes.

  • true: Logs are returned in reverse order.
  • false: Logs are returned in regular order. This is the default value.
Notice
  • The reverse parameter is valid only when the query parameter is set to a search statement. The reverse parameter specifies the method to sort returned logs.
  • If the query parameter is set to a query statement, the reverse parameter is invalid. The order in which returned logs are sorted is specified by using the ORDER BY clause in the analytic statement. If you use the default keyword asc in the ORDER BY clause, the logs are sorted in ascending order. If you use the desc keyword in the ORDER BY clause, the logs are sorted in descending order.
powerSql Boolean Query No false

Specifies whether to use the Dedicated SQL feature. For more information, see Enable Dedicated SQL.

  • true: The Dedicated SQL feature is used.
  • false: The Standard SQL feature is used. This is the default value.

You can use the powerSql or query parameter to configure Dedicated SQL.

Response parameters

Parameter Type Example Description
x-log-progress String Complete

The status of the query results. Valid values:

  • Complete: The query succeeded and the complete query results are returned.
  • Incomplete: The query succeeded but the query results are incomplete because the amount of returned data exceeds the limit and the specified time range is invalid. You must repeat the request to obtain complete query results.
x-log-count Long 10000

The total number of logs in the query results.

logs Object

The returned logs.

__time__ Long 1627268185

The timestamp of the log. The timestamp follows the UNIX time format. It is the number of seconds that have elapsed since 00:00:00 UTC, Thursday, January 1, 1970.

__source__ String None

The log source that is specified when logs are written. For example, the source can be the IP address of the host where the log is generated.

Examples

Sample requests

GET /logstores/{logstoreName}/index?type=log&from=1627268185&to=1627269085&topic=topic&query=status: 401 | SELECT remote_addr,COUNT(*) as pv GROUP by remote_addr ORDER by pv desc limit 5&line=100&offset=0&reverse=false&powerSql=false 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

{
  "x-log-progress" : "Complete",
  "x-log-count" : 10000,
  "logs" : {
    "__time__" : 1627268185,
    "__source__" : "None"
  }
}

Error codes

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