opentelemetry-java

OpenTelemetry Java SDK

1,958

807

1,958

140

View on GitHub

Top Related Projects

opentracing-java

1,682

OpenTracing API for Java. 🛑 This library is DEPRECATED! https://github.com/opentracing/specification/issues/163

zipkin

16,917

Zipkin is a distributed tracing system

client_java

2,169

Prometheus instrumentation library for JVM applications

Quick Overview

OpenTelemetry Java is an open-source observability framework for cloud-native software. It provides a collection of tools, APIs, and SDKs to instrument, generate, collect, and export telemetry data (metrics, logs, and traces) for analysis in order to understand your software's behavior and performance.

Pros

Vendor-neutral and open-source, allowing for flexibility and avoiding vendor lock-in
Comprehensive support for various Java frameworks and libraries
Provides automatic instrumentation for many popular Java technologies
Highly extensible and customizable to fit specific application needs

Cons

Learning curve can be steep for newcomers to observability concepts
Documentation, while improving, can sometimes be fragmented or outdated
Performance overhead, though minimal, may be a concern for extremely high-throughput systems
Still evolving, which may lead to breaking changes between versions

Code Examples

Creating a tracer and recording a span:

Tracer tracer = GlobalOpenTelemetry.getTracer("instrumentation-library-name", "semver:1.0.0");
Span span = tracer.spanBuilder("my span").startSpan();
try (Scope scope = span.makeCurrent()) {
    // Your code here
} finally {
    span.end();
}

Adding attributes to a span:

Span span = tracer.spanBuilder("my span").startSpan();
span.setAttribute("http.method", "GET");
span.setAttribute("http.url", "https://example.com");

Creating and recording a metric:

Meter meter = GlobalOpenTelemetry.getMeter("instrumentation-library-name");
LongCounter counter = meter
    .counterBuilder("processed_jobs")
    .setDescription("Number of processed jobs")
    .setUnit("1")
    .build();

counter.add(1);

Getting Started

To get started with OpenTelemetry Java, add the following dependencies to your project:

dependencies {
    implementation 'io.opentelemetry:opentelemetry-api:1.24.0'
    implementation 'io.opentelemetry:opentelemetry-sdk:1.24.0'
    implementation 'io.opentelemetry:opentelemetry-exporter-otlp:1.24.0'
}

Then, initialize the OpenTelemetry SDK in your application:

SdkTracerProvider sdkTracerProvider = SdkTracerProvider.builder()
    .addSpanProcessor(BatchSpanProcessor.builder(OtlpGrpcSpanExporter.builder().build()).build())
    .build();

OpenTelemetrySdk openTelemetry = OpenTelemetrySdk.builder()
    .setTracerProvider(sdkTracerProvider)
    .buildAndRegisterGlobal();

This sets up a basic OpenTelemetry configuration with OTLP exporter. You can now use the global tracer to create spans and record telemetry data in your application.

Competitor Comparisons

opentracing-java

1,682

OpenTracing API for Java. 🛑 This library is DEPRECATED! https://github.com/opentracing/specification/issues/163

Pros of OpenTracing

Simpler API with a focus on distributed tracing
Easier to get started for developers new to observability
More mature and stable, with a longer history of production use

Cons of OpenTracing

Limited scope compared to OpenTelemetry's comprehensive observability approach
Smaller ecosystem and fewer integrations
No longer actively developed, as efforts have shifted to OpenTelemetry

Code Comparison

OpenTracing:

Tracer tracer = GlobalTracer.get();
Span span = tracer.buildSpan("operation").start();
span.setTag("key", "value");
span.finish();

OpenTelemetry:

Tracer tracer = GlobalOpenTelemetry.getTracer("instrumentation-library-name");
Span span = tracer.spanBuilder("operation").startSpan();
span.setAttribute("key", "value");
span.end();

The code snippets show similar functionality, but OpenTelemetry uses slightly different method names and a more structured approach to creating tracers. OpenTelemetry also provides additional features like metrics and logs, which are not shown in this basic example.

OpenTracing is simpler and more focused on tracing, while OpenTelemetry offers a more comprehensive observability solution with a slightly steeper learning curve. However, OpenTelemetry is the future of observability, combining the best aspects of OpenTracing and OpenCensus.

zipkin

16,917

Zipkin is a distributed tracing system

Pros of Zipkin

Mature project with a longer history and established user base
Simpler architecture, potentially easier to set up and maintain
Built-in web UI for visualizing and analyzing traces

Cons of Zipkin

Less flexible and extensible compared to OpenTelemetry
Limited support for non-Java languages and frameworks
Smaller ecosystem and fewer integrations with other observability tools

Code Comparison

Zipkin instrumentation example:

Span span = tracer.newTrace().name("encode").start();
try {
  doSomethingExpensive();
} finally {
  span.finish();
}

OpenTelemetry instrumentation example:

Span span = tracer.spanBuilder("encode").startSpan();
try (Scope scope = span.makeCurrent()) {
  doSomethingExpensive();
} finally {
  span.end();
}

Both examples show how to create and manage spans, but OpenTelemetry uses a more explicit scope management approach. Zipkin's API is slightly simpler, while OpenTelemetry offers more control over the span's lifecycle and context propagation.

OpenTelemetry provides a more comprehensive observability solution with support for metrics and logs in addition to traces, making it a more versatile choice for modern distributed systems. However, Zipkin may be preferred for simpler Java-centric projects or those already invested in the Zipkin ecosystem.

client_java

2,169

Prometheus instrumentation library for JVM applications

Pros of client_java

Mature and well-established project with a long history in the Prometheus ecosystem
Simpler implementation for basic metric collection and export
Tighter integration with Prometheus-specific features and best practices

Cons of client_java

Limited to Prometheus-specific metrics and data model
Less flexibility for supporting multiple observability backends
Narrower scope compared to OpenTelemetry's comprehensive approach

Code Comparison

client_java:

Counter requests = Counter.build()
    .name("requests_total")
    .help("Total requests.")
    .register();

requests.inc();

opentelemetry-java:

Meter meter = GlobalMeterProvider.getMeter("instrumentation-library-name");
LongCounter counter = meter
    .counterBuilder("requests_total")
    .setDescription("Total requests.")
    .build();

counter.add(1);

Summary

While client_java offers a straightforward implementation for Prometheus-specific metrics, opentelemetry-java provides a more versatile and standardized approach to observability. OpenTelemetry supports multiple backends and offers a wider range of telemetry data types, making it more suitable for complex, multi-vendor environments. However, client_java may be preferable for projects deeply integrated with the Prometheus ecosystem or those requiring simpler metric collection.

Convert designs to code with AI

Introducing Visual Copilot: A new AI model to turn Figma designs to high quality code using your components.

Try Visual Copilot

README

OpenTelemetry Java

Project Status

See Java status on OpenTelemetry.io.

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

If you are looking for generated classes for the OpenTelemetry semantic conventions, see semantic-conventions-java.

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.

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

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.
- context api The OpenTelemetry Context implementation.
- incubating apis incubating APIs, including Events.
extensions define additional API extensions not part of the core API, including propagators.
sdk defines the implementation of the OpenTelemetry API.
exporters trace, metric, and log exporters for the SDK.
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.

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. See language version compatibility for complete details.

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

Note that if you want to use any artifacts that have not fully stabilized yet (such as the prometheus exporter, then you will need to add an entry for the Alpha BOM as well, e.g.

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

  implementation('io.opentelemetry:opentelemetry-api')
  implementation('io.opentelemetry:opentelemetry-exporter-prometheus')
  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.43.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.43.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	Javadoc
Bill of Materials (BOM)	Bill of materials for stable artifacts	`opentelemetry-bom`	1.42.0	N/A
Alpha Bill of Materials (BOM)	Bill of materials for alpha artifacts	`opentelemetry-bom-alpha`	1.42.0-alpha	N/A

API

Component	Description	Artifact ID	Version
API	OpenTelemetry API, including metrics, traces, baggage, context	`opentelemetry-api`	1.42.0
API Incubator	API incubator, including pass through propagator, and extended tracer, and Event API	`opentelemetry-api-incubator`	1.42.0
Context API	OpenTelemetry context API	`opentelemetry-context`	1.42.0

API Extensions

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

SDK

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

SDK Exporters

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

SDK Extensions

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

Shims

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