Skip to content

aws-observability/aws-otel-python

Repository files navigation

AWS Distro for OpenTelemetry Python SDK

AWS Distro for OpenTelemetry Python SDK (ADOT Python SDK) is a distribution of OpenTelemetry Python with components to trace applications in a format compatible with the AWS X-Ray service. This enables all the features of the OpenTelemetry project and configures its components to create traces that can be viewed in the AWS X-Ray console and allow propagation of those contexts across multiple downstream AWS services.

How it works

OpenTelemetry is a project maintained by the Cloud Native Computing Foundation which provides open source APIs, libraries, and agents to collect distributed traces and metrics for application monitoring.

OpenTelemetry generates telemetry data, such as metrics and traces, for requests to the application. In addition, OpenTelemetry Python provides automatic tracing for many popular Python packages. These traces record parameters used, results, exceptions, and more in span attributes as it completes the traced task. Read more about standardized attributes on the OpenTelemetry Specification Semantic Conventions for traces.

OpenTelemetry Python provides entry points for configuration through its API. This can be used to configure the ids_generator needed to support the X-Ray trace ID format. It also allows the use of a custom propagator, passed into the tracer provider, to generate and propagate the AWS X-Ray trace header.

After traces have been generated, they can be sent to a back-end service like AWS X-Ray to display the traces in a user-friendly interactive console packed with features to help you visualize and understand what happened during traced calls. Learn more about AWS X-Ray in the developer guide.

An easy way for a traced application to send traces to AWS X-Ray is by using the ADOT Collector. The traced application configures OpenTelemetry for Python to export traces in the OpenTelemetry Format, and subsequently directs the traces to a Docker Container running the ADOT Collector. The ADOT Collector is configured with AWS credentials for the CLI, an AWS Region, and which trace attributes to index so that it can send the traces to the AWS X-Ray console. Read more about the AWS X-Ray Tracing Exporter for OpenTelemetry Collector.

Getting Started

Check out the links below for information on getting started with ADOT Python SDK:

Applications for integration testing - Auto-instrumentation

See an app used for integration testing with automatic instrumentation README.md for setup instructions.

Applications for integration testing - Manual instrumentation

See an app used for integration testing with manual instrumentation README.md for setup instructions.

Requirements

Python 3.5+ is required to use OpenTelemetry Python. Check your currently installed Python version using python3 -V. For more information about supported Python versions, see the OpenTelemetry Python package on PyPi.

Useful Links

Find out more about AWS X-Ray Tracing with Opentelemetry Python at the following links.

Security

See CONTRIBUTING for more information.

License

This project is licensed under the Apache-2.0 License.