Breaking Down What X-Ray Records
Understanding the data model is essential for both instrumenting your code correctly and reading traces in the console.
Trace
The top-level container. Identified by a globally unique Trace ID (e.g., 1-5e1b4a3c-abcdef1234567890abcdef12). A trace represents the complete end-to-end journey of one request.
Segment
Represents the work done by one service within the trace. Each service that participates in the request creates exactly one segment. A segment contains:
- Start time and end time
- HTTP request/response data (method, URL, status code)
- Error, fault, and throttle flags
- The service name and version
Subsegment
Represents a discrete unit of work within a segment. There are two kinds:
1. Remote call subsegments: Automatically created by the SDK when your code calls an external service (DynamoDB, S3, an HTTP endpoint). These record the downstream call's latency and result.
2. Custom subsegments: Manually created in your code to time a specific block of logic (e.g., "MyEncryptionAlgorithm" or "ParseXMLResponse").
# Python example: custom subsegment
from aws_xray_sdk.core import xray_recorder
@xray_recorder.capture('process_payment') # Creates a named subsegment
def process_payment(order):
# This entire function's execution time is recorded as a subsegment
result = stripe.charge(order.amount)
return result
Inferred Segments (Inferred Nodes)
DynamoDB does not run the X-Ray SDK and does not send segments to X-Ray. But your Lambda's SDK knows it called DynamoDB (because it intercepted the call). The SDK creates a subsegment for that call. X-Ray uses these subsegments to draw DynamoDB on the Service Map as an Inferred Node — a service that appears in your architecture map even though it never directly reported to X-Ray. This is how managed AWS services (S3, DynamoDB, SNS, SQS) appear on your service map automatically.