Instrumenting your application for Amazon X-Ray - Amazon X-Ray
Instrumenting your application with the Amazon Distro for OpenTelemetryInstrumenting your application with Amazon X-Ray SDKsChoosing between the Amazon Distro for OpenTelemetry and X-Ray SDKs
Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China (PDF).

Instrumenting your application for Amazon 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 Amazon 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 Amazon Distro for OpenTelemetry

The Amazon Distro for OpenTelemetry (ADOT) is an Amazon 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 Amazon.

With ADOT, engineers can instrument their applications once and send correlated metrics and traces to multiple Amazon monitoring solutions including Amazon CloudWatch, Amazon 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 Amazon Distro for OpenTelemetry Collector enabled for use with X-Ray. For more information about using the Amazon Distro for OpenTelemetry with Amazon X-Ray and other Amazon Web Services, see the Amazon Distro for OpenTelemetry Documentation.

For more information about language support and usage, see Amazon 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 Amazon 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 and Python. In addition, ADOT enables auto-instrumentation of Amazon Lambda functions and their downstream requests using Java, Node.js, and Python runtimes, via ADOT Managed Lambda Layers.

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 Amazon 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. This is different from the format for trace IDs that are created using an X-Ray SDK or by Amazon services that are integrated with X-Ray. To ensure that trace IDs in W3C format are accepted by X-Ray, you must use Amazon X-Ray Exporter version 0.86.0 or later, which is included with ADOT Collector version 0.34.0 and later. Previous versions of the exporter validate trace ID timestamps, which might cause W3C trace IDs to be rejected.

Instrumenting your application with Amazon X-Ray SDKs

Amazon 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 Amazon SDK clients that your application uses to call other Amazon Web 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 Amazon 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 Amazon Distro for OpenTelemetry and X-Ray SDKs

The SDKs included with X-Ray are part of a tightly integrated instrumentation solution offered by Amazon. The Amazon 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 Amazon 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

    Amazon 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 Amazon 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