Skip to content

framework-elastic_otel_java_agent.md

Latest commit

 

History

History
75 lines (50 loc) · 4.03 KB

framework-elastic_otel_java_agent.md

File metadata and controls

75 lines (50 loc) · 4.03 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, label, or tag containing elastic-otel and must provide an OTLP endpoint plus authentication credentials. The framework can also be enabled explicitly with ELASTIC_OTEL_AGENT.
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 or tag with elastic-otel in it 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 VCAP_APPLICATION.application_name if it is not configured in service credentials or OTEL_SERVICE_NAME. It also sets deployment.environment.name from VCAP_APPLICATION.space_name when otel.resource.attributes is not configured.

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.

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.