Loading

Set up the EDOT Java Agent

Elastic Stack Serverless Observability

Learn how to set up the Elastic Distribution of OpenTelemetry (EDOT) Java in various environments, including Kubernetes and others.

For Kubernetes, use the OTel Kubernetes Operator. The Operator also manages the auto-instrumentation of Java applications. Follow the quickstart guide for Kubernetes or learn more about instrumentation details on Kubernetes for Java.

For environments where modifying the JVM arguments or configuration is not possible, or when including the EDOT Java in the application binary is necessary or preferred, use the runtime attach setup option.

Follow the following Java setup guide for all other environments.

You can download the latest release version or snapshot version of the EDOT Java agent from the following links:

Latest release Latest snapshot
Maven Central Sonatype Nexus

Complete the steps in the Quickstart section that corresponds to your Elastic deployment model.

The minimal configuration to send data involves setting the values for OTEL_EXPORTER_OTLP_ENDPOINT and OTEL_EXPORTER_OTLP_HEADERS environment variables.

Set the service.name resource attribute explicitly with OTEL_SERVICE_NAME as it allows to qualify captured data and group multiple service instances together.

The following is an example that sets the OTEL_EXPORTER_OTLP_ENDPOINT, OTEL_EXPORTER_OTLP_HEADERS, and OTEL_SERVICE_NAME environment variables:

export OTEL_EXPORTER_OTLP_ENDPOINT=https://my-deployment.apm.us-west1.gcp.cloud.es.io
export OTEL_EXPORTER_OTLP_HEADERS="Authorization=ApiKey P....l"
export OTEL_SERVICE_NAME="my-awesome-service"

For more advanced configuration, refer to Configuration.

Configuration of those environment values depends on the deployment model.

When deployed locally, the EDOT Collector is accessible with http://localhost:4318 without authentication, no further configuration is required. The OTEL_EXPORTER_OTLP_ENDPOINT and OTEL_EXPORTER_OTLP_HEADERS environment variables do not have to be set.

When using a self-managed EDOT Collector, set the OTEL_EXPORTER_OTLP_ENDPOINT environment variable to the OTLP endpoint of your self-managed EDOT Collector. If EDOT Collector requires authentication, set OTEL_EXPORTER_OTLP_HEADERS to include Authorization=ApiKey <ELASTIC_API_KEY>.

Follow the Serverless quickstart guides to retrieve the <ELASTIC_OTLP_ENDPOINT> and the <ELASTIC_API_KEY>.

  • Set OTEL_EXPORTER_OTLP_ENDPOINT to <ELASTIC_OTLP_ENDPOINT>.
  • Set OTEL_EXPORTER_OTLP_HEADERS to include Authorization=ApiKey <ELASTIC_API_KEY>.

Connection to the EDOT Collector is managed by the OTel Kubernetes Operator. Follow the Quickstart Guides for Kubernetes.

Use the -javaagent: JVM argument with the path to agent jar. This requires to modify the JVM arguments and restart the application.

java \
-javaagent:/path/to/agent.jar \
-jar myapp.jar

When modifying the JVM command line arguments is not possible, use the JAVA_TOOL_OPTIONS environment variable to provide the -javaagent: argument or JVM system properties. When JAVA_TOOL_OPTIONS is set, all JVMs automatically use it, so make sure to limit the scope to the relevant JVMs.

Some application servers require manual steps or modification of their configuration files. Refer to dedicated instructions for more details.

For applications deployed with Kubernetes, use the OpenTelemetry Operator.