OpenTelemetry for Java

Getting Started

If you are looking for an all-in-one, easy-to-install auto-instrumentation javaagent, see opentelemetry-java-instrumentation.

If you are looking for examples on how to use the OpenTelemetry API to write your own manual instrumentation, or how to set up the OpenTelemetry Java SDK, see Manual instrumentation. Fully-functional examples are available in opentelemetry-java-docs.

For a general overview of OpenTelemetry, visit opentelemetry.io.

Would you like to get involved with the project? Read our contributing guide. We welcome contributions!

Contacting us

We hold regular meetings. See details at community page.

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.

Overview

OpenTelemetry is the merging of OpenCensus and OpenTracing into a single project.

This project contains the following top level components:

• OpenTelemetry API:
  • stable apis including Tracer, Span, SpanContext, Meter, and Baggage
  • semantic conventions Generated code for the OpenTelemetry semantic conventions.
  • context api The OpenTelemetry Context implementation.
• extensions define additional API extensions, which are not part of the core API.
• sdk defines the implementation of the OpenTelemetry API.
• sdk-extensions defines additional SDK extensions, which are not part of the core SDK.
• OpenTracing shim defines a bridge layer from OpenTracing to the OpenTelemetry API.
• OpenCensus shim defines a bridge layer from OpenCensus to the OpenTelemetry API.
• Micrometer shim defines a bridge layer from Micrometer to the OpenTelemetry API.

This project publishes a lot of artifacts, listed in releases. opentelemetry-bom (BOM = Bill of Materials) is provided to assist with synchronizing versions of dependencies. opentelemetry-bom-alpha provides the same function for unstable artifacts. See published releases for instructions on using the BOMs.

We would love to hear from the larger community: please provide feedback proactively.

Requirements

Unless otherwise noted, all published artifacts support Java 8 or higher.

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

See CONTRIBUTING.md for additional instructions for building this project for development.

Note about extensions

Both API and SDK extensions consist of various additional components which are excluded from the core artifacts to keep them from growing too large.

We still aim to provide the same level of quality and guarantee for them as for the core components. Please don't hesitate to use them if you find them useful.

Project setup and contributing

Please refer to the contribution guide on how to set up for development and contribute!

Published Releases

Published releases are available on maven central. We strongly recommend using our published BOM to keep all dependency versions in sync.

Maven

<project>
  <dependencyManagement>
    <dependencies>
      <dependency>
        <groupId>io.opentelemetry</groupId>
        <artifactId>opentelemetry-bom</artifactId>
        <version>1.15.0</version>
        <type>pom</type>
        <scope>import</scope>
      </dependency>
    </dependencies>
  </dependencyManagement>
  <dependencies>
    <dependency>
      <groupId>io.opentelemetry</groupId>
      <artifactId>opentelemetry-api</artifactId>
    </dependency>
  </dependencies>
</project>

Gradle

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

Note that if you want to use any artifacts that have not fully stabilized yet (such as the semantic conventions constants or the SDK Autoconfigure Extension), then you will need to add an entry for the Alpha BOM as well, e.g.

dependencies {
  implementation platform("io.opentelemetry:opentelemetry-bom:1.15.0")
  implementation platform('io.opentelemetry:opentelemetry-bom-alpha:1.15.0-alpha')

  implementation('io.opentelemetry:opentelemetry-api')
  implementation('io.opentelemetry:opentelemetry-semconv')
  implementation('io.opentelemetry:opentelemetry-sdk-extension-autoconfigure')
}

Snapshots

Snapshots based out the main branch are available for opentelemetry-api, opentelemetry-sdk and the rest of the artifacts. We strongly recommend using our published BOM to keep all dependency versions in sync.

Maven

<project>
  <repositories>
    <repository>
      <id>oss.sonatype.org-snapshot</id>
      <url>https://oss.sonatype.org/content/repositories/snapshots</url>
    </repository>
  </repositories>
  <dependencyManagement>
    <dependencies>
      <dependency>
        <groupId>io.opentelemetry</groupId>
        <artifactId>opentelemetry-bom</artifactId>
        <version>1.16.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>

Gradle

repositories {
    maven { url 'https://oss.sonatype.org/content/repositories/snapshots' }
}

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

Libraries will usually only need opentelemetry-api, while applications will want to use the opentelemetry-sdk module which contains our standard implementation of the APIs.

Gradle composite builds

For opentelemetry-java developers that need to test the latest source code with another project, composite builds can be used as an alternative to publishToMavenLocal. This requires some setup which is explained here.

Releases

See the VERSIONING.md document for our policies for releases and compatibility guarantees.

Check out information about the latest release.

See the project milestones for details on upcoming releases. The dates and features described in issues and milestones are estimates, and subject to change.

The following tables describe the artifacts published by this project. To take a dependency, follow the instructions in Published Released to include the BOM, and specify the dependency as follows, replacing {{artifact-id}} with the value from the "Artifact ID" column:

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

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

Bill of Material

Component	Description	Artifact ID	Version
Bill of Materials (BOM)	Bill of materials for stable artifacts	opentelemetry-bom	1.15.0
Alpha Bill of Materials (BOM)	Bill of materials for alpha artifacts	opentelemetry-bom-alpha	1.15.0-alpha

API

Component	Description	Artifact ID	Version
API	OpenTelemetry API, including metrics, traces, baggage, context	opentelemetry-api	1.15.0
Context API	OpenTelemetry context API	opentelemetry-context	1.15.0
Semantic Conventions	Generated code for OpenTelemetry semantic conventions	opentelemetry-semconv	1.15.0-alpha

API Extensions

Component	Description	Artifact ID	Version
Annotations Extension	Instrumentation annotations, used in conjunction with OpenTelemetry java agent	opentelemetry-extension-annotations	1.15.0
AWS Extension	AWS Xray propagator	opentelemetry-extension-aws	1.15.0
Kotlin Extension	Context extension for coroutines	opentelemetry-extension-kotlin	1.15.0
Trace Propagators Extension	Trace propagators, including B3, Jaeger, OT Trace	opentelemetry-extension-trace-propagators	1.15.0
Incubator Extension	API incubator, including pass through propagator, and extended tracer	opentelemetry-extension-incubator	1.15.0-alpha
Noop API Extension	A noop OpenTelemetry implementation which ignores context	opentelemetry-extension-noop-api	1.15.0-alpha

SDK

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

SDK Exporters

Component	Description	Artifact ID	Version
OTLP Exporters	OTLP gRPC & HTTP exporters, including metrics and trace	opentelemetry-exporter-otlp	1.15.0
OTLP Log Exporters	OTLP gRPC & HTTP log exporters	opentelemetry-exporter-otlp-logs	1.15.0-alpha
OTLP Common	Shared OTLP components (internal)	opentelemetry-exporter-otlp-common	1.15.0
Jaeger gRPC Exporter	Jaeger gRPC trace exporter	opentelemetry-exporter-jaeger	1.15.0
Jaeger Thrift Exporter	Jaeger thrift trace exporter	opentelemetry-exporter-jaeger-thift	1.15.0
Jaeger Proto	Jaeger gRPC protobuf definitions (deprecated)	opentelemetry-exporter-jaeger-proto	1.15.0
Logging Exporter	Logging exporters, includings metrics, traces, and logs	opentelemetry-exporter-logging	1.15.0
OTLP Logging Exporter	Logging exporters in OTLP protobuf JSON format, including metrics, traces, and logs	opentelemetry-exporter-logging-otlp	1.15.0
Zipkin Exporter	Zipkin trace exporter	opentelemetry-exporter-zipkin	1.15.0
Prometheus Exporter	Prometheus metric exporter	opentelemetry-exporter-prometheus	1.15.0-alpha

SDK Extensions

Component	Description	Artifact ID	Version
SDK Autoconfigure Extension	Autoconfigure OpenTelemetry SDK from env vars, system properties, and SPI	opentelemetry-sdk-extension-autoconfigure	1.15.0-alpha
SDK Autoconfigure SPI	Service Provider Interface (SPI) definitions for autoconfigure	opentelemetry-sdk-extension-autoconfigure-spi	1.15.0
SDK Resources Extension	Resource providers, including container, host, os, and process	opentelemetry-sdk-extension-resources	1.15.0
SDK AWS Extension	AWS resource providers, including beanstalk, ec2, ecs, eks, and lambda	opentelemetry-sdk-extension-aws	1.15.0
SDK Jaeger Remote Sampler Extension	Sampler which obtains sampling configuration from remote Jaeger server	opentelemetry-sdk-extension-jaeger-remote-sampler	1.15.0
SDK JFR Events Extension	SpanProcessor which records spans as JFR events	opentelemetry-sdk-extension-jfr-events	1.15.0-alpha
SDK Metric Incubator Extension	Metrics incubator, including YAML based view configuration	opentelemetry-sdk-extension-metric-incubator	1.15.0-alpha
SDK Tracing Incubator Extension	Trace incubator, including leak detecting SpanProcessor	opentelemetry-sdk-extension-tracing-incubator	1.15.0-alpha
SDK zPages Extension	SpanProcessor which exposes spans with zPages	opentelemetry-sdk-extension-zpages	1.15.0-alpha

Shims

Component	Description	Artifact ID	Version
Micrometer Shim	Bridge micrometer metrics into the OpenTelemetry metrics API	opentelemetry-micrometer1-shim	1.15.0-alpha
OpenCensus Shim	Bridge opencensus metrics into the OpenTelemetry metrics SDK	opentelemetry-opencensus-shim	1.15.0-alpha
OpenTracing Shim	Bridge opentracing spans into the OpenTelemetry trace API	opentelemetry-opentracing-shim	1.15.0-alpha

Contributing

See CONTRIBUTING.md

Approvers (@open-telemetry/java-approvers):

• Christian Neumüller, Dynatrace
• Jakub Wach, Splunk
• Josh Suereth, Google

Find more about the approver role in community repository.

Maintainers (@open-telemetry/java-maintainers):

• Anuraag Agrawal, AWS
• Jack Berg, New Relic
• John Watson, Splunk

Maintainers Emeritus:

• Bogdan Drutu, Splunk
• Carlos Alberto, LightStep

Find more about the maintainer role in community repository.

Thanks to all the people who have contributed

Made with contrib.rocks.