Intro to OpenTelemetry Java

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.

Overview

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.

Navigating the docs

The OpenTelemetry Java documentation is organized as follows:

• Getting Started by Example: A quick example to get off the ground running with OpenTelemetry Java, demonstrating integration of the OpenTelemetry Java agent into a simple web application.
• Instrumentation ecosystem: A guide to the OpenTelemetry Java instrumentation ecosystem. This is a key resource for application authors looking to integrate OpenTelemetry Java into applications. Learn about the different categories of instrumentation, and decide which is right for you.
• Record Telemetry with API: A technical reference for the OpenTelemetry API, exploring all key aspects of the API with working code examples. Most users will use this page like an encyclopedia, consulting the index of sections as needed, rather than reading front to back.
• Manage Telemetry with SDK A technical reference for the OpenTelemetry SDK, exploring all SDK plugin extension points and the programmatic configuration API with working code examples. Most users will use this page like an encyclopedia, consulting the index of sections as needed, rather than reading front to back.
• Configure the SDK: A technical reference for configuring the SDK, focussing on zero-code autoconfiguration. Includes a reference of all supported environment variables and system properties for configuring the SDK. Explores all programmatic customization points with working code examples. Most users will use this page like an encyclopedia, consulting the index of sections as needed, rather than reading front to back.
• Learn More: Supplementary resources, including end-to-end examples, Javadoc, component registry, and a performance reference.

Repositories

OpenTelemetry Java source code is organized into several repositories:

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.
• Although semantic-conventions-java is a dependency of opentelemetry-java-instrumentation, it is an independent artifact with an independent release schedule.

Dependencies and BOMs

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.

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.

• Gradle
• Maven

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>