Configure the EDOT Python agent

Serverless Observability Stack EDOT Python

Configure the Elastic Distribution of OpenTelemetry Python (EDOT Python) to send data to Elastic.

Configure the OpenTelemetry SDK through the mechanisms documented on the OpenTelemetry website. EDOT Python is typically configured with OTEL_* environment variables defined by the OpenTelemetry spec. For example:

export OTEL_RESOURCE_ATTRIBUTES=service.name=<app-name>,deployment.environment.name=<env-name>
export OTEL_EXPORTER_OTLP_ENDPOINT=https://my-deployment.ingest.us-west1.gcp.cloud.es.io
export OTEL_EXPORTER_OTLP_HEADERS="Authorization=ApiKey P....l"
opentelemetry-instrument <command to start your service>
		

Because the Elastic Distribution of OpenTelemetry Python is an extension of OpenTelemetry Python, it supports both:

• General OpenTelemetry configuration options
• Specific configuration options that are only available in EDOT Python

Serverless Unavailable Stack Preview 9.1.0 EDOT Python Preview 1.4.0

APM Agent Central Configuration lets you configure EDOT Python instances remotely, see Central configuration docs for more details.

To activate central configuration, set the ELASTIC_OTEL_OPAMP_ENDPOINT environment variable to the OpAMP server endpoint.

export ELASTIC_OTEL_OPAMP_ENDPOINT=http://localhost:4320/v1/opamp
		

To deactivate central configuration, remove the ELASTIC_OTEL_OPAMP_ENDPOINT environment variable and restart the instrumented application.

Serverless Unavailable Stack Preview 9.1.0 EDOT Python Preview 1.10.0

If the OpAMP server is configured to require authentication set the ELASTIC_OTEL_OPAMP_HEADERS environment variable.

export ELASTIC_OTEL_OPAMP_HEADERS="Authorization=ApiKey an_api_key"
		

Serverless Unavailable Stack Preview 9.1.0 EDOT Python Preview 1.10.0

If the OpAMP Central configuration server requires mutual TLS to encrypt data in transit you need to set the following environment variables:

• ELASTIC_OTEL_OPAMP_CERTIFICATE: The path of the trusted certificate, in PEM format, to use when verifying a server’s TLS credentials, this may also be used if the server is using a self-signed certificate.
• ELASTIC_OTEL_OPAMP_CLIENT_CERTIFICATE: Client certificate/chain trust for clients private key path to use in mTLS communication in PEM format.
• ELASTIC_OTEL_OPAMP_CLIENT_KEY: Client private key path to use in mTLS communication in PEM format.

export ELASTIC_OTEL_OPAMP_CERTIFICATE=/path/to/rootCA.pem
export ELASTIC_OTEL_OPAMP_CLIENT_CERTIFICATE=/path/to/client.pem
export ELASTIC_OTEL_OPAMP_CLIENT_KEY=/path/to/client-key.pem
		

You can modify the following settings for EDOT Python through APM Agent Central Configuration:

Dynamic settings can be changed without having to restart the application.

EDOT Python supports all configuration options listed in the OpenTelemetry General SDK Configuration documentation and OpenTelemetry Python.

To secure the connection to the OTLP endpoint using TLS, you can configure the following environment variables:

Signal-specific variants are also supported: OTEL_EXPORTER_OTLP_{TRACES,METRICS,LOGS}_CERTIFICATE, OTEL_EXPORTER_OTLP_{TRACES,METRICS,LOGS}_CLIENT_CERTIFICATE, and OTEL_EXPORTER_OTLP_{TRACES,METRICS,LOGS}_CLIENT_KEY.

For more details, refer to the OpenTelemetry OTLP Exporter documentation.

Instrument Python logging module to format and forward logs in OTLP format is turned off by default and gated under a configuration environment variable:

export OTEL_PYTHON_LOGGING_AUTO_INSTRUMENTATION_ENABLED=true
		

You can capture HTTP headers as span attributes on both client and server HTTP instrumentations according to HTTP semantic conventions. Refer to http.request.header.<key> and http.response.header.<key> attributes.

EDOT Python Preview 1.11.0

To define which HTTP headers you want to capture, provide a comma-separated list of HTTP header names through the environment variables OTEL_INSTRUMENTATION_HTTP_CAPTURE_HEADERS_SERVER_REQUEST and OTEL_INSTRUMENTATION_HTTP_CAPTURE_HEADERS_SERVER_RESPONSE, for example:

export OTEL_INSTRUMENTATION_HTTP_CAPTURE_HEADERS_SERVER_REQUEST="Accept-Encoding,User-Agent,Referer"
export OTEL_INSTRUMENTATION_HTTP_CAPTURE_HEADERS_SERVER_RESPONSE="Last-Modified,Content-Type"
		

These configuration options are supported by the following HTTP server instrumentations:

• Aiohttp-server
• ASGI
• Django
• Falcon
• FastAPI
• Flask
• Pyramid
• Starlette
• Tornado
• WSGI

EDOT Python Planned

To define which HTTP headers you want to capture, provide a comma-separated list of HTTP header names through the environment variables OTEL_INSTRUMENTATION_HTTP_CAPTURE_HEADERS_CLIENT_REQUEST and OTEL_INSTRUMENTATION_HTTP_CAPTURE_HEADERS_CLIENT_RESPONSE, for example:

export OTEL_INSTRUMENTATION_HTTP_CAPTURE_HEADERS_CLIENT_REQUEST="Accept-Encoding,User-Agent,Referer"
export OTEL_INSTRUMENTATION_HTTP_CAPTURE_HEADERS_CLIENT_RESPONSE="Last-Modified,Content-Type"
		

These configuration options are supported by the following HTTP client instrumentations:

• Aiohttp-client
• httpx
• requests
• urllib
• urllib3

EDOT Python Preview 1.11.0

Some headers might contain sensitive data such as personally identifiable information (PII), session keys, passwords, and so on. To avoid storing this data, OpenTelemetry Python provides a sanitization system through the OTEL_INSTRUMENTATION_HTTP_CAPTURE_HEADERS_SANITIZE_FIELDS environment variable. Set the environment variable to a comma delimited list of HTTP header names to be sanitized. You can use use regular expressions. All header names are matched in a case-insensitive manner.

This example replaces the values of the set-cookie header and headers such as session-id that matches the provided regular expression with [REDACTED] in the span:

export OTEL_INSTRUMENTATION_HTTP_CAPTURE_HEADERS_SANITIZE_FIELDS=".*session.*,set-cookie"
		

EDOT Python uses different defaults than OpenTelemetry Python for the following configuration options:

ELASTIC_OTEL_ options are specific to Elastic and will always live in EDOT Python include the following.

LLM instrumentations implement the following configuration options:

To prevent logs from being exported, set OTEL_LOGS_EXPORTER to none. However, application logs might still be gathered and exported by the Collector through the filelog receiver.

To prevent application logs from being collected and exported by the Collector, refer to Exclude paths from logs collection.