--- title: OpenTelemetry bridge description: The Elastic APM OpenTelemetry bridge allows creating Elastic APM Transactions and Spans using the OpenTelemetry API. OpenTelemetry metrics are also collected... url: https://www.elastic.co/elastic/docs-builder/docs/3028/reference/apm/agents/java/opentelemetry-bridge products: - APM Agent - APM Java Agent applies_to: - Serverless Observability projects: Generally available - Elastic Stack: Generally available - Application Performance Monitoring Agent for Java: Generally available --- # OpenTelemetry bridge The Elastic APM OpenTelemetry bridge allows creating Elastic APM `Transactions` and `Spans` using the OpenTelemetry API. OpenTelemetry metrics are also collected. In other words, it translates the calls to the OpenTelemetry API to Elastic APM and thus allows for reusing existing instrumentation. While manual instrumentations using the OpenTelemetry API can be adapted to the Elastic APM Java agent, it’s not possible to use the instrumentations from [opentelemetry-java-instrumentation](https://github.com/open-telemetry/opentelemetry-java-instrumentation) in the context of the Elastic APM Java agent. However, you can use [opentelemetry-java-instrumentation](https://github.com/open-telemetry/opentelemetry-java-instrumentation) (aka the OpenTelemetry Java agent) and send the data to APM Server. See the [OpenTelemetry integration docs](https://docs-v3-preview.elastic.dev/elastic/docs-builder/docs/3028/solutions/observability/apm/opentelemetry) for more details. The first span of a service will be converted to an Elastic APM [`Transaction`](https://docs-v3-preview.elastic.dev/elastic/docs-builder/docs/3028/solutions/observability/apm/transactions), subsequent spans are mapped to Elastic APM [`Span`](https://docs-v3-preview.elastic.dev/elastic/docs-builder/docs/3028/solutions/observability/apm/spans). ## Getting started The first step in getting started with the OpenTelemetry API bridge is to declare a dependency to the API: ```xml io.opentelemetry opentelemetry-api ${version.opentelemetry} ``` ```groovy compile "io.opentelemetry:opentelemetry-api:$openTelemetryVersion" ``` The minimum required OpenTelemetry version is 1.4.0. ## Initialize tracer There’s no separate dependency needed for the bridge itself. The Java agent hooks into `GlobalOpenTelemetry` to return its own implementation of `OpenTelemetry` that is connected to the internal tracer of the agent. ```java import io.opentelemetry.api.GlobalOpenTelemetry; import io.opentelemetry.api.OpenTelemetry; import io.opentelemetry.api.trace.Tracer; OpenTelemetry openTelemetry = GlobalOpenTelemetry.get(); Tracer tracer = openTelemetry.getTracer(""); ``` To disable that behavior, and to rely on the standard discovery mechanism of `GlobalOpenTelemetry`, you can set [`disable_instrumentations`](/elastic/docs-builder/docs/3028/reference/apm/agents/java/config-core#config-disable-instrumentations) to `opentelemetry`. ## Add custom metadata to a span If you like the spans created by the Elastic APM Java agent’s auto-instrumentation, but you want to add a custom label, you can use the OpenTelemetry API to get ahold of the current span and call `setAttribute`: ```java Span.current().setAttribute("foo", "bar"); ``` ## Customize span tracing We utilize the `setAttribute()` API not only to [add custom metadata](#otel-set-attribute), but also as a way to customize some special tracing features through corresponding custom attributes listed below. Such attributes are not added to span metadata. For example: ```java Span.current().setAttribute("co.elastic.discardable", false); ``` ### `co.elastic.discardable` By default, spans may be discarded, for example if [`span_min_duration` ([1.16.0])](/elastic/docs-builder/docs/3028/reference/apm/agents/java/config-core#config-span-min-duration) is set and the span does not exceed the configured threshold. Use this attribute to make a span non-discardable by setting it to `false`. making a span non-discardable implicitly makes the entire stack of active spans non-discardable as well. Child spans can still be discarded. | Key | Value type | Default | |--------------------------|------------|---------| | `co.elastic.discardable` | `boolean` | `true` | ## Create a child of the active span This is an example for adding a custom span to the span created by the Java agent’s auto-instrumentation. ```java // if there's an active span, it will implicitly be the parent // in case there's no parent, the custom span will become a Elastic APM transaction Span custom = tracer.spanBuilder("my custom span").startSpan(); // making your child the current one makes the Java agent aware of this span // if the agent creates spans in the context of myTracedMethod() (such as outgoing requests), // they'll be added as a child of your custom span try (Scope scope = custom.makeCurrent()) { myTracedMethod(); } catch (Exception e) { custom.recordException(e); throw e; } finally { custom.end(); } ``` To learn more about the OpenTelemetry API, head over do [their documentation](https://opentelemetry.io/docs/java/manual_instrumentation/). ## Metrics This functionality is in technical preview and may be changed or removed in a future release. Elastic will work to fix any issues, but features in technical preview are not subject to the support SLA of official GA features. The Elastic APM Java Agent supports collecting metrics defined via OpenTelemetry. You can either use the [OpenTelemetry API](#otel-metrics-api) or the [OpenTelemetry SDK](#otel-metrics-sdk) in case you need more customizations. In both cases the Elastic APM Agent will respect the [`disable_metrics`](/elastic/docs-builder/docs/3028/reference/apm/agents/java/config-reporter#config-disable-metrics) and [`metrics_interval`](/elastic/docs-builder/docs/3028/reference/apm/agents/java/config-reporter#config-metrics-interval) settings for OpenTelemetry metrics. You can use the [`custom_metrics_histogram_boundaries`](/elastic/docs-builder/docs/3028/reference/apm/agents/java/config-metrics#config-custom-metrics-histogram-boundaries) setting to customize histogram bucket boundaries. Alternatively you can use OpenTelemetry `Views` to define histogram buckets on a per-metric basis when providing your own `MeterProvider`. Note that `custom_metrics_histogram_boundaries` will only work for API Usages. If you bring your own `MeterProvider` and therefore your own OpenTelemetry SDK, the setting will only work for SDK versions prior to `1.32.0`. ## API Usage You can define metrics and report metric data via `GlobalOpenTelemetry`: ```java import io.opentelemetry.api.GlobalOpenTelemetry; import io.opentelemetry.api.metrics.LongCounter; import io.opentelemetry.api.metrics.Meter; Meter myMeter = GlobalOpenTelemetry.getMeter("my_meter"); LongCounter counter = meter.counterBuilder("my_counter").build(); counter.add(42); ``` We don’t require you to setup an OpenTelemetry `MeterProvider` within `GlobalOpenTelemetry` yourself. The Elastic APM Java Agent will detect if no `MeterProvider` was configured and will provide its own automatically in this case. If you provide your own `MeterProvider` (see [Using a customized MeterProvider](#otel-metrics-sdk)), the agent will use the provided instance. ## Using a customized MeterProvider In some cases using just the [OpenTelemetry API for metrics](#otel-metrics-api) might not be flexible enough. Some example use cases are: - Using OpenTelemetry Views - Exporting metrics to other tools in addition to Elastic APM (e.g. prometheus) For these use cases you can just setup you OpenTelemetry SDK `MeterProvider`. The Elastic APM Agent will take care of installing an additional `MetricExporter` via instrumentation, which will ship the metric data to Elastic APM. This requires using OpenTelemetry version `1.16.0` or newer. To create your own `MeterProvider`, you will need to add the OpenTelemetry Metric SDK as dependency to your project: ```xml io.opentelemetry opentelemetry-sdk-metrics ${version.opentelemetry} ``` ```groovy compile "io.opentelemetry:opentelemetry-sdk-metrics:$openTelemetryVersion" ``` Afterwards you can create and use your own `MeterProvider` as shown below: ```java import io.opentelemetry.sdk.metrics.SdkMeterProvider; import io.opentelemetry.api.metrics.DoubleHistogram; import io.opentelemetry.api.metrics.Meter; import io.opentelemetry.api.metrics.MeterProvider; import io.opentelemetry.exporter.prometheus.PrometheusHttpServer; import io.opentelemetry.sdk.metrics.InstrumentSelector; import io.opentelemetry.sdk.metrics.View; //Elastic APM MetricReader will be registered automatically by the agent SdkMeterProvider meterProvider = SdkMeterProvider.builder() .registerMetricReader(PrometheusHttpServer.create()) .registerView( InstrumentSelector.builder().setName("my_histogram").build(), View.builder().setAggregation(Aggregation.explicitBucketHistogram(List.of(1.0, 5.0))).build() ) .build(); Meter testMeter = meterProvider.get("my_meter"); DoubleHistogram my_histogram = testMeter.histogramBuilder("my_histogram").build(); my_histogram.record(0.5); ``` ## Caveats Not all features of the OpenTelemetry API are supported. ### In process context propagation Entries that are added to the current context, `Context.current().with(...).makeCurrent()` cannot be retrieved via `Context.current().get(...)`. ### Span References Spans can only have a single parent (`SpanBuilder#setParent`) ### Baggage Baggage support has been added in version `1.41.0`. Since `1.43.0` you can automatically attach baggage as span, transaction and error attributes via the [`baggage_to_attach`](/elastic/docs-builder/docs/3028/reference/apm/agents/java/config-core#config-baggage-to-attach) configuration option. ### Events Events are silently dropped, for example `Span.current().addEvent("my event")`. ### Annotations [OpenTelemetry instrumentation annotations](https://opentelemetry.io/docs/instrumentation/java/automatic/annotations/) started supported since `1.45.0`.