Skip to content

docs: update migration guide #423

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 5 commits into from
Nov 11, 2025
+45 −10
Merged

docs: update migration guide #423

Changes from 2 commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
67c3dad
docs/reference/migration: add more options that have counterparts in …
xrmx Nov 10, 2025
999cc09
Fix typos
xrmx Nov 10, 2025
4f96f36
Always wrap otel env var with _ as code
xrmx Nov 11, 2025
ce214df
Apply suggestions from code review
xrmx Nov 11, 2025
6a06096
Apply suggestions from code review
xrmx Nov 11, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
47 changes: 41 additions & 6 deletions docs/reference/edot-python/migration.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -34,13 +34,32 @@ The following are Elastic APM Python agent settings that you can migrate to EDOT

### `api_key`

The Elastic [`api_key`](apm-agent-python://reference/configuration.md#config-api-key) option corresponds to the OpenTelemetry [OTEL_EXPORTER_OTLP_HEADERS](https://opentelemetry.io/docs/concepts/sdk-configuration/otlp-exporter-configuration/#otel_exporter_otlp_headers) option.
The Elastic [`api_key`](apm-agent-python://reference/configuration.md#config-api-key) option corresponds to the OpenTelemetry [OTEL_EXPORTER_OTLP_HEADERS](https://opentelemetry.io/docs/concepts/sdk-configuration/otlp-exporter-configuration/#otel_exporter_otlp_headers) environment variable.

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

### `capture_headers`

The Elastic [`capture_headers`](apm-agent-python://reference/configuration.md#config-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, see [OpenTelemetry documentation](https://github.com/open-telemetry/opentelemetry.io/edit/main/content/en/docs/zero-code/python/example.md/#capture-http-request-and-response-headers).

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"` will replace the value of headers such as `session-id` and `set-cookie` with `[REDACTED]` in the span.

### `cloud_provider`

The Elastic [`cloud_provider`](apm-agent-python://reference/configuration.md#config-cloud-provider) option corresponds to listing individual resource detectors using the OpenTelemetry Python `OTEL_EXPERIMENTAL_RESOURCE_DETECTORS` environment variable, see [default value of OTEL_EXPERIMENTAL_RESOURCE_DETECTORS](configuration.md#differences-from-opentelemetry-python). The default value is dynamic based on the platform and is analogous to `auto`.

### `django_autoinsert_middleware`

The Elastic [`django_transaction_name_from_route`](apm-agent-python://reference/configuration.md#config-django-autoinsert-middleware) option does not have a correspondant option but is enabled by default in OpenTelemetry Python.

### `django_transaction_name_from_route`

The Elastic [`django_transaction_name_from_route`](apm-agent-python://reference/configuration.md#config-django-transaction-name-from-route) option does not have a correspondant option but is enabled by default in OpenTelemetry Python.

### `enabled`

The Elastic [`enabled`](apm-agent-python://reference/configuration.md#config-enabled) option corresponds to the OpenTelemetry [OTEL_SDK_DISABLED](https://opentelemetry.io/docs/specs/otel/configuration/sdk-environment-variables/#general-sdk-configuration) option.
The Elastic [`enabled`](apm-agent-python://reference/configuration.md#config-enabled) option corresponds to the OpenTelemetry [OTEL_SDK_DISABLED](https://opentelemetry.io/docs/specs/otel/configuration/sdk-environment-variables/#general-sdk-configuration) environment_variable.

### `environment`

Expand All @@ -54,25 +73,37 @@ The Elastic [`global_labels`](apm-agent-python://reference/configuration.md#conf

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

### `include_process_args`

The Elastic [`include_process_args`](apm-agent-python://reference/configuration.md#config-include-process-args) option corresponds to include the `ProcessResourceDetector` to `OTEL_EXPERIMENTAL_RESOURCE_DETECTORS` environment variable, see [default value of OTEL_EXPERIMENTAL_RESOURCE_DETECTORS](configuration.md#differences-from-opentelemetry-python).

### `metrics_interval`

The Elastic [`metrics_interval`](apm-agent-python://reference/configuration.md#config-metrics_interval) corresponds to the OpenTelemetry [OTEL_METRIC_EXPORT_INTERVAL](https://opentelemetry.io/docs/specs/otel/configuration/sdk-environment-variables/#periodic-exporting-metricreader) option.
The Elastic [`metrics_interval`](apm-agent-python://reference/configuration.md#config-metrics_interval) corresponds to the OpenTelemetry [OTEL_METRIC_EXPORT_INTERVAL](https://opentelemetry.io/docs/specs/otel/configuration/sdk-environment-variables/#periodic-exporting-metricreader) environment variable.

For example: `OTEL_METRIC_EXPORT_INTERVAL=30000`.

### `sanitize_field_names`

The Elastic [`sanitize_field_names`](apm-agent-python://reference/configuration.md#config-sanitize-field-names) option used not have a complete counterpart, for captured headers sanitization see [capture_headers](#capture_headers).

### `secret_token`

The Elastic [`secret_token`](apm-agent-python://reference/configuration.md#config-secret-token) option corresponds to the OpenTelemetry [OTEL_EXPORTER_OTLP_HEADERS](https://opentelemetry.io/docs/concepts/sdk-configuration/otlp-exporter-configuration/#otel_exporter_otlp_headers) option.
The Elastic [`secret_token`](apm-agent-python://reference/configuration.md#config-secret-token) option corresponds to the OpenTelemetry [OTEL_EXPORTER_OTLP_HEADERS](https://opentelemetry.io/docs/concepts/sdk-configuration/otlp-exporter-configuration/#otel_exporter_otlp_headers) environment variable.

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

### `server_timeout`

The Elastic [`server_timeout`](apm-agent-python://reference/configuration.md#config-server-timeout) option corresponds to the OpenTelemetry [`OTEL_EXPORTER_OTLP_TIMEOUT`](https://opentelemetry.io/docs/languages/sdk-configuration/otlp-exporter/#otel_exporter_otlp_timeout) environment variable.

### `server_url`

The Elastic [`server_url`](apm-agent-python://reference/configuration.md#config-server-url) option corresponds to the OpenTelemetry [`OTEL_EXPORTER_OTLP_ENDPOINT`](https://opentelemetry.io/docs/concepts/sdk-configuration/otlp-exporter-configuration/#otel_exporter_otlp_endpoint) option.
The Elastic [`server_url`](apm-agent-python://reference/configuration.md#config-server-url) option corresponds to the OpenTelemetry [`OTEL_EXPORTER_OTLP_ENDPOINT`](https://opentelemetry.io/docs/concepts/sdk-configuration/otlp-exporter-configuration/#otel_exporter_otlp_endpoint) environment variable.

### `service_name`

The Elastic [`service_name`](apm-agent-python://reference/configuration.md#config-service-name) option corresponds to the OpenTelemetry [OTEL_SERVICE_NAME](https://opentelemetry.io/docs/concepts/sdk-configuration/general-sdk-configuration/#otel_service_name) option.
The Elastic [`service_name`](apm-agent-python://reference/configuration.md#config-service-name) option corresponds to the OpenTelemetry [OTEL_SERVICE_NAME](https://opentelemetry.io/docs/concepts/sdk-configuration/general-sdk-configuration/#otel_service_name) environment variable.

You can also set the service name using [OTEL_RESOURCE_ATTRIBUTES](https://opentelemetry.io/docs/concepts/sdk-configuration/general-sdk-configuration/#otel_resource_attributes).

Expand All @@ -84,6 +115,10 @@ The Elastic [`service_version`](apm-agent-python://reference/configuration.md#co

For example: `OTEL_RESOURCE_ATTRIBUTES=service.version=1.2.3`.

### `transaction_ignore_urls` and `transactions_ignore_patterns`

The Elastic [`transaction_ignore_urls`](apm-agent-python://reference/configuration.md#config-transaction-ignore-urls) and [`transactions_ignore_patterns`](apm-agent-python://reference/configuration.md#config-transactions-ignore-patterns) options correspond to setting the [OTEL_PYTHON_EXCLUDED_URLS](https://opentelemetry.io/docs/zero-code/python/configuration/#excluded-urls) environment variable.

## Performance overhead

Evaluate the [differences in performance overhead](/reference/edot-python/overhead.md) between EDOT Python and Elastic APM Python agent.
Expand Down
Loading