All Products
Search
Document Center

Simple Log Service:GetContextLogs

Last Updated:Oct 26, 2023

Queries the contextual logs of a specified log.

Usage notes

  • You can specify a log as the start log. The time range of a contextual query is one day before and one day after the generation time of the start log.

  • Host consists of a project name and a Simple Log Service endpoint. You must specify a project in Host.

  • An AccessKey pair is created and obtained. For more information, see AccessKey pairs.

    The AccessKey pair of an Alibaba Cloud account has permissions on all API operations. Using these credentials to perform operations in Simple Log Service is a high-risk operation. We recommend that you use a RAM user to call API operations or perform routine O&M. To create a RAM user, log on to the RAM console. Make sure that the RAM user has the management permissions on Simple Log Service resources. For more information, see Create a RAM user and authorize the RAM user to access Simple Log Service.

  • The information that is required to query logs is obtained. The information includes the name of the project to which the logs belong, the region of the project, and the name of the Logstore to which the logs belong. For more information, see Manage a project and Manage a Logstore.

  • Indexes are configured before you query logs. For more information, see Create indexes.

  • The values of the pack_id and pack_meta fields are obtained before you query logs. The fields are internal fields, and you can obtain the values by using the debugging feature of your browser in the Simple Log Service console.

Authentication resources

The following table describes the authorization information that is required for this operation. You can add the information to the Action element of a RAM policy statement to grant a RAM user or a RAM role the permissions to call this operation.

Action

Resource

log:GetLogStoreContextLogs

acs:log:{#regionId}:{#accountId}:project/{#ProjectName}/logstore/{#LogstoreName}

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 and does not have operation-specific request headers. For more information, see Common request parameters.

Request syntax

GET /logstores/{logstore} HTTP/1.1

Request parameters

Parameter

Type

Position

Required

Example

Description

project

String

Host

Yes

ali-test-project

The name of the project.

logstore

String

Path

Yes

test-logstore

The name of the Logstore.

type

String

Query

Yes

context_log

The type of the data in the Logstore. Set the value to context_log.

pack_id

String

Query

Yes

85C897C740352DC6-808

The unique identifier of the log group to which the start log belongs.

pack_meta

String

Query

Yes

2|MTY1NTcwNTUzODY5MTY0MDk1Mg==|3|0

The unique context identifier of the start log in the log group.

back_lines

Long

Query

Yes

10

The number of logs that you want to obtain and are generated before the generation time of the start log. Value range: (0,100].

forward_lines

Long

Query

Yes

10

The number of logs that you want to obtain and are generated after the generation time of the start log. Value range: (0,100].

Response parameters

Parameter

Type

Example

Description

total_lines

Long

201

The total number of logs that are returned. The logs include the start log that is specified in the request.

back_lines

Long

100

The number of logs that are generated before the generation time of the start log.

forward_lines

Long

100

The number of logs that are generated after the generation time of the start log.

progress

String

Complete

Indicates whether the query results are complete. Valid values:

  • Complete: The query is successful, and the complete query results are returned.

  • Incomplete: The query is successful, but the query results are incomplete. To obtain the complete results, you must repeat the request.

logs

Array of Object

{ "__index_number__": "-100", "__tag__:__pack_id__": "895CEA449A52FE-8c8", "__pack_meta__": "0|MTU1OTI4NTExMjg3NTQ2NDU1OA==|4|1"}

The logs that are returned. The logs are arranged in contextual order. If no contextual logs are found based on the specified start log, this parameter is empty.

The logs parameter contains log content and the following fields that are formatted in key-value pairs.

Parameter

Type

Example

Description

__index_number__

String

-100

The position of the log in the context. A negative value indicates that the log is generated before the generation time of the start log. The value 0 indicates that the log is the start log. A positive value indicates that the log is generated after the generation time of the start log. For example, the value -100 indicates that the log is the 100th log before the generation time of the start log.

__tag__:__pack_id__

String

895CEA449A52FE-8c8

The unique identifier of the log group to which the log belongs. The identifier can be used as the value of the pack_id parameter in the request.

__pack_meta__

String

0\|MTU1OTI4NTExMjg3NTQ2NDU1OA==\|4\|1

The unique context identifier of the log in the log group. The identifier can be used as the value of the pack_meta parameter in the request.

Examples

Sample requests

GET /logstores/test-logstore?type=context_log&pack_id=85C897C740352DC6-808&pack_meta=2|MTY1NTcwNTUzODY5MTY0MDk1Mg==|3|0&back_lines=10&forward_lines=10 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

{
    "total_lines": 201,
    "back_lines": 100,
    "forward_lines": 100,
    "progress": "Complete",
    "logs": [
                {
                  "__index_number__": "-100",
                  "__tag__:__pack_id__": "895CEA449A52FE-8c8",
                  "__pack_meta__": "0|MTU1OTI4NTExMjg3NTQ2NDU1OA==|4|1",
                }
    ]
}

Error codes

For a list of error codes, see Service error codes.

HTTP status code

Error code

Error message

Description

404

ProjectNotExist

Project ProjectName does not exist.

The specified project does not exist.

404

LogstoreNotExist

logstore logstoreName does not exist.

The specified Logstore does not exist.

400

InvalidParameter

Invalid pack meta/id.

The value of the pack_meta or pack_id parameter in the request is invalid.

400

InvalidParameter

back_lines or forward_lines must be postive.

The value of the back_lines or forward_lines parameter in the request is invalid. You must set one or both of the parameters to positive values.

For more information, see Common error codes.

SDK example

In this example, Simple Log Service SDK for Java is used. You must use Simple Log Service SDK for Java 0.6.38 or later. If you use Logtail to collect logs, the contextual information is automatically added to logs. For more information, see SDK sample code.


package sdksample;

import com.aliyun.openservices.log.Client;
import com.aliyun.openservices.log.common.LogContent;
import com.aliyun.openservices.log.common.LogItem;
import com.aliyun.openservices.log.common.QueriedLog;
import com.aliyun.openservices.log.common.TagContent;
import com.aliyun.openservices.log.exception.LogException;
import com.aliyun.openservices.log.request.PutLogsRequest;
import com.aliyun.openservices.log.response.GetContextLogsResponse;
import com.aliyun.openservices.log.response.GetLogsResponse;

import java.util.ArrayList;
import java.util.Date;
import java.util.List;

public class GetContextLogsSample {

    private static int getCurrentTimestamp() {
        return (int) (new Date().getTime() / 1000);
    }

    private static class PackInfo {
        public String packID;
        public String packMeta;

        public PackInfo(String id, String meta) {
            this.packID = id;
            this.packMeta = meta;
        }
    }

    private static PackInfo extractPackInfo(QueriedLog log) {
        PackInfo ret = new PackInfo("", "");
        ArrayList<LogContent> contents = log.GetLogItem().GetLogContents();
        for (int i = 0; i < contents.size(); ++i) {
            LogContent content = contents.get(i);
            if (content.GetKey().equals("__tag__:__pack_id__")) {
                ret.packID = content.GetValue();
            } else if (content.GetKey().equals("__pack_meta__")) {
                ret.packMeta = content.GetValue();
            }
        }
        return ret;
    }

    public static void main(String args[]) throws InterruptedException, LogException {
        // The Simple Log Service endpoint. In this example, the Simple Log Service endpoint for the China (Hangzhou) region is used. Replace the parameter value with the actual endpoint. 
        String endpoint = "https://cn-hangzhou.log.aliyuncs.com"; 
       // Configure environment variables. In this example, the AccessKey ID and AccessKey secret are obtained from environment variables. 
        String accessKeyId = System.getenv("ALIBABA_CLOUD_ACCESS_KEY_ID");
        String accessKeySecret = System.getenv("ALIBABA_CLOUD_ACCESS_KEY_SECRET"); 
        // The name of the project that you want to query. 
        String project = "ProjectName"; 
       // The name of the Logstore that you want to query. 
        String logstore = "logstoreName"; 
        // Create a client instance. 
        Client client = new Client(endpoint, accessKeyId, accessKeySecret);

        System.out.println("Make sure that the indexing feature is enabled for the Logstore.");
        Thread.sleep(3000);

        // Call the GetLogs operation and include |with_pack_meta in the query statement to obtain the values of the pack_id and pack_meta parameters in the start log. 
        // Set the query time range to the previous 15 minutes. 
        // Specify the first log in the query results as the start log. 
        String query = "*|with_pack_meta";
        GetLogsResponse response = client.GetLogs(project, logstore,
                (int) getCurrentTimestamp() - 900, (int) getCurrentTimestamp(),"", query);
        ArrayList<QueriedLog> logs = response.GetLogs();
        if (logs.isEmpty()) {
            System.out.println("No logs are found.");
            System.exit(1);
        }

        // Extract the pack information of the start log. 
        PackInfo info = extractPackInfo(logs.get(0));
        if (info.packMeta.isEmpty() || info.packID.isEmpty()) {
            System.out.println("pack ID: " + info.packID + ", pack meta: " + info.packMeta);
            System.out.println("The pack information of the start log is incomplete. Make sure that the start log is written by using Logtail.");
            System.exit(1);
        }

        // Use the extracted pack information to perform a contextual query. This is a two-way query. 
        GetContextLogsResponse contextRes = client.getContextLogs(project, logstore,
                info.packID, info.packMeta, 10, 10);
        System.out.println("The two-way query.")
        System.out.println("pack ID: " + info.packID + ", pack meta: " + info.packMeta);
        System.out.println("is complete: " + contextRes.isCompleted());
        System.out.println("total lines: " + contextRes.getTotalLines());
        System.out.println("back lines: " + contextRes.getBackLines());
        System.out.println("forward lines: " + contextRes.getForwardLines());
        Thread.sleep(1000);

        // Use the start log in the query results to query the logs generated one day before the generation time of the start log. This is a one-way query. You can repeat the query up to three times. 
        List<QueriedLog> contextLogs = contextRes.getLogs();
        for (int i = 0; i < 3 && !contextLogs.isEmpty(); i++) {
            QueriedLog log = contextLogs.get(0);
            info = extractPackInfo(log);
            GetContextLogsResponse res = client.getContextLogs(project, logstore,
                    info.packID, info.packMeta, 10, 0);
            System.out.println("Query the logs generated one day before the generation time of the start log.");
            System.out.println("pack ID: " + info.packID + ", pack meta: " + info.packMeta);
            System.out.println("is complete: " + res.isCompleted());
            System.out.println("total lines: " + res.getTotalLines());
            System.out.println("back lines: " + res.getBackLines());
            System.out.println("forward lines: " + res.getForwardLines());
            contextLogs = res.getLogs();

            Thread.sleep(1000);
        }

        // Use the last log in the query results to query the logs generated one day after the generation time of the start log. This is a one-way query. You can repeat the query up to three times. 
        contextLogs = contextRes.getLogs();
        for (int i = 0; i < 3 && !contextLogs.isEmpty(); i++) {
            QueriedLog log = contextLogs.get(contextLogs.size() - 1);
            info = extractPackInfo(log);
            GetContextLogsResponse res = client.getContextLogs(project, logstore,
                    info.packID, info.packMeta, 0, 10);
            System.out.println("Query the logs generated one day after the generation time of the start log.");
            System.out.println("pack ID: " + info.packID + ", pack meta: " + info.packMeta);
            System.out.println("is complete: " + res.isCompleted());
            System.out.println("total lines: " + res.getTotalLines());
            System.out.println("back lines: " + res.getBackLines());
            System.out.println("forward lines: " + res.getForwardLines());
            contextLogs = res.getLogs();

            Thread.sleep(1000);
        }
    }
}