Skip to content

framework-elastic_otel_java_agent.md

Latest commit

 

History

History
84 lines (56 loc) · 5.53 KB

framework-elastic_otel_java_agent.md

File metadata and controls

84 lines (56 loc) · 5.53 KB
Raw

Elastic OTel Java Agent Framework

The Elastic OTel Java Agent Framework causes an application to be automatically configured to work with the Elastic Distribution of OpenTelemetry Java.

Detection Criterion Existence of a bound Elastic OTel service. The service must have a name containing, or a label or tag matching, elastic-otel, edot-java, or elastic-edot, and the combined service and environment configuration must provide an OTLP endpoint plus authentication credentials. The framework can also be enabled explicitly with ELASTIC_OTEL_AGENT when the same required configuration is present.
Tags elastic-otel-javaagent=<version>

Tags are printed to standard output by the buildpack detect script.

User-Provided Service

Users can provide their own Elastic OTel service. A user-provided service must have a name containing or a tag matching elastic-otel, edot-java, or elastic-edot so that the framework configures the application with the Elastic OTel Java agent.

The credential payload can contain the following entries.

Name Description
otel.exporter.otlp.endpoint The OTLP endpoint for your Elastic deployment or EDOT Collector. Aliases: otlp_endpoint, otlpEndpoint, endpoint.
otel.exporter.otlp.headers Explicit OTLP headers, for example Authorization=ApiKey <key>. If present, this takes precedence over derived authentication headers.
api_key Elastic API key. Converted to otel.exporter.otlp.headers=Authorization=ApiKey <key>.
secret_token Bearer token. Converted to otel.exporter.otlp.headers=Authorization=Bearer <token>.
otel.* Any additional OpenTelemetry configuration applied as JVM system properties.
elastic.otel.* Any additional Elastic OTel configuration applied as JVM system properties.

Creating an Elastic OTel User-Provided Service

Example minimal configuration:

cf cups my-elastic-otel-service -p '{"otel.exporter.otlp.endpoint":"https://my-deployment.ingest.us-west1.gcp.cloud.es.io","api_key":"my-api-key"}'

Example configuration with explicit OTLP headers and resource attributes:

cf cups my-elastic-otel-service -p '{"otel.exporter.otlp.endpoint":"https://my-deployment.ingest.us-west1.gcp.cloud.es.io","otel.exporter.otlp.headers":"Authorization=ApiKey my-api-key","otel.resource.attributes":"deployment.environment.name=production"}'

Bind your application to the service using:

cf bind-service my-app-name my-elastic-otel-service

or use the services block in the application manifest file.

Configuration

For general information on configuring the buildpack, including how to specify configuration values through environment variables, refer to Configuration and Extension.

The framework uses the dependency version configured in manifest.yml.

Name Description
version The version of Elastic OTel Java agent to use. The current buildpack manifest uses the elastic-otel-javaagent dependency.

The framework sets otel.service.name from service credentials, then OTEL_SERVICE_NAME, then VCAP_APPLICATION.application_name, using the first configured value. It also sets deployment.environment.name from VCAP_APPLICATION.space_name when otel.resource.attributes is not configured. Generic OTLP environment variables do not select the Elastic distribution by themselves; set ELASTIC_OTEL_AGENT to choose it explicitly.

Authentication headers are provided through OTEL_EXPORTER_OTLP_HEADERS rather than a JVM system property. When the headers come from service credentials, the framework resolves them from VCAP_SERVICES when the application starts. This keeps credentials out of the JVM command line and allows credential rotation with an application restart instead of a restage.

Warning Do not bind this framework alongside the Elastic APM Agent, OpenTelemetry Javaagent, Splunk OTel Java Agent, or another Java agent framework for the same application. Running multiple Java agents in the same JVM can cause duplicate telemetry or conflicting instrumentation.

Troubleshooting: Multiple Agents or Wrong Agent

  • Elastic and Splunk agents both start: OTEL_EXPORTER_OTLP_ENDPOINT is set as an environment variable during staging. Also set ELASTIC_OTEL_AGENT=true, or put the endpoint in the service credentials instead.
  • Upstream OpenTelemetry agent starts instead of Elastic: The Elastic service lacks authentication credentials. Add api_key or otel.exporter.otlp.headers.
  • Elastic and OpenTelemetry agents both start: An otel-collector service or another otel-named or otel-tagged service is also bound. Unbind it.
  • Telemetry does not reach Elastic: OTEL_EXPORTER_OTLP_ENDPOINT, set as an environment variable during staging, overrides the endpoint from the service binding. Remove it, or make sure it points to Elastic.

Migration From Elastic APM Agent

The Elastic OTel Java agent uses OTLP configuration. It does not use Elastic APM agent settings such as server_url or secret_token with the elastic.apm.* prefix.

When migrating, create a new service binding named or tagged for Elastic OTel and provide an OTLP endpoint plus otel.exporter.otlp.headers or api_key.