OpenTelemetry compatibility considerations - Amazon CloudWatch
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).

OpenTelemetry compatibility considerations

To onboard your applications with CloudWatch Application Signals, we recommend that you completely remove any existing application performance monitoring solution from your application beforehand. This includes removing any instrumentation code and configurations.

Even though Application Signals uses OpenTelemetry instrumentation, it is not guaranteed to be compatible with your existing OpenTelemetry instrumentation or configuration. In a best-case scenario, you might be able to keep some of your OpenTelemetry functionality, such as custom metrics. However, be sure to read the following sections for details.

Considerations if you already use OpenTelemetry

If you are already using OpenTelemetry with your application, the rest of this section contains important information to achieve compatibility with Application Signals.

  • Before you enable your application for Application Signals, you must remove the injection of any other auto-instrumentation agents based on OpenTelemetry from your application. This helps avoid configuration conflicts. You can continue to use manual instrumentation using compatible OpenTelemetry APIs along with Application Signals.

  • If you are using manual instrumentation to generate custom spans or metrics from your application, then depending on the complexity of the instrumentation, enabling Application Signals might cause them to stop generating data or have other undesirable behavior. You might be able to use some of the available configurations in OpenTelemetry (except for the ones mentioned in the table later in this section) to retain the desired behavior of your existing metrics or spans. For more information about these configurations, see SDK Configuration in the OpenTelemetry documentation.

    For example, by using the OTEL_EXPORTER_OTLP_METRICS_ENDPOINT configuration and a self-managed OpenTelemetry Collector instance, you might be able to continue sending your custom metrics to your desired destination.

  • Some environment variables or system properties must not be used with Application Signals, while you can use others as long as you follow the guidance in the table. See the following table for details.

Environment variable Recommendation with Application Signals

General environment variables

OTEL_SDK_DISABLED

Must not be set to true.

OTEL_TRACES_EXPORTER

Must be set to otlp.

OTEL_LOGS_EXPORTER

Set to none to disable other logs exporters.

OTEL_EXPORTER_OTLP_ENDPOINT

Must not be used.

OTEL_EXPORTER_OTLP_TRACES_ENDPOINT

Must not be used.

OTEL_ATTRIBUTE_COUNT_LIMIT

If set, must be set high enough to include approximately 10 more span attributes that are added by CloudWatch Application Signals.

OTEL_EXPORTER_OTLP_PROTOCOL

Must be set to http/protobuf

OTEL_PROPAGATORS

If set, must include xray for tracing.

OTEL_TRACES_SAMPLER

If set, must be xray to use X-Ray centralized sampling.

To use local sampling, set this to parentbased_traceidratio and specify the sampling rate in OTEL_TRACES_SAMPLER_ARG.

OTEL_TRACES_SAMPLER_ARG

If you are using the default of X-Ray centralized trace sample, this variable must not be used.

If you are using local sampling instead, set the sampling rate in this variable. For example, 0.05 for a 5% sampling rate.

Java-specific environment variables

OTEL_JAVA_ENABLED_RESOURCE_PROVIDERS

If set, must include Amazon resource detectors.

Python-specific environment variables

OTEL_PYTHON_CONFIGURATOR

If used, must be set to aws_configurator

OTEL_PYTHON_DISTRO

If used, must be set to aws_distro