Instrumenting your application for AWS X-Ray
Instrumenting your application involves sending trace data for incoming and outbound requests and other events within your application, along with metadata about each request. There are several different instrumentation options you can choose from or combine, based on your particular requirements:
-
Auto instrumentation – instrument your application with zero code changes, typically via configuration changes, adding an auto-instrumentation agent, or other mechanisms.
-
Library instrumentation – make minimal application code changes to add pre-built instrumentation targeting specific libraries or frameworks, such as the AWS SDK, Apache HTTP clients, or SQL clients.
-
Manual instrumentation – add instrumentation code to your application at each location where you want to send trace information.
There are several SDKs, agents, and tools that can be used to instrument your application for X-Ray tracing.
Topics
Instrumenting your application with the AWS Distro for OpenTelemetry
The AWS Distro for OpenTelemetry (ADOT) is an AWS distribution based on the Cloud Native Computing Foundation (CNCF) OpenTelemetry project. OpenTelemetry provides a single set of open source APIs, libraries, and agents to collect distributed traces and metrics. This toolkit is a distribution of upstream OpenTelemetry components including SDKs, auto-instrumentation agents, and collectors that are tested, optimized, secured, and supported by AWS.
With ADOT, engineers can instrument their applications once and send correlated metrics and traces to multiple AWS monitoring solutions including Amazon CloudWatch, AWS X-Ray, and Amazon OpenSearch Service.
Using X-Ray with ADOT requires two components: an OpenTelemetry SDK enabled for
use with X-Ray, and the AWS Distro for OpenTelemetry Collector enabled for use with
X-Ray. For more information about using the AWS Distro for OpenTelemetry with AWS X-Ray and other AWS services,
see the AWS Distro for OpenTelemetry Documentation
For more information about language support and usage, see AWS Observability on GitHub
Note
You can now use the CloudWatch agent to collect metrics, logs and traces from Amazon EC2 instances and on-premise servers. CloudWatch agent version 1.300025.0 and later can collect traces from OpenTelemetry or X-Ray client SDKs, and send them to X-Ray. Using the CloudWatch agent instead of the AWS Distro for OpenTelemetry (ADOT) Collector or X-Ray daemon to collect traces can help you reduce the number of agents that you manage. See the CloudWatch agent topic in the CloudWatch User Guide for more information.
ADOT includes the following:
ADOT currently includes auto-instrumentation support for Java
ADOT SDKs for Java and Go support X-Ray centralized sampling rules. If you need support for X-Ray sampling rules in other languages, consider using an AWS X-Ray SDK.
Note
You can send now send W3C trace IDs to X-Ray. By default, traces that are created with OpenTelemetry have a
trace ID format that's based on the W3C Trace Context
specification
Instrumenting your application with AWS X-Ray SDKs
AWS X-Ray includes a set of language-specific SDKs for instrumenting your application to send traces to X-Ray. Each X-Ray SDK provides the following:
-
Interceptors to add to your code to trace incoming HTTP requests
-
Client handlers to instrument AWS SDK clients that your application uses to call other AWS services
-
An HTTP client to instrument calls to other internal and external HTTP web services
X-Ray SDKs also support instrumenting calls to SQL databases, automatic AWS SDK client instrumentation, and other features. Instead of sending trace data directly to X-Ray, the SDK sends JSON segment documents to a daemon process listening for UDP traffic. The X-Ray daemon buffers segments in a queue and uploads them to X-Ray in batches.
The following language-specific SDKs are provided:
X-Ray currently includes auto-instrumentation support for Java.
Choosing between the AWS Distro for OpenTelemetry and X-Ray SDKs
The SDKs included with X-Ray are part of a tightly integrated instrumentation solution offered by AWS. The AWS Distro for OpenTelemetry is part of a broader industry solution in which X-Ray is only one of many tracing solutions. You can implement end-to-end tracing in X-Ray using either approach, but it’s important to understand the differences in order to determine the most useful approach for you.
We recommend instrumenting your application with the AWS Distro for OpenTelemetry if you need the following:
-
The ability to send traces to multiple different tracing back ends without having to re-instrument your code
-
Support for a large number of library instrumentations for each language, maintained by the OpenTelemetry community
-
Fully managed Lambda layers that package everything you need to collect telemetry data, without requiring code changes when using Java, Python, or Node.js
Note
AWS Distro for OpenTelemetry offers a simpler getting started experience for instrumenting your Lambda functions. However, due to the flexibility OpenTelemetry offers, your Lambda function will require additional memory and invocations may experience cold start latency increases, which can lead to additional charges. If you're optimizing for low-latency and do not require OpenTelemetry's advanced capabilities such as dynamically configurable back end destinations, you may want to use the AWS X-Ray SDK to instrument your application.
We recommend choosing an X-Ray SDK for instrumenting your application if you need the following:
-
A tightly integrated single-vendor solution
-
Integration with X-Ray centralized sampling rules, including the ability to configure sampling rules from the X-Ray console and automatically use them across multiple hosts, when using Node.js, Python, Ruby, or .NET
