Theminimal configuration section provides a recommended starting point for EDOT Java configuration.

Seeconfiguration options for details on the supported configuration options andconfiguration methods for how to provide them.

This configuration is provided usingenvironment variables, otherconfiguration methods are also supported.

# service name: mandatory for integration in UI and correlationOTEL_SERVICE_NAME=my-service# resource attributes: recommended for integration in UI and correlation, can also include service.nameOTEL_RESOURCE_ATTRIBUTES='service.version=1.0,deployment.environment.name=production'# exporter endpoint: mandatory if not using a local Collector accessible on http://localhost:4317OTEL_EXPORTER_OTLP_ENDPOINT=https://my-otel-collector# exporter authentication: mandatory if endpoint requires authenticationOTEL_EXPORTER_OTLP_HEADERS='Authorization=ApiKey mySecretApiKey'

For authentication, theOTEL_EXPORTER_OTLP_HEADERS can also be used with an APM secret token:

OTEL_EXPORTER_OTLP_HEADERS='Authorization=Bearer mySecretToken'

EDOT Java instrumentation agent is based on OpenTelemetry JavaSDK andInstrumentation, and thus supports the followingconfiguration options:

• OpenTelemetry Java instrumentation configuration options
• OpenTelemetry Java SDK configuration options

EDOT Java uses different defaults than the OpenTelemetry Java instrumentation for the following configuration options:

(*) default value set todelta only if not already explicitly set.

The EDOT Java instrumentation agent also provides configuration options for each of thesupported features.This table only contains minimal configuration, see each respective feature for exhaustive configuration options documentation.

When using the Elasticsearch Java API client, spans for Elasticsearch operations are generated directly by the client’s built-in OpenTelemetry instrumentation.

Because the client owns the instrumentation, certain fields, such as the search request body reported asspan.db.statement, are only captured when the Elasticsearch client’s OpenTelemetry options are turned on.

For more details on instrumentation settings in the Elasticsearch Java API client, refer to theElasticsearch Java client documentation.

You might need this configuration if you notice thatspan.db.statement is missing for Elasticsearch search operations and you use:

• Elasticsearch Java API client 8.x or 9.x

• EDOT Java SDK or another OpenTelemetry Java SDK

• The APM Java Agent

Set either one of the following Elasticsearch client instrumentation options:

-Dotel.instrumentation.elasticsearch.capture-search-query=true

OTEL_INSTRUMENTATION_ELASTICSEARCH_CAPTURE_SEARCH_QUERY=true

The flagotel.instrumentation.elasticsearch.enabled is turned on by default, so you typically only need to activatecapture-search-query.

When activated, the Elasticsearch client includes the search request body in the generated spans, and EDOT or OTel exports this value asspan.db.statement.

APM Agent Central Configuration lets you configure EDOT Java instances remotely, seeCentral configuration docs for more details.

To activate central configuration, set theELASTIC_OTEL_OPAMP_ENDPOINT environment variable to the OpAMP server endpoint.

export ELASTIC_OTEL_OPAMP_ENDPOINT=http://localhost:4320/v1/opamp

To deactivate central configuration, remove theELASTIC_OTEL_OPAMP_ENDPOINT environment variable and restart the instrumented application.

You can modify the following settings for EDOT Java through APM Agent Central Configuration:

Dynamic settings can be changed without having to restart the application.

Configuration can be provided through multipleconfiguration methods:

• Environment variables
• System properties
• Properties configuration file

Configuration options are applied with the following priorities:

• environment variables take precedence oversystem properties andproperties configuration file.
• system properties take precedence onproperties configuration file.

Environment variables provide a cross-platform way to configure EDOT Java and is especially useful in containerized environments.

Define environment variables before starting the JVM:

export OTEL_SERVICE_NAME=my-servicejava ...

These configuration options can be seen by anything that can see the executed command-line.

Define system properties at the JVM start, usually on the command-line:

java -Dotel.service.name=my-service ...

When modifying the JVM command line options is not possible, using theJAVA_TOOL_OPTIONS environment variable couldbe used to provide the system properties, for example:

export JAVA_TOOL_OPTIONS='-Dotel.service.name=my-service'

EDOT Java can be configured using a java properties configuration file.

Before starting the JVM, create and populate the configuration file and specify where to find it:

echo otel.service.name=my-service > my.propertiesjava -Dotel.javaagent.configuration-file=my.properties ...

The EDOT Java agent provides the ability to control the agent log verbosity by setting the log level with theELASTIC_OTEL_JAVAAGENT_LOG_LEVEL configuration option (INFO by default).

The following log levels are supported:TRACE,DEBUG,INFO,WARN,ERROR,FATAL andOFF.

Fortroubleshooting, theELASTIC_OTEL_JAVAAGENT_LOG_LEVEL=DEBUG is a recommended alternative toOTEL_JAVAAGENT_DEBUG=true as it provides span information in JSON format.

This feature relies on theOTEL_JAVAAGENT_LOGGING configuration option to be set toelastic (default), thesimple value from contrib is not supported.

SettingOTEL_JAVAAGENT_LOGGING=none orELASTIC_OTEL_JAVAAGENT_LOG_LEVEL=OFF disables agent logging feature.

SettingOTEL_JAVAAGENT_LOGGING=application will disable EDOT agent logging feature and attempt to use the application logger.Asdocumented here in the contrib documentation,support for this depends on the application and logging libraries used.

The EDOT Java agent provides the ability to toggle the exporter endpoint certificate verification with theELASTIC_OTEL_VERIFY_SERVER_CERT configuration option (true by default).

When the endpoint certificate is not trusted by the JVM where the agent runs, the common symptom is security-related exceptions with the following message:unable to find valid certification path to requested target.

This is common in the following scenarios:

• When endpoint uses a self-signed certificate not trusted by the JVM
• When the certificate authority used by the endpoint certificate is not trusted by the JVM

One solution is to add the certificate or certificate authority to the JVM trust store, which requires modifying the JVM trust store.

If trust store modification is not possible or not practical, for example when troubleshooting or working with a local deployment, certificate verification can be disabled by settingELASTIC_OTEL_VERIFY_SERVER_CERT tofalse. This however need to be evaluated carefully as it lowers the communication security and could allow for man-in-the-middle attacks where the data could be intercepted between the agent and the collector endpoint.

To secure the connection to the OTLP endpoint using TLS, you can configure the following environment variables as documented in theOpenTelemetry OTLP Exporter specification:

Signal-specific variants are also supported:OTEL_EXPORTER_OTLP_{signal}_CERTIFICATE,OTEL_EXPORTER_OTLP_{signal}_CLIENT_CERTIFICATE, andOTEL_EXPORTER_OTLP_{signal}_CLIENT_KEY where{signal} is one ofTRACES,METRICS orLOGS.

To prevent logs from being exported, setOTEL_LOGS_EXPORTER tonone. However, application logs might still be gathered and exported by the Collector through thefilelog receiver.

To prevent application logs from being collected and exported by the Collector, refer toExclude paths from logs collection.