OpenTelemetry Java

opentelemetry-java is the home of the Java implementation of the OpenTelemetry API for recording telemetry, and SDK for managing telemetry recorded by the API.

See opentelemetry.io Java Documentation for:

• An overview of the OpenTelemetry Java ecosystem and key repositories
• Detailed documentation on the components published from this repository
• Review of instrumentation ecosystem, including OpenTelemetry Java agent
• End-to-end working code examples
• And more

Requirements

Unless otherwise noted, all published artifacts support Java 8 or higher. See language version compatibility for complete details.

Android Disclaimer: For compatibility reasons, library desugaring must be enabled.

See contributing for details on building this project locally.

Releases

Releases are published to maven central. We publish minor releases monthly and patch releases as needed.

See releases for a listing of released versions and notes (see also changelog).

Artifacts

The artifacts published by this repository are summarized below in tables, organized in collapsible sections by topic.

As discussed in compatibility, artifact versions must be kept in sync, for which we strongly recommend using one of our BOMs.

API

The OpenTelemetry API for recording telemetry.

Component	Description	Artifact ID	Version	Javadoc
API	OpenTelemetry API, including metrics, traces, baggage, context	opentelemetry-api	1.62.0
API Incubator	API incubator, including pass through propagator, and extended tracer, and Event API	opentelemetry-api-incubator	1.62.0-alpha
Context API	OpenTelemetry context API	opentelemetry-context	1.62.0
Common	Common utility methods used across API components	opentelemetry-common	1.62.0

API Extensions

Extensions to the OpenTelemetry API.

Component	Description	Artifact ID	Version	Javadoc
Kotlin Extension	Context extension for coroutines	opentelemetry-extension-kotlin	1.62.0
Trace Propagators Extension	Trace propagators, including B3, Jaeger, OT Trace	opentelemetry-extension-trace-propagators	1.62.0

SDK

The OpenTelemetry SDK for managing telemetry producing by the API.

Component	Description	Artifact ID	Version	Javadoc
SDK	OpenTelemetry SDK, including metrics, traces, and logs	opentelemetry-sdk	1.62.0
Metrics SDK	OpenTelemetry metrics SDK	opentelemetry-sdk-metrics	1.62.0
Trace SDK	OpenTelemetry trace SDK	opentelemetry-sdk-trace	1.62.0
Log SDK	OpenTelemetry log SDK	opentelemetry-sdk-logs	1.62.0
Profiles SDK	OpenTelemetry profiles SDK	opentelemetry-sdk-profiles	1.62.0
SDK Common	Shared SDK components	opentelemetry-sdk-common	1.62.0
SDK Testing	Components for testing OpenTelemetry instrumentation	opentelemetry-sdk-testing	1.62.0

SDK Exporters

SDK exporters for shipping traces, metrics, and logs out of process.

Component	Description	Artifact ID	Version	Javadoc
OTLP Exporters	OTLP gRPC & HTTP exporters, including traces, metrics, and logs	opentelemetry-exporter-otlp	1.62.0
OTLP Profiles Exporter	OTLP profiles exporter	opentelemetry-exporter-otlp-profiles	1.62.0-alpha
OTLP Logging Exporters	Logging exporters in OTLP JSON encoding, including traces, metrics, and logs	opentelemetry-exporter-logging-otlp	1.62.0
OTLP Common	Shared OTLP components (internal)	opentelemetry-exporter-otlp-common	1.62.0
Logging Exporter	Logging exporters, including metrics, traces, and logs	opentelemetry-exporter-logging	1.62.0
Zipkin Exporter	Zipkin trace exporter	opentelemetry-exporter-zipkin	1.62.0
Prometheus Exporter	Prometheus metric exporter	opentelemetry-exporter-prometheus	1.62.0-alpha
Exporter Common	Shared exporter components (internal)	opentelemetry-exporter-common	1.62.0
OkHttp Sender	OkHttp implementation of HttpSender (internal)	opentelemetry-exporter-sender-okhttp	1.62.0
JDK Sender	Java 11+ native HttpClient implementation of HttpSender (internal)	opentelemetry-exporter-sender-jdk	1.62.0
gRPC ManagedChannel Sender	gRPC ManagedChannel implementation of GrpcSender (internal)	opentelemetry-exporter-sender-grpc-managed-channel	1.62.0

SDK Extensions

Extensions to the OpenTelemetry SDK.

Component	Description	Artifact ID	Version	Javadoc
SDK Autoconfigure	Autoconfigure OpenTelemetry SDK from env vars, system properties, and SPI	opentelemetry-sdk-extension-autoconfigure	1.62.0
SDK Autoconfigure SPI	Service Provider Interface (SPI) definitions for autoconfigure	opentelemetry-sdk-extension-autoconfigure-spi	1.62.0
SDK Declarative Config	Declarative config implementation for YAML-based SDK configuration	opentelemetry-sdk-extension-declarative-config	1.62.0-alpha
SDK Jaeger Remote Sampler Extension	Sampler which obtains sampling configuration from remote Jaeger server	opentelemetry-sdk-extension-jaeger-remote-sampler	1.62.0
SDK Incubator	SDK incubator, including YAML based view configuration, LeakDetectingSpanProcessor	opentelemetry-sdk-extension-incubator	1.62.0-alpha

Shims

Shims for bridging data from one observability library to another.

Component	Description	Artifact ID	Version	Javadoc
OpenCensus Shim	Bridge opencensus metrics into the OpenTelemetry metrics SDK	opentelemetry-opencensus-shim	1.62.0-alpha
OpenTracing Shim	Bridge opentracing spans into the OpenTelemetry trace API	opentelemetry-opentracing-shim	1.62.0

Verifying Artifacts

All artifacts published to Maven Central are signed with GPG key 17A27CE7A60FF5F0 (fingerprint: 3F05 DDA9 F317 301E 9271 36D4 17A2 7CE7 A60F F5F0).

Dependencies

To take a dependency, include a BOM and specify the dependency as follows, replacing {{artifact-id}} with the value from the "Artifact ID" column from artifacts:

  implementation('io.opentelemetry:{{artifact-id}}')

<dependency>
  <groupId>io.opentelemetry</groupId>
  <artifactId>{{artifact-id}}</artifactId>
</dependency>

Snapshots

Snapshots of the main branch are available as follows:

repositories {
    maven { url 'https://central.sonatype.com/repository/maven-snapshots/' }
}

dependencies {
  implementation platform("io.opentelemetry:opentelemetry-bom:1.63.0-SNAPSHOT")
  implementation('io.opentelemetry:opentelemetry-api')
}

  <project>
    <repositories>
      <repository>
        <id>sonatype-snapshot-repository</id>
        <url>https://central.sonatype.com/repository/maven-snapshots/</url>
      </repository>
    </repositories>
    <dependencyManagement>
      <dependencies>
        <dependency>
          <groupId>io.opentelemetry</groupId>
          <artifactId>opentelemetry-bom</artifactId>
          <version>1.63.0-SNAPSHOT</version>
          <type>pom</type>
          <scope>import</scope>
        </dependency>
      </dependencies>
    </dependencyManagement>
    <dependencies>
      <dependency>
        <groupId>io.opentelemetry</groupId>
        <artifactId>opentelemetry-api</artifactId>
      </dependency>
    </dependencies>
  </project>

Compatibility

Artifacts from this repository follow semantic versioning.

Stable artifacts (i.e. artifacts without -alpha version suffix) come with strong backwards compatibility guarantees for public APIs.

Artifacts may depend on other artifacts from this repository, and may depend on internal APIs (i.e. non-public APIs) which are subject to change across minor versions. Therefore, it's critical to keep artifact versions in sync in order to avoid possible runtime exceptions. We strongly recommend using one of our BOMs to assist in keeping artifacts in sync.

See the VERSIONING.md for complete details on compatibility policy.

Contacting us

We hold regular meetings. See details at community page.

The meeting is open for all to join. We invite everyone to join our meeting, regardless of your experience level. Whether you're a seasoned OpenTelemetry developer, just starting your journey, or simply curious about the work we do, you're more than welcome to participate!

To report a bug, or request a new feature, please open an issue.

We use GitHub Discussions for support or general questions. Feel free to drop us a line.

We are also present in the #otel-java channel in the CNCF slack. Please join us for more informal discussions.

Contributing

See CONTRIBUTING.md for:

• Details on building locally
• Project scope
• Keys to successful PRs
• Guide to using gradle composite builds

Maintainers

• Jack Berg, Grafana Labs
• John Watson, Sublime Security

For more information about the maintainer role, see the community repository.

Approvers

• Gregor Zeitlinger, Grafana Labs
• Jason Plumb, Splunk
• Lauri Tulmin, Splunk
• Trask Stalnaker, Microsoft

For more information about the approver role, see the community repository.

Triagers

None.

For more information about the triager role, see the community repository.

Emeritus

• Bogdan Drutu, Maintainer
• Carlos Alberto, Maintainer
• Josh Suereth, Approver
• Mateusz Rzeszutek, Approver

For more information about the emeritus role, see the community repository.

Help wanted

We are currently resource constrained and are actively seeking new contributors interested in working towards approver / maintainer roles. In addition to the documentation for approver / maintainer roles and the contributing guide, here are some additional notes on engaging:

• Pull request reviews are equally or more helpful than code contributions. Comments and approvals are valuable with or without a formal project role. They're also a great forcing function to explore a fairly complex codebase.
• Attending the Java: SDK + Automatic Instrumentation Special Interest Group (SIG) is a great way to get to know community members and learn about project priorities.
• Issues labeled help wanted are project priorities. Code contributions (or pull request reviews when a PR is linked) for these issues are particularly important.
• Triaging / responding to new issues and discussions is a great way to engage with the project.

Thanks to all of our contributors!