AWS Distro for OpenTelemetry Python Language

This repo hosts documentation and sample apps for the ADOT Python library which provides the AWS service integrations for traces and metrics for the OpenTelemetry Python library. The library can be configured to support trace applications 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 in Python:

• Tracing with Automatic Instrumentation
• Tracing with Manual Instrumentation

Applications for integration testing - Auto-instrumentation (DEPRECATED)

WARNING: This sample app is deprecated and is no longer maintained. Please use the new standardized sample apps.

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

Applications for integration testing - Manual instrumentation (DEPRECATED)

WARNING: This sample app is deprecated and is no longer maintained. Please use the new standardized sample apps.

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.

• OpenTelemetry Python Core GitHub
• OpenTelemetry Python Contrib GitHub
• AWS OpenTelemetry Python SDK Extension Package
• AWS OpenTelemetry Python X-Ray Propagator Package
• AWS Distro for OpenTelemetry

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.