OpenTelemetry Java is the set of OpenTelemetry observability tools for the Java ecosystem. At a high level, it consists of the API, the SDK, and instrumentation.
This page introduces the ecosystem, with a conceptual overview, a guide to navigating the docs, a list of repositories with key details about releases and artifacts.
The API is a set of classes and interfaces for recording telemetry across key observability signals. It supports multiple implementations, with a low-overhead minimalist Noop (i.e. pronounced “no-op”) and SDK reference implementation provided out of the box. It is designed to be taken as a direct dependency by libraries, frameworks, and application owners looking to add instrumentation. It comes with strong backwards compatibility guarantees, zero transitive dependencies, and supports Java 8+.
The SDK is the built-in reference implementation of the API, processing and exporting telemetry produced by instrumentation API calls. Configuring the SDK to process and export appropriately is an essential step to integrating OpenTelemetry into an application. The SDK has autoconfiguration and programmatic configuration options.
Instrumentation records telemetry using the API. There are a variety of categories of instrumentation, including: zero-code Java agent, zero-code Spring Boot starter, library, native, manual, and shims.
For a language-agnostic overview, see OpenTelemetry concepts.
The OpenTelemetry Java documentation is organized as follows:
OpenTelemetry Java source code is organized into several repositories:
Repository | Description | Group ID | Current Version | Release cadence |
---|---|---|---|---|
opentelemetry-java | Core API and SDK components | io.opentelemetry | 1.44.1 | Friday after first Monday of the month |
opentelemetry-java-instrumentation | Instrumentation maintained by OpenTelemetry, including OpenTelemetry Java agent | io.opentelemetry.instrumentation | 2.10.0 | Wednesday after second Monday of the month |
opentelemetry-java-contrib | Community maintained components that don’t fit the express scope of other repositories | io.opentelemetry.contrib | 1.38.0 | Friday after second Monday of the month |
semantic-conventions-java | Generated code for semantic conventions | io.opentelemetry.semconv | 1.28.0 | Following releases of semantic-conventions |
opentelemetry-proto-java | Generated bindings for OTLP | io.opentelemetry.proto | 1.3.2-alpha | Following releases of opentelemetry-proto |
opentelemetry-java-examples | End-to-end code examples demonstrating a variety of patterns using the API, SDK, and instrumentation | n/a | n/a | n/a |
opentelemetry-java
, opentelemetry-java-instrumentation
, and
opentelemetry-java-contrib
each publish large catalogs of artifacts. Please
consult repositories for details, or see the “Managed Dependencies” column in
the Bill of Materials table to see a full list of
managed dependencies.
As a general rule, artifacts published from the same repository have the same
version. The exception to this is opentelemetry-java-contrib
, which can be
thought of as a group of independent projects that are co-located in the same
repository to take advantage of shared tooling. For now, the artifacts of
opentelemetry-java-contrib
are aligned but this is a coincidence and will
change in the future.
The repositories have a release cadence which mirrors their high level dependency structure:
opentelemetry-java
is the core and releases first each month.opentelemetry-java-instrumentation
depends on opentelemetry-java
and is
next to publish.opentelemetry-java-contrib
depends on opentelemetry-java-instrumentation
and opentelemetry-java
and is last to publish.semantic-conventions-java
is a dependency of
opentelemetry-java-instrumentation
, it is an independent artifact with an
independent release schedule.A bill of materials, or BOM for short, is an artifact that helps keep the versions of related dependencies aligned. OpenTelemetry Java publishes several BOMs catering to different use cases, listed below in order of increasing scope. We highly recommend using a BOM.
Click the link in the “Managed Dependencies” column to see a list of the artifacts managed by the BOM.
Description | Repository | Group ID | Artifact ID | Current Version | Managed Dependencies |
---|---|---|---|---|---|
Stable core API and SDK artifacts | opentelemetry-java | io.opentelemetry | opentelemetry-bom | 1.44.1 | latest pom.xml |
Experimental core API and SDK artifacts, including all of opentelemetry-bom | opentelemetry-java | io.opentelemetry | opentelemetry-bom-alpha | 1.44.1-alpha | latest pom.xml |
Stable instrumentation artifacts, including all of opentelemetry-bom | opentelemetry-java-instrumentation | io.opentelemetry.instrumentation | opentelemetry-instrumentation-bom | 2.10.0 | latest pom.xml |
Experimental instrumentation artifacts, including all of opentelemetry-instrumentation-bom | opentelemetry-java-instrumentation | io.opentelemetry.instrumentation | opentelemetry-instrumentation-bom-alpha | 2.10.0-alpha | latest pom.xml |
The following code snippet demonstrates adding a BOM dependency,
with{{bomGroupId}}
, {{bomArtifactId}}
, and {{bomVersion}}
referring to the
“Group ID”, “Artifact ID”, and “Current Version” table columns, respectively.
dependencies {
implementation(platform("{{bomGroupId}}:{{bomArtifactId}}:{{bomVersion}}"))
// Add a dependency on an artifact whose version is managed by the bom
implementation("io.opentelemetry:opentelemetry-api")
}
<project>
<dependencyManagement>
<dependencies>
<dependency>
<groupId>{{bomGroupId}}</groupId>
<artifactId>{{bomArtifactId}}</artifactId>
<version>{{bomVersion}}</version>
<type>pom</type>
<scope>import</scope>
</dependency>
</dependencies>
</dependencyManagement>
<!-- Add a dependency on an artifact whose version is managed by the bom -->
<dependencies>
<dependency>
<groupId>io.opentelemetry</groupId>
<artifactId>opentelemetry-api</artifactId>
</dependency>
</dependencies>
</project>
¿Fue útil esta página?
Thank you. Your feedback is appreciated!
Please let us know how we can improve this page. Your feedback is appreciated!