Loading

Migrate to EDOT Python from the Elastic APM Python agent

Serverless Observability Stack EDOT Python

Learn the differences between the Elastic APM Python agent and the Elastic Distribution of OpenTelemetry Python (EDOT Python).

Follow the steps to migrate your instrumentation and settings. For step-by-step instructions on setting up EDOT Python refer to Setup.

Follow these steps to migrate:

  1. Remove any configuration and setup code needed by Elastic APM Python Agent from your application source code.
  2. Migrate any usage of Elastic APM Python Agent API to manual instrumentation with OpenTelemetry API in the application source code.
  3. Follow the setup documentation on to install and configure EDOT Python.

The following are Elastic APM Python agent settings that you can migrate to EDOT Python.

The Elastic api_key option corresponds to the OpenTelemetry OTEL_EXPORTER_OTLP_HEADERS environment variable.

For example: OTEL_EXPORTER_OTLP_HEADERS="Authorization=ApiKey an_api_key".

The Elastic capture_headers option corresponds to the OpenTelemetry Python OTEL_INSTRUMENTATION_HTTP_CAPTURE_HEADERS_SERVER_REQUEST and OTEL_INSTRUMENTATION_HTTP_CAPTURE_HEADERS_SERVER_RESPONSE environment variables, refer to OpenTelemetry documentation.

For sanitization of these captured headers you can use the OTEL_INSTRUMENTATION_HTTP_CAPTURE_HEADERS_SANITIZE_FIELDS environment variable. For example OTEL_INSTRUMENTATION_HTTP_CAPTURE_HEADERS_SANITIZE_FIELDS=".*session.*,set-cookie" replaces the value of headers such as session-id and set-cookie with [REDACTED] in the span.

The Elastic cloud_provider option corresponds to listing individual resource detectors using the OpenTelemetry Python OTEL_EXPERIMENTAL_RESOURCE_DETECTORS environment variable, refer to default value of OTEL_EXPERIMENTAL_RESOURCE_DETECTORS. The default value is dynamic based on the platform and is analogous to auto.

The Elastic django_transaction_name_from_route option does not have a correspondent option, but is activated by default in OpenTelemetry Python.

The Elastic django_transaction_name_from_route option does not have a correspondent option, but is activated by default in OpenTelemetry Python.

The Elastic enabled option corresponds to the OpenTelemetry OTEL_SDK_DISABLED environment variable.

The Elastic environment option corresponds to setting the deployment.environment.name key in OTEL_RESOURCE_ATTRIBUTES.

For example: OTEL_RESOURCE_ATTRIBUTES=deployment.environment.name=testing.

The Elastic global_labels option corresponds to adding key=value comma separated pairs in OTEL_RESOURCE_ATTRIBUTES.

For example: OTEL_RESOURCE_ATTRIBUTES=alice=first,bob=second. Such labels will result in resource.attributes.key=value attributes on the server, e.g. resource.attributes.alice=first

The Elastic include_process_args option corresponds to include the ProcessResourceDetector to OTEL_EXPERIMENTAL_RESOURCE_DETECTORS environment variable, refer to the default value of OTEL_EXPERIMENTAL_RESOURCE_DETECTORS.

The Elastic metrics_interval corresponds to the OpenTelemetry OTEL_METRIC_EXPORT_INTERVAL environment variable.

For example: OTEL_METRIC_EXPORT_INTERVAL=30000.

The Elastic sanitize_field_names option does not have a complete equivalent. For captured headers sanitization, refer to capture_headers.

The Elastic secret_token option corresponds to the OpenTelemetry OTEL_EXPORTER_OTLP_HEADERS environment variable.

For example: OTEL_EXPORTER_OTLP_HEADERS="Authorization=ApiKey an_apm_secret_token".

The Elastic server_timeout option corresponds to the OpenTelemetry OTEL_EXPORTER_OTLP_TIMEOUT environment variable.

The Elastic server_url option corresponds to the OpenTelemetry OTEL_EXPORTER_OTLP_ENDPOINT environment variable.

The Elastic service_name option corresponds to the OpenTelemetry OTEL_SERVICE_NAME environment variable.

You can also set the service name using OTEL_RESOURCE_ATTRIBUTES.

For example: OTEL_RESOURCE_ATTRIBUTES=service.name=myservice. If OTEL_SERVICE_NAME is set, it takes precedence over the resource attribute.

The Elastic service_version option corresponds to setting the service.version key in OTEL_RESOURCE_ATTRIBUTES.

For example: OTEL_RESOURCE_ATTRIBUTES=service.version=1.2.3.

The Elastic transaction_ignore_urls and transactions_ignore_patterns options correspond to setting the OTEL_PYTHON_EXCLUDED_URLS environment variable.

Evaluate the differences in performance overhead between EDOT Python and Elastic APM Python agent.

The following limitations apply when migrating to EDOT Python.

You can manage EDOT Python configurations through the central configuration feature in the Applications UI.

Refer to Central configuration for more information.

A custom lambda layer for the Elastic Distribution of OpenTelemetry Python is not currently available. Refer to the Lambda Auto-Instrumentation.

The following libraries are currently missing an OpenTelemetry equivalent:

  • Azure storage and Azure queue
  • aiobotocore
  • aiomysql
  • aioredis
  • Graphene
  • httplib2
  • pylibmc
  • pyodbc
  • python-memcached
  • Sanic
  • zlib

EDOT Python lacks a structlog integration at the moment.

EDOT Python does not implement span compression.

EDOT Python is not sending metrics that power the Breakdown metrics.

If you're encountering issues during migration, refer to the EDOT Python troubleshooting guide.