Instrumentation records telemetry using the API. The SDK is the built-in reference implementation of the API, and is configured to process and export the telemetry produced by instrumentation API calls. This page discusses the OpenTelemetry ecosystem in OpenTelemetry Java, including resources for end users and cross-cutting instrumentation topics:
There are several categories of instrumentation:
[1]: Zero-code instrumentation is installed automatically based on detected libraries / frameworks.
The opentelemetry-java-instrumentation project contains the source code for Java agent, Spring Boot starter, and Library instrumentation.
The Java agent is a form of zero-code automatic instrumentation that dynamically manipulates application bytecode.
For a list of libraries instrumented by the Java agent, see the “Auto-instrumented versions” column on supported libraries.
See Java agent for more details.
The Spring Boot starter is a form of zero-code automatic instrumentation that leverages spring autoconfigure to install library instrumentation.
See Spring Boot starter for details.
Library instrumentation wraps or uses extension points to instrument a library, requiring users to install and/or adapt library usage.
For a list of instrumentation libraries, see the “Standalone Library Instrumentation” column on supported libraries.
Native instrumentation is built directly into libraries or frameworks. OpenTelemetry encourages library authors to add native instrumentation using the API. In the long term, we hope the native instrumentation becomes the norm, and view the instrumentation maintained by OpenTelemetry in opentelemetry-java-instrumentation as a temporary means of filling the gap.
Manual instrumentation is written by application authors, and typically specific to the application domain.
A shim is instrumentation that bridges data from one observability library to another, typically from some library into OpenTelemetry.
Shims maintained in the OpenTelemetry Java ecosystem:
Description | Documentation | Signal(s) | Artifact |
---|---|---|---|
Bridge OpenTracing into OpenTelemetry | README | Traces | io.opentelemetry:opentelemetry-opentracing-shim:1.44.1 |
Bridge Opencensus into OpenTelemetry | README | Traces, Metrics | io.opentelemetry:opentelemetry-opencensus-shim:1.44.1-alpha |
Bridge Micrometer into OpenTelemetry | README | Metrics | io.opentelemetry.instrumentation:opentelemetry-micrometer-1.5:2.10.0-alpha |
Bridge JMX into OpenTelemetry | README | Metrics | io.opentelemetry.instrumentation:opentelemetry-jmx-metrics:2.10.0-alpha |
Bridge OpenTelemetry into Prometheus Java client | README | Metrics | io.opentelemetry.contrib:opentelemetry-prometheus-client-bridge:1.41.0-alpha |
Bridge OpenTelemetry into Micrometer | README | Metrics | io.opentelemetry.contrib:opentelemetry-micrometer-meter-provider:1.41.0-alpha |
Bridge Log4j into OpenTelemetry | README | Logs | io.opentelemetry.instrumentation:opentelemetry-log4j-appender-2.17:2.10.0-alpha |
Bridge Logback into OpenTelemetry | README | Logs | io.opentelemetry.instrumentation:opentelemetry-logback-appender-1.0:2.10.0-alpha |
Bridge OpenTelemetry context into Log4j | README | Context | io.opentelemetry.instrumentation:opentelemetry-log4j-context-data-2.17-autoconfigure:2.10.0-alpha |
Bridge OpenTelemetry context into Logback | README | Context | io.opentelemetry.instrumentation:opentelemetry-logback-mdc-1.0:2.10.0-alpha |
The OpenTelemetry APIs are designed to be complementary, with the whole greater than the sum of the parts. Each signal has its own strengths, and collectively stitch together a compelling observability story.
Importantly, the data from the various signals are linked together through trace context:
For this correlation to work, trace context must be propagated throughout an application (across function calls and threads), and across application boundaries. The context API facilitates this. Instrumentation needs to be written in a manner which is context aware:
The semantic conventions define how to produce telemetry for standard operations. Among other things, the semantic conventions specify span names, span kinds, metric instruments, metric units, metric types, and attribute key, value, and requirement levels.
When writing instrumentation, consult the semantic conventions and conform to any which are applicable to the domain.
OpenTelemetry Java publishes artifacts to assist in conforming to the semantic conventions, including generated constants for attribute keys and values.
TODO: discuss instrumentation API and how it helps conform to semantic conventions
While the LoggerProvider / Logger
APIs are structurally similar to the equivalent trace
and metric APIs, they serve a different use case. As of
now, LoggerProvider
/ Logger
and associated classes represent the
Log Bridge API, which exists to write log
appenders to bridge logs recorded through other log APIs / frameworks into
OpenTelemetry. They are not intended for end user use as a replacement for Log4j
/ SLF4J / Logback / etc.
There are two typical workflows for consuming log instrumentation in OpenTelemetry catering to different application requirements:
In the direct to collector workflow, logs are emitted directly from an application to a collector using a network protocol (e.g. OTLP). This workflow is simple to set up as it doesn’t require any additional log forwarding components, and allows an application to easily emit structured logs that conform to the log data model. However, the overhead required for applications to queue and export logs to a network location may not be suitable for all applications.
To use this workflow:
[1]: Log appenders are a type of shim which bridges logs from a log framework into the OpenTelemetry log SDK. See “Bridge Log4j into OpenTelemetry”, “Bridge Logback into OpenTelemetry” entries. See Log Appender example for demonstration of a variety of scenarios.
In the file or stdout workflow, logs are written to files or standout output. Another component (e.g. FluentBit) is responsible for reading / tailing the logs, parsing them to more structured format, and forwarding them a target, such as the collector. This workflow may be preferable in situations where application requirements do not permit additional overhead from direct to collector. However, it requires that all log fields required down stream are encoded into the logs, and that the component reading the logs parse the data into the log data model. The installation and configuration of log forwarding components is outside the scope of this document.
Log correlation with traces is available by installing a shim to bridge OpenTelemetry context into the log framework. See “Bridge OpenTelemetry context into Log4j”, “Bridge OpenTelemetry context into Logback” entries.
Cette page est-elle utile?
Thank you. Your feedback is appreciated!
Please let us know how we can improve this page. Your feedback is appreciated!