X-Ray
Introduction
Section titled “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
Section titled “Getting started”This guide is designed for users new to X-Ray and assumes basic
knowledge of the AWS CLI and our awslocal
wrapper script.
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.
Sending trace segments
Section titled “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"awslocal xray put-trace-segments --trace-segment-documents "$DOC"
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
Section titled “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)awslocal 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
Section titled “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):
awslocal xray batch-get-traces --trace-ids $TRACE_ID
{ "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
Section titled “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
Section titled “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
Section titled “API Coverage”Operation ▲ | Implemented | Image |
---|