Queries logs in a Logstore of a specified project. You can also specify relevant parameters to query logs that meet the specified conditions.

Description

  • The time ranges that are used in this operation are left-closed and right-open intervals. Each interval contains the specified start time, but does not contain the specified end time. The intervals are defined by the from and to parameters. If you specify the from and to parameters to the same value, the time range is invalid and an error message is returned.
  • If the number of logs in the Logstore greatly changes, Log Service cannot predict how many times this API operation needs to be called to obtain the complete results. In this case, you must check the value of the x-log-progress parameter in the returned results of each request. Based on the value, you can decide whether to call this operation again to obtain the complete results. 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. However, the query has a latency that varies with the type of the log. Based on the log timestamp, Log Service classifies logs into the following two types:
    • Real-time data: Logs of this type are generated within the interval of (-180 seconds, 900 seconds] based on the current server time. For example, if a log was generated at September 25, 2014, 12:00:00 UTC and the server receives the log at September 25, 2014, 12:05:00 UTC, the server processes the log as real-time data. Such logs are generated in normal scenarios.
    • Historical data: Logs of this type are generated within the interval of [-604,800 seconds, -180 seconds) based on the current server time. For example, if a log was generated at September 25, 2014, 12:00:00 UTC and the server receives the log at September 25, 2014, 12:05:00 UTC, the server processes the log as historical data. Such logs 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 three seconds. You can query 99.9% of real-time data within one second.

Request syntax

GET /logstores/<logstorename>? type=log&topic=<logtopic>&from=<starttime>&to=<endtime>&query=<querystring>&line=<linenum>&offset=<startindex>&reverse=<ture|false> HTTP/1.1
Authorization: <AuthorizationString>
Date: <GMT Date>
Host: <Project Endpoint>
x-log-bodyrawsize: 0
x-log-apiversion: 0.6.0
x-log-signaturemethod: hmac-sha1

Request parameters

  • Request headers

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

  • Parameters
    Parameter Type Required Example Description
    logstorename string Yes app_log The name of the Logstore to which the logs belong.
    type string Yes log The type of data in the Logstore. The value of this parameter must be set to log in this operation.
    from int Yes 1409529600 The start time of the time range that is specified in the request. This value is a UNIX timestamp representing the number of milliseconds that have elapsed since the epoch time January 1, 1970, 00:00:00 UTC.
    to int Yes 1409608800 The end time of the time range that is specified in the request. This value is a UNIX timestamp representing the number of milliseconds that have elapsed since the epoch time January 1, 1970, 00:00:00 UTC.
    topic string No groupA The topic of the logs to be queried.
    query string No error The query syntax. For more information about the query syntax, see Real-time log analysis.
    line int No 20 The maximum number of logs to return for the request. Valid values: 0 to 100. Default value: 100.
    offset int No 0 The start position of the returned log for the request. Valid values: 0 and positive integers. Default value: 0.
    reverse bool No None Specifies whether to return logs in reverse order based on the log timestamp. Unit: minutes. If the value is true, logs are returned in reverse order. If the value is false, logs are returned in regular order. Default value: false.

Response parameters

  • Response headers

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

    The response header contains specific parameters that indicate whether the query results are complete. The following table describes the specific response parameters.
    Parameter Type Example Description
    x-log-progress string Complete The status of the query results. Valid values: Incomplete and Complete.
    x-log-count int 10000 The total number of logs in the query results.
  • Response elements
    If the request succeeds, the HTTP status code 200 is returned. The response body contains the matched logs. If a large number of logs (measured in TBs) are queried, the query results may be incomplete. The response body of the GetLogs operation is an array that contains the information of each log. The following table describes the parameters of the array.
    Parameter Type Example Description
    __time__ int 1409529660 The timestamp of the log. This value is a UNIX timestamp representing the number of milliseconds that have elapsed since the epoch time January 1, 1970, 00:00:00 UTC.
    __source__ string 10.237.0.17 The log source. It is specified when logs are written.
    [content] Key-value pair None The original content of logs.

Examples

In this example, the logs whose topic is groupA are queried in a Logstore named app_log. The Logstore belongs to a project named big-game in the China (Hangzhou) region. The time range is from September 1, 2014, 00:00:00 to September 1, 2014, 22:00:00 and the keyword is "error". The query starts from the beginning of the time range. A maximum of 20 logs can be returned.
  • Sample requests
    GET /logstores/app_log? type=log&topic=groupA&from=1409529600&to=1409608800&query=error&line=20&offset=0 HTTP/1.1
    Authorization: <AuthorizationString>
    Date: Wed, 3 Sept. 2014 08:33:46 GMT
    Host: big-game.cn-hangzhou.log.aliyuncs.com
    x-log-bodyrawsize: 0
    x-log-apiversion: 0.4.0
    x-log-signaturemethod: hmac-sha1
  • Sample success responses
    HTTP/1.1 200 OK
    Content-MD5: 36F9F7F0339BEAF571581AF1B0AAAFB5
    Content-Type: application/json
    Content-Length: 269
    Date: Wed, 3 Sept. 2014 08:33:47 GMT
    x-log-requestid: efag01234-12341-15432f
    x-log-progress : Complete
    x-log-count : 10000
    x-log-processed-rows: 10000
    x-log-elapsed-millisecond:5
    {
        "progress": "Complete",
        "count": 2,
        "logs": [
            {
                "__time__": 1409529660,
                "__source__": "10.237.0.17",
                "Key1": "error",
                "Key2": "Value2"
            },
            {
                "__time__": 1409529680,
                "__source__": "10.237.0.18",
                "Key3": "error",
                "Key4": "Value4"
            }
        ]
    }

In the sample response, the value of the x-log-progress parameter is Complete. This indicates that all logs are queried and the returned results are complete. Two logs meet the specified query conditions. The logs are displayed as the value of the logs parameter. If the value of the x-log-progress parameter is Incomplete, you must resend the request to obtain the complete results.

Error codes

HTTP status code Error code Error message Description
404 LogStoreNotExist logstore {Name} does not exist. The error message returned because the specified Logstore does not exist.
400 InvalidTimeRange request time range is invalid. The error message returned because the specified time range of the request is invalid.
400 InvalidQueryString query string is invalid. The error message returned because the specified query string of the request is invalid.
400 InvalidOffset offset is invalid. The error message returned because the specified offset parameter of the request is invalid.
400 InvalidLine line is invalid. The error message returned because the specified line parameter of the request is invalid.
400 InvalidReverse Reverse value is invalid. The error message returned because the specified reverse parameter is invalid.
400 IndexConfigNotExist logstore without index config. The error message returned because the indexing feature is not enabled for the Logstore.

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