OpenTelemetry for Java

Getting Started

If you are looking for an all-in-one, easy-to-install auto-instrumentation javaagent, please visit our sibling project, opentelemetry-java-instrumentation.

If you are looking for examples on how to use the OpenTelemetry APIs to write your own manual instrumentation, or how to set up the OpenTelemetry Java SDK, please visit our quickstart guide. We also have fully-functioning example projects in our examples sub-module, which can be a good way to get your feet wet in a local environment.

If you are looking to get involved with the project, please read our contributing guide. We welcome contributions!

If you are looking for a general overview of the OpenTelemetry project, please visit the official website.

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, and Baggage
  • semantic conventions Generated code for the OpenTelemetry semantic conventions.
  • context api The OpenTelmetry Context implementation.
  • metrics api alpha code for the metrics API.
• 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.
• examples on how to use the APIs, SDK, and standard exporters.

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. 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 contribute

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

Quick Start

Please refer to the quick start guide on how use the OpenTelemetry API.

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.0.1</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.0.1")
  implementation('io.opentelemetry:opentelemetry-api')
}

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.1.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.1.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.

Releases

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

Check out information about the latest release.

This is a current feature status list:

Component	Version
Trace API	v1.0.1
Trace SDK	v1.0.1
Context	v1.0.1
Baggage	v1.0.1
Jaeger Trace Exporter	v1.0.1
Zipkin Trace Exporter	v1.0.1
OTLP Exporter (Spans)	v1.0.1
OTLP Exporter (Metrics)	v1.0.1-alpha
Metrics API	v1.0.1-alpha
Metrics SDK	v1.0.1-alpha
Prometheus Metrics Exporter	v1.0.1-alpha
OpenTracing Bridge	v1.0.1-alpha
OpenCensus Bridge	v1.0.1-alpha

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

Contributing

See CONTRIBUTING.md

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

• Armin Ruech, Dynatrace
• Pavol Loffay, Traceable.ai
• Tyler Benson, DataDog
• Giovanni Liva, Dynatrace
• Christian Neumüller, Dynatrace
• Carlos Alberto, LightStep

Find more about the approver role in community repository.

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

• Bogdan Drutu, Splunk
• John Watson, Splunk
• Anuraag Agrawal, AWS

Find more about the maintainer role in community repository.

Thanks to all the people who have contributed