observability-edot-java-migrate

elastic/agent-skills

Migrate Java applications from classic Elastic APM agent to EDOT Java agent.

What is observability-edot-java-migrate?

Guides migration from elastic-apm-agent.jar to elastic-otel-javaagent.jar for Java applications. Use this when switching to OpenTelemetry-based observability with Elastic's EDOT Java agent.

Remove classic APM agent references and dependencies
Download and attach elastic-otel-javaagent.jar via -javaagent flag
Configure required OTEL environment variables (OTEL_SERVICE_NAME, OTEL_EXPORTER_OTLP_ENDPOINT, OTEL_EXPORTER_OTLP_HEADERS)
Replace APM Server URLs with managed OTLP endpoints or EDOT Collector URLs
Verify no dual-agent conflicts on the same JVM

How to install observability-edot-java-migrate

npx skills add https://github.com/elastic/agent-skills --skill observability-edot-java-migrate

Prerequisites

Java application currently using elastic-apm-agent.jar
Access to Elastic documentation and migration guide
Managed OTLP endpoint or EDOT Collector URL
Valid API key or bearer token for authentication

Claude Code

Cursor

Windsurf

Cline

How to use observability-edot-java-migrate

1.Read the official EDOT Java migration guide before starting
2.Remove all elastic-apm-agent.jar references and co.elastic.apm Maven/Gradle dependencies
3.Delete elasticapm.properties file and all ELASTIC_APM_* environment variables
4.Download elastic-otel-javaagent.jar from Maven Central
5.Attach the agent using -javaagent:/path/to/elastic-otel-javaagent.jar or JAVA_TOOL_OPTIONS
6.Set OTEL_SERVICE_NAME environment variable
7.Set OTEL_EXPORTER_OTLP_ENDPOINT to your managed OTLP endpoint or EDOT Collector URL (not APM Server)
8.Set OTEL_EXPORTER_OTLP_HEADERS with Authorization header (ApiKey or Bearer token)

Use cases

Good for

Upgrading existing Java applications from classic Elastic APM to OpenTelemetry-based EDOT agent
Switching to managed OTLP endpoints for centralized observability
Migrating authentication from secret tokens to API keys or bearer tokens
Consolidating multiple Java services under OTEL_SERVICE_NAME configuration

Who it's for

Java developers managing Elastic APM deployments
DevOps engineers upgrading observability infrastructure
Teams migrating to OpenTelemetry standards

observability-edot-java-migrate FAQ

Can I run both classic APM agent and EDOT agent simultaneously?

No. Never run both agents on the same JVM. You must completely remove the classic agent before deploying EDOT.

What OTEL_EXPORTER_OTLP_ENDPOINT should I use?

Use your managed OTLP endpoint or EDOT Collector URL. Do NOT reuse the old ELASTIC_APM_SERVER_URL or APM Server URL (which contain apm-server, :8200, or /intake/v2/events).

How do I authenticate with the EDOT agent?

Set OTEL_EXPORTER_OTLP_HEADERS to either 'Authorization=ApiKey <key>' or 'Authorization=Bearer <token>'. This replaces ELASTIC_APM_SECRET_TOKEN and ELASTIC_APM_API_KEY.

Do I need to set OTEL_TRACES_EXPORTER and other exporter variables?

No. Do not set OTEL_TRACES_EXPORTER, OTEL_METRICS_EXPORTER, or OTEL_LOGS_EXPORTER—the defaults are already correct for EDOT.

What replaces ELASTIC_APM_SERVICE_NAME?

Use OTEL_SERVICE_NAME instead. Set it to the same service name or a new name for your application.

Full instructions (SKILL.md)

Source of truth, from elastic/agent-skills.

name: observability-edot-java-migrate description: > Migrate a Java application from the classic Elastic APM Java agent to the EDOT Java agent. Use when switching from elastic-apm-agent.jar to elastic-otel-javaagent.jar. metadata: author: elastic version: 0.1.1

EDOT Java Migration

Read the migration guide before making changes:

Guidelines

Remove ALL classic APM references: elastic-apm-agent.jar, elasticapm.properties, all ELASTIC_APM_* env vars, and any co.elastic.apm Maven/Gradle dependencies
Use elastic-otel-javaagent.jar (download from Maven Central, not a Maven/Gradle compile dependency)
Attach via -javaagent:/path/to/elastic-otel-javaagent.jar or JAVA_TOOL_OPTIONS="-javaagent:/path/to/elastic-otel-javaagent.jar" — without this the agent does nothing
Set exactly three required environment variables:
- OTEL_SERVICE_NAME (replaces ELASTIC_APM_SERVICE_NAME)
- OTEL_EXPORTER_OTLP_ENDPOINT — must be the 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)
- OTEL_EXPORTER_OTLP_HEADERS — "Authorization=ApiKey <key>" or "Authorization=Bearer <token>" (replaces ELASTIC_APM_SECRET_TOKEN / API_KEY)
Do NOT set OTEL_TRACES_EXPORTER, OTEL_METRICS_EXPORTER, or OTEL_LOGS_EXPORTER — the defaults are already correct
Never run both classic Elastic APM agent and EDOT agent on the same JVM