observability-edot-python-migrate
elastic/agent-skills
Migrate Python applications from classic Elastic APM agent to EDOT Python agent.
What is observability-edot-python-migrate?
This skill guides you through migrating a Python application from the elastic-apm package to elastic-opentelemetry (EDOT). Use it when you need to switch to OpenTelemetry-based instrumentation for better observability and future compatibility.
- Remove classic APM dependencies and configuration from your Python application
- Install and configure the elastic-opentelemetry package
- Run edot-bootstrap to auto-instrument detected libraries
- Wrap application entrypoint with opentelemetry-instrument for telemetry collection
- Replace APM environment variables with OTEL equivalents
How to install observability-edot-python-migrate
npx skills add https://github.com/elastic/agent-skills --skill observability-edot-python-migrate- Existing Python application using elastic-apm package
- Access to managed OTLP endpoint or EDOT Collector URL
- API key or bearer token for OTLP authentication
How to use observability-edot-python-migrate
- 1.Read the official EDOT Python migration guide from Elastic documentation
- 2.Remove all elastic-apm references from requirements.txt and application code (ElasticAPM initialization, elasticapm.contrib imports, ELASTIC_APM config blocks)
- 3.Install elastic-opentelemetry package by adding it to requirements.txt
- 4.Run edot-bootstrap --action=install during your container image build to install auto-instrumentation packages
- 5.Wrap your application entrypoint with opentelemetry-instrument (e.g., opentelemetry-instrument gunicorn app:app)
- 6.Set three required environment variables: OTEL_SERVICE_NAME, OTEL_EXPORTER_OTLP_ENDPOINT (use managed OTLP endpoint, not APM Server URL), and OTEL_EXPORTER_OTLP_HEADERS with your API key or bearer token
- 7.Verify telemetry is being collected and remove any old ELASTIC_APM_* environment variables
Use cases
- Upgrading an existing Flask or Django application from elastic-apm to EDOT
- Migrating a containerized Python service to use OpenTelemetry instrumentation
- Switching from APM Server to managed OTLP endpoint for observability
- Consolidating multiple Python microservices to use EDOT for consistent telemetry
- Preparing a Python application for future observability platform changes
- Python developers maintaining applications with Elastic APM instrumentation
- DevOps engineers managing Python service deployments
- Teams migrating to OpenTelemetry-based observability
- Elastic Cloud users upgrading their observability stack
observability-edot-python-migrate FAQ
No. Never run both classic elastic-apm and EDOT on the same application. You must fully remove the classic APM agent before deploying EDOT.
Use your managed OTLP endpoint or EDOT Collector URL. Do NOT reuse the old ELASTIC_APM_SERVER_URL value. Never use an APM Server URL (no apm-server, no :8200, no /intake/v2/events).
No. Do not set these variables—the defaults are already correct for EDOT.
Use OTEL_SERVICE_NAME instead. Set it to the same service name you used before.
Use OTEL_EXPORTER_OTLP_HEADERS with the value 'Authorization=ApiKey <key>' or 'Authorization=Bearer <token>' depending on your authentication method.
Full instructions (SKILL.md)
Source of truth, from elastic/agent-skills.
name: observability-edot-python-migrate description: > Migrate a Python application from the classic Elastic APM Python agent to the EDOT Python agent. Use when switching from elastic-apm to elastic-opentelemetry. metadata: author: elastic version: 0.1.0
EDOT Python Migration
Read the migration guide before making changes:
Guidelines
- Remove ALL classic APM references:
elastic-apmfrom requirements,ElasticAPM(app)/elasticapm.contrib.*from application code,app.config['ELASTIC_APM']blocks, and allELASTIC_APM_*env vars - Install
elastic-opentelemetryvia pip (add torequirements.txtor equivalent) - Run
edot-bootstrap --action=installduring image build to install auto-instrumentation packages for detected libraries - Wrap the application entrypoint with
opentelemetry-instrument— e.g.opentelemetry-instrument gunicorn app:app. Without this, no telemetry is collected - Set exactly three required environment variables:
OTEL_SERVICE_NAME(replacesELASTIC_APM_SERVICE_NAME)OTEL_EXPORTER_OTLP_ENDPOINT— must be the managed OTLP endpoint or EDOT Collector URL. Do NOT reuse the oldELASTIC_APM_SERVER_URLvalue. Never use an APM Server URL (noapm-server, no:8200, no/intake/v2/events)OTEL_EXPORTER_OTLP_HEADERS—"Authorization=ApiKey <key>"or"Authorization=Bearer <token>"(replacesELASTIC_APM_SECRET_TOKEN)
- Do NOT set
OTEL_TRACES_EXPORTER,OTEL_METRICS_EXPORTER, orOTEL_LOGS_EXPORTER— the defaults are already correct - Never run both classic
elastic-apmand EDOT on the same application
Examples
See the EDOT Python migration guide for complete examples.
Related skills
More from elastic/agent-skills and the wider catalog.
observability-k8s-investigation
>
observability-llm-obs
Monitor LLM performance, cost, tokens, and agentic workflows in Elastic.
observability-logs-search
Search and filter Observability logs with ES|QL to investigate incidents, errors, and anomalies.
observability-manage-slos
Create and manage SLOs in Elastic Observability using the Kibana API.
observability-service-health
Assess APM service health using SLOs, alerts, ML anomalies, latency, error rate, and dependencies.
security-alert-triage
Triage Elastic Security alerts: gather context, classify threats, create cases, and acknowledge.