Migrating to EDOT Python from the Elastic APM Python Agent

This guide will highlight the major differences between the Elastic APM Python agent and the Elastic Distribution of OpenTelemetry Python (EDOT Python). For step-by-step instructions on setting up EDOT Python refer to the Setup.

We are a distribution

As a distribution of OpenTelemetry, EDOT Python follows certain standards, but there is still some space for innovation.

EDOT Python principles

Bold on auto-instrumentation

We have chosen to make auto-instrumentation as simple as possible so you can just focus on your code; we favored an experience that requires minimal changes to your application code. The upstream OpenTelemetry configuration has more options than the distribution requires. Our default configuration is listed here.

Bring your own instrumentation

In EDOT Python we decided to not ship all the available instrumentations in order to accommodate environments where installing more packages than requested may be an issue. We provide a tool to discover available instrumentations automatically that can be added to your build workflow. See Get started.

Performance overhead

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

Limitations

Central and Dynamic configuration

Currently EDOT Python does not have an equivalent of the central configuration feature that the Elastic APM Python agent supports. When using EDOT Python, all the configurations are static and should be provided to the application with other configurations, e.g. environment variables.

AWS lambda

At the moment, we are not building a custom lambda layer for our Python distribution. You can refer to the upstream Lambda Auto-Instrumentation.

Missing instrumentations

Not all instrumentations we have in Elastic APM Python Agent have an OpenTelemetry counterpart. But we may port them if they are requested by users.

At the time of writing these docs, the following libraries are missing an OpenTelemetry instrumentation:

  • aiobotocore
  • aiomysql
  • aiopg
  • aioredis
  • Azure storage and Azure queue
  • Graphene
  • httplib2
  • pylibmc
  • pyodbc
  • Sanic
  • zlib

Integration with structured logging

EDOT Python does not have any structlog integration at the moment.

Span compression

EDOT Python does not implement span compression.

Breakdown metrics

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

Migration steps

  • remove any configuration and setup code needed by Elastic APM Python Agent from your application source code.
  • migrate any eventual usage of Elastic APM Python Agent API for manual instrumentation with OpenTelemetry API in the application source code.
  • follow setup documentation on how to install and configure EDOT Python

Option reference

This list contains Elastic APM Python agent configuration options that can be migrated to EDOT Python configuration because they have an equivalent in OpenTelemetry:

api_key

The Elastic api_key option corresponds to the OpenTelemetry OTEL_EXPORTER_OTLP_HEADERS option.

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

enabled

The Elastic enabled option corresponds to the OpenTelemetry OTEL_SDK_DISABLED option.

environment

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.

global_labels

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 labels.key=value attributes on the server, e.g. labels.alice=first

metrics_interval

The Elastic metrics_interval corresponds to the OpenTelemetry OTEL_METRIC_EXPORT_INTERVAL option.

For example: OTEL_METRIC_EXPORT_INTERVAL=30000.

secret_token

The Elastic secret_token option corresponds to the OpenTelemetry OTEL_EXPORTER_OTLP_HEADERS option.

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

server_url

The Elastic server_url option corresponds to the OpenTelemetry OTEL_EXPORTER_OTLP_ENDPOINT option.

service_name

The Elastic service_name option corresponds to the OpenTelemetry OTEL_SERVICE_NAME option.

The service name value can also be set 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.

service_version

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.