Instrumentation

Arconia OpenTelemetry supports two instrumentation approaches for Spring Boot applications. You can choose either based on your requirements and the libraries you are using.

The OpenTelemetry Java Agent is not supported by Arconia OpenTelemetry. If you’d like to continue using the Agent, check out the OpenTelemetry Buildpack for adding it to your application out-of-the-box.

Micrometer APIs

The Micrometer project provides APIs for instrumenting Java applications. The Spring portfolio is instrumented with Micrometer, following stable semantic conventions. Arconia OpenTelemetry includes bridges between Micrometer and OpenTelemetry, so all Micrometer-generated telemetry is automatically exported to OpenTelemetry backends.

The following APIs are available:

Observation: the recommended API. A single observation produces both metrics and traces, decoupling the capturing of contextual information from the generation of telemetry data.
MeterRegistry: for metrics-only instrumentation. Metrics are automatically exported to OpenTelemetry via the Micrometer Metrics Registry OTLP or the Micrometer Metrics OpenTelemetry Bridge.
Tracer: for traces-only instrumentation. Traces are automatically exported to OpenTelemetry via the Micrometer Tracing OpenTelemetry Bridge.

Check out the Micrometer and Spring Boot documentation for more information.

By default, Micrometer-based instrumentation uses its own stable naming conventions. Arconia lets you switch to different types like the OpenTelemetry Semantic Conventions or the OpenInference Semantic Conventions instead. Check out the Semantic Conventions documentation for more details.

OpenTelemetry APIs

The OpenTelemetry Java project provides its own APIs for instrumenting applications. The main APIs available for instrumentation are:

Tracer: for creating spans and distributed traces.
Meter: for recording metrics (counters, histograms, gauges).
Logger: for emitting structured log records.
Context: for propagating context across threads and services.

Check out the OpenTelemetry Java API documentation for more information on how to use these APIs directly.

OpenTelemetry Java Instrumentation Libraries

The OpenTelemetry Java Instrumentation project provides libraries that instrument different Java libraries and frameworks. A full list of supported libraries is available in the project documentation.

Arconia OpenTelemetry doesn’t use any of these libraries by default. It is possible to add them to your project, but the recommendation is to prefer the built-in instrumentation in the Spring portfolio based on Micrometer. With Arconia, you can easily adopt the OpenTelemetry Semantic Conventions on top of the Micrometer-based instrumentation, getting the best of both worlds: stable instrumentation with standard naming.

Several instrumentation libraries in the OpenTelemetry Java Instrumentation project are not stable yet (marked as experimental) and follow experimental semantic conventions. Both the libraries and the conventions are subject to breaking changes without notice. Always check the documentation and stability status of the specific instrumentation library before adopting it.