Elastic Distribution of OpenTelemetry Python

Warning

The Elastic Distribution of OpenTelemetry Python is not yet recommended for production use. Functionality may be changed or removed in future releases. Alpha releases are not subject to the support SLA of official GA features.

We welcome your feedback! You can reach us by opening a GitHub issue or starting a discussion thread on the Elastic Discuss forum.

The Elastic Distribution of OpenTelemetry Python (EDOT Python) is a customized version of OpenTelemetry Python. EDOT Python makes it easier to get started using OpenTelemetry in your Python applications through strictly OpenTelemetry native means, while also providing a smooth and rich out of the box experience with Elastic Observability. It's an explicit goal of this distribution to introduce no new concepts in addition to those defined by the wider OpenTelemetry community.

With EDOT Python you have access to all the features of the OpenTelemetry Python agent plus:

• Access to improvements and bug fixes contributed by the Elastic team before the changes are available upstream in OpenTelemetry repositories.
• Access to optional features that can enhance OpenTelemetry data that is being sent to Elastic.
• Elastic-specific processors that ensure optimal compatibility when exporting OpenTelemetry signal data to an Elastic backend like an Elastic Observability deployment.
• Preconfigured collection of tracing and metrics signals, applying some opinionated defaults, such as which sources are collected by default.

Ready to try out EDOT Python? Follow the step-by-step instructions in Get started.

Read the docs

• Get started
• Manual instrumentation
• Configuration

Install

pip install elastic-opentelemetry

Usage

Our distribution does not install any instrumentation package by default, instead it relies on the edot-bootstrap command to scan the installed packages and install the available instrumentation, preferring EDOT variants when available. The following command will install all the instrumentations available for libraries found installed in your environment:

edot-bootstrap --action=install

It will be useful to add this command every time you need to deploy an updated version of your application, e.g. into your container image build process.

At runtime you have to make some environment variables available to provide the needed configuration. A service name is required to have your app easily recognizable from the other. Then you need to provide the authorization headers for authentication with Elastic cloud and the project endpoint where to send your data.

OTEL_RESOURCE_ATTRIBUTES=service.name=<app-name>
OTEL_EXPORTER_OTLP_HEADERS="Authorization=<authorization header value>"
OTEL_EXPORTER_OTLP_ENDPOINT=<your elastic cloud url>

We are done with the configuration and the last piece of the puzzle is wrapping your service invocation with opentelemetry-instrument that is the wrapper that provides automatic instrumentation:

opentelemetry-instrument <command to start your service>

For a web service running with gunicorn it may looks like:

opentelemetry-instrument gunicorn main:app

Configuration

The distribution supports all the configuration variables from OpenTelemetry Python project version 1.29.0.

Default configuration variables

This distribution sets the following defaults:

• OTEL_TRACES_EXPORTER: otlp
• OTEL_METRICS_EXPORTER: otlp
• OTEL_LOGS_EXPORTER: otlp
• OTEL_EXPORTER_OTLP_PROTOCOL: grpc
• OTEL_EXPERIMENTAL_RESOURCE_DETECTORS: process_runtime,os,otel,telemetry_distro,_gcp,aws_ec2,aws_ecs,aws_elastic_beanstalk,azure_app_service,azure_vm
• OTEL_METRICS_EXEMPLAR_FILTER: always_off
• OTEL_EXPORTER_OTLP_METRICS_TEMPORALITY_PREFERENCE: DELTA

Note

OTEL_EXPERIMENTAL_RESOURCE_DETECTORS cloud resource detectors are dynamically set. When running in a Kubernetes Pod it will be set to process_runtime,os,otel,telemetry_distro,_gcp,aws_eks.

Distribution specific configuration variables

• ELASTIC_OTEL_SYSTEM_METRICS_ENABLED (default: false): when sets to true sends system namespace metrics.

License

This software is licensed under the Apache License, version 2 ("Apache-2.0").