X-Ray

Introduction

X-Ray is a distributed tracing service that helps to understand cross-service interactions and facilitates debugging of performance bottlenecks. Instrumented applications generate trace data by recording trace segments with information about the work tasks of an application, such as timestamps, tasks names, or metadata. X-Ray supports different ways of instrumenting your application including the AWS X-Ray SDK and the AWS Distro for OpenTelemetry (ADOT). X-Ray daemon is an application that gathers raw trace segment data from the X-Ray SDK and relays it to the AWS X-Ray API. The X-Ray API can then be used to retrieve traces originating from different application components.

LocalStack allows you to use the X-Ray APIs to send and retrieve trace segments in your local environment. The supported APIs are available on our API Coverage section, which provides information on the extent of X-Ray integration with LocalStack.

Getting started

This guide is designed for users new to X-Ray and assumes basic knowledge of the AWS CLI and our lstk aws command.

Start your LocalStack container using your preferred method. We will demonstrate how you can create a minimal trace segment and manually send it to the X-Ray API. Notice that this trace ingestion typically happens in the background, for example by the X-Ray SDK and X-Ray daemon.

PutTraceSegments.

Sending trace segments

You can generates a unique trace ID and constructs a JSON document with trace information. It then sends this trace segment to the AWS X-Ray API using the PutTraceSegments API. Run the following commands in your terminal:

START_TIME=$(date +%s)
HEX_TIME=$(printf '%x\n' $START_TIME)
GUID=$(dd if=/dev/random bs=12 count=1 2>/dev/null | od -An -tx1 | tr -d ' \t\n')
TRACE_ID="1-$HEX_TIME-$GUID"
END_TIME=$(($START_TIME+3))
DOC=$(cat <<EOF
{"trace_id": "$TRACE_ID", "id": "6226467e3f845502", "start_time": $START_TIME.37518, "end_time": $END_TIME.4042, "name": "test.elasticbeanstalk.com"}
EOF
)
echo "Sending trace segment to X-Ray API: $DOC"
lstk aws xray put-trace-segments --trace-segment-documents "$DOC"

Output

Sending trace segment to X-Ray API: {"trace_id": "1-6501ee11-056ec85fafff21f648e2d3ae", "id": "6226467e3f845502", "start_time": 1694625297.37518, "end_time": 1694625300.4042, "name": "test.elasticbeanstalk.com"}
{
"UnprocessedTraceSegments": []
}

Retrieve trace summaries

You can now retrieve the trace summaries from the last 10 minutes using the GetTraceSummaries API. Run the following commands in your terminal:

EPOCH=$(date +%s)
lstk aws xray get-trace-summaries --start-time $(($EPOCH-600)) --end-time $(($EPOCH))
{
    "TraceSummaries": [
        {
            "Id": "1-6501ee11-056ec85fafff21f648e2d3ae",
            "Duration": 3,
            "ResponseTime": 1,
            "HasFault": false,
            "HasError": false,
            "HasThrottle": false,
            "Http": {},
            "Annotations": {},
            "Users": [],
            "ServiceIds": []
        }
    ],
    "TracesProcessedCount": 1,
    "ApproximateTime": 1694625413.0
}

Retrieve full trace

You can retrieve the full trace by providing the TRACE_ID using the BatchGetTraces API. Run the following commands in your terminal (use the same terminal as for the first command):

lstk aws xray batch-get-traces --trace-ids $TRACE_ID

Output

{
    "Traces": [
        {
            "Id": "1-6501ee11-056ec85fafff21f648e2d3ae",
            "Duration": 3,
            "Segments": [
                {
                    "Id": "6226467e3f845502",
                    "Document": "{\"trace_id\": \"1-6501ee11-056ec85fafff21f648e2d3ae\", \"id\": \"6226467e3f845502\", \"start_time\": 1694625297.37518, \"end_time\": 1694625300.4042, \"name\": \"test.elasticbeanstalk.com\"}"
                }
            ]
        }
    ],
    "UnprocessedTraceIds": []
}

Examples

The following code snippets and sample applications provide practical examples of how to use X-Ray in LocalStack:

• Lambda X-Ray shows how to instrument Lambda functions for X-Ray using Powertools and the X-Ray SDK.

Current Limitations

LocalStack supports collecting trace segments but currently does not correlate multiple trace segments with the same trace_id into a single aggregated trace.

API Coverage

10 of 38 operations implemented

Available from the Ultimate plan. Licensing details

Formats for tools and AIPage MarkdownCoverage MarkdownCoverage JSONCoverage catalog

Find an API

Search the full operation list, then sort the table to compare current support.

Loading operations…

Search by operation name

Operation ▲	Implemented ▼	Verified on Kubernetes
Loading operations…

PreviousNext

Complete static API list All 38 operations and their current support status

Operation	Status
BatchGetTraces	Implemented
CancelTraceRetrieval	Not implemented
CreateGroup	Not implemented
CreateSamplingRule	Implemented
DeleteGroup	Not implemented
DeleteResourcePolicy	Not implemented
DeleteSamplingRule	Implemented
GetEncryptionConfig	Not implemented
GetGroup	Not implemented
GetGroups	Not implemented
GetIndexingRules	Not implemented
GetInsight	Not implemented
GetInsightEvents	Not implemented
GetInsightImpactGraph	Not implemented
GetInsightSummaries	Not implemented
GetRetrievedTracesGraph	Not implemented
GetSamplingRules	Implemented
GetSamplingStatisticSummaries	Not implemented
GetSamplingTargets	Not implemented
GetServiceGraph	Implemented
GetTimeSeriesServiceStatistics	Not implemented
GetTraceGraph	Implemented
GetTraceSegmentDestination	Not implemented
GetTraceSummaries	Implemented
ListResourcePolicies	Not implemented
ListRetrievedTraces	Not implemented
ListTagsForResource	Not implemented
PutEncryptionConfig	Not implemented
PutResourcePolicy	Not implemented
PutTelemetryRecords	Implemented
PutTraceSegments	Implemented
StartTraceRetrieval	Not implemented
TagResource	Not implemented
UntagResource	Not implemented
UpdateGroup	Not implemented
UpdateIndexingRule	Not implemented
UpdateSamplingRule	Implemented
UpdateTraceSegmentDestination	Not implemented