AWS Distro for OpenTelemetry - Instrumentation for Python

Introduction

This project is a redistribution of the OpenTelemetry Distro for Python, preconfigured for use with AWS services. Please check out that project too to get a better understanding of the underlying internals. You won't see much code in this repository since we only apply some small configuration changes, and our OpenTelemetry friends takes care of the rest. The exception to this is support for Application Signals.

We provided a Python agent that can be attached to any application using a supported Python version and dynamically injects bytecode to capture telemetry from a number of popular libraries and frameworks. The telemetry data can be exported in a variety of formats. In addition, the agent and exporter can be configured via command line arguments or environment variables. The net result is the ability to gather telemetry data from a Python application without any code changes.

Getting Started

Check out the getting started documentation.

Supported Python libraries and frameworks

For the complete list of supported frameworks, please refer to the OpenTelemetry for Python documentation.

Generative AI

As of version 0.20.0, this distribution officially supports Generative AI instrumentation for the following frameworks and SDKs:

• CrewAI (crewai >= 1.10.0, < 2)
• LangChain (langchain >= 0.3.21, < 2)
• LlamaIndex (llama-index-core >= 0.13.0, < 1; llama-index-workflows >= 1.0.1, != 2.24.0, < 3)
• Model Context Protocol (MCP) (mcp >= 1.10.0, < 2)
• OpenAI Agents SDK (openai-agents >= 0.3.3, < 1)

These instrumentations provide end-to-end visibility into agent applications, including framework orchestration, model calls, tool invocations, and downstream dependencies.

Configuration

Environment variable	Description
AGENT_OBSERVABILITY_ENABLED	Set to true to enable agent-observability defaults. The default is false. When enabled, the following environment variable defaults are applied unless you have already configured them: OTEL_TRACES_EXPORTER=otlp OTEL_LOGS_EXPORTER=otlp OTEL_METRICS_EXPORTER=awsemf OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT=true OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=https://xray.<region>.amazonaws.com/v1/traces OTEL_EXPORTER_OTLP_LOGS_ENDPOINT=https://logs.<region>.amazonaws.com/v1/logs OTEL_PYTHON_DISABLED_INSTRUMENTATIONS=http,sqlalchemy,psycopg2,pymysql,sqlite3,aiopg,asyncpg,mysql_connector,urllib3,requests,system_metrics,google-genai,jinja2 OTEL_PYTHON_LOGGING_AUTO_INSTRUMENTATION_ENABLED=true OTEL_PYTHON_LOG_CORRELATION=true OTEL_AWS_APPLICATION_SIGNALS_ENABLED=false OTEL_METRICS_ADD_APPLICATION_SIGNALS_DIMENSIONS=false CREWAI_DISABLE_TELEMETRY=true Note The trace and log endpoints are configured only when OTEL_EXPORTER_OTLP_ENDPOINT is not set and an AWS Region can be determined.
AWS_GENAI_CONTENT_EXTRACTION_OPT_OUT	We recommend setting AWS_GENAI_CONTENT_EXTRACTION_OPT_OUT=true to keep captured content in span attributes. The current default is false: captured content is removed from span attributes and routed to a separate logs pipeline. If that logs pipeline is disabled, the content is discarded. Warning AWS_GENAI_CONTENT_EXTRACTION_OPT_OUT will be deprecated in a future release. As we align with the latest OTel GenAI semantic conventions, captured content will remain in span attributes. Note For context about why this environment variable exists, OTel recently replaced per-message events with structured attributes in Semantic Conventions v1.37.0. https://github.com/open-telemetry/semantic-conventions/releases/tag/v1.37.0 https://github.com/open-telemetry/semantic-conventions/pull/2179
AWS_REDACT_SPAN_ATTRIBUTES	Your spans may contain sensitive information from LLM interactions, such as your users' prompt data and tool call information; use AWS_REDACT_SPAN_ATTRIBUTES to specify a comma-separated list of span attributes to redact. Matching values in spans, span events, and span links are all replaced with REDACTED. Note that this applies to all span attributes, not just those produced by this distribution's instrumentations. Supports wildcard patterns. Examples: To redact specific sensitive data GenAI attributes: export AWS_REDACT_SPAN_ATTRIBUTES='gen_ai.input.messages,gen_ai.output.messages' To redact multiple attributes matching a pattern: export AWS_REDACT_SPAN_ATTRIBUTES='llm.input_messages.*,llm.output_messages.*' Warning Redaction occurs in-process within the agent, before telemetry is exported. This may affect other integrations that rely on these attribute values.
AWS_GENAI_INSTRUMENTATION Note AWS_AGENTIC_INSTRUMENTATION is the legacy environment variable name and remains supported as a fallback when AWS_GENAI_INSTRUMENTATION is not set.	Set to disabled to force all of the above instrumentations to remain disabled. Set to enabled to force all of the above instrumentations to load. Note When agent observability is enabled (AGENT_OBSERVABILITY_ENABLED=true), instrumentation is skipped when a conflicting third-party instrumentation is detected for the same framework. You may set AWS_GENAI_INSTRUMENTATION=disabled to force all of the above instrumentations to remain disabled if you are using another instrumentation source and automatic detection does not work. If another third-party instrumentation is installed, you should uninstall it or otherwise resolve any dependency conflicts before using the above instrumentations. You may set AWS_GENAI_INSTRUMENTATION=enabled to force the above instrumentations to load. We recommend that you do not use this setting when third-party instrumentation for the same framework is enabled, because both instrumentations may run and produce duplicate or inconsistent telemetry.

Support

Please note that as per policy, we're providing support via GitHub on a best effort basis. However, if you have AWS Enterprise Support you can create a ticket and we will provide direct support within the respective SLAs.

Security issue notifications

If you discover a potential security issue in this project we ask that you notify AWS/Amazon Security via our vulnerability reporting page. Please do not create a public github issue.

License

This project is licensed under the Apache-2.0 License.

Notices

Python Version Support

This project ensures compatibility with the following supported Python versions: 3.10, 3.11, 3.12, 3.13, 3.14

Note on Amazon CloudWatch Application Signals

Amazon CloudWatch Application Signals components are designed to seamlessly work with all library instrumentations offered by OpenTelemetry Python auto-instrumentation. While upstream OpenTelemetry Python instrumentations are in beta, Application Signals components are stable, production ready and have also been tested for popular libraries/frameworks such as Django, Boto3, and others. We will prioritize backward compatibility for Application Signals components, striving to ensure that they remain functional even in the face of potential breaking changes introduced by OpenTelemetry upstream libraries. Please raise an issue if you notice Application Signals doesn't work for a particular OpenTelemetry supported library.

Checksum Verification

Artifacts released will include a .sha256 file for checksum verification starting from v0.7.0 To verify, run the command shasum -a 256 -c <artifact_name>.sha256 It should return the output <artifact_name>: OK if the validation is successful