Top Related Projects
OpenTracing API for Java. 🛑 This library is DEPRECATED! https://github.com/opentracing/specification/issues/163
Zipkin is a distributed tracing system
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 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 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.
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 CopilotREADME
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.
Bill of Materials (BOMs)
A bill of materials (or BOM) helps sync dependency versions of related artifacts.
Component | Description | Artifact ID | Version | Javadoc |
---|---|---|---|---|
Bill of Materials (BOM) | Bill of materials for stable artifacts | opentelemetry-bom | 1.45.0 | N/A |
Alpha Bill of Materials (BOM) | Bill of materials for alpha artifacts | opentelemetry-bom-alpha | 1.45.0-alpha | N/A |
API
The OpenTelemetry API for recording telemetry.
Component | Description | Artifact ID | Version | Javadoc |
---|---|---|---|---|
API | OpenTelemetry API, including metrics, traces, baggage, context | opentelemetry-api | 1.45.0 | |
API Incubator | API incubator, including pass through propagator, and extended tracer, and Event API | opentelemetry-api-incubator | 1.45.0-alpha | |
Context API | OpenTelemetry context API | opentelemetry-context | 1.45.0 |
API Extensions
Extensions to the OpenTelemetry API.
Component | Description | Artifact ID | Version | Javadoc |
---|---|---|---|---|
Kotlin Extension | Context extension for coroutines | opentelemetry-extension-kotlin | 1.45.0 | |
Trace Propagators Extension | Trace propagators, including B3, Jaeger, OT Trace | opentelemetry-extension-trace-propagators | 1.45.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.45.0 | |
Metrics SDK | OpenTelemetry metrics SDK | opentelemetry-sdk-metrics | 1.45.0 | |
Trace SDK | OpenTelemetry trace SDK | opentelemetry-sdk-trace | 1.45.0 | |
Log SDK | OpenTelemetry log SDK | opentelemetry-sdk-logs | 1.45.0 | |
SDK Common | Shared SDK components | opentelemetry-sdk-common | 1.45.0 | |
SDK Testing | Components for testing OpenTelemetry instrumentation | opentelemetry-sdk-testing | 1.45.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.45.0 | |
OTLP Logging Exporters | Logging exporters in OTLP JSON encoding, including traces, metrics, and logs | opentelemetry-exporter-logging-otlp | 1.45.0 | |
OTLP Common | Shared OTLP components (internal) | opentelemetry-exporter-otlp-common | 1.45.0 | |
Logging Exporter | Logging exporters, including metrics, traces, and logs | opentelemetry-exporter-logging | 1.45.0 | |
Zipkin Exporter | Zipkin trace exporter | opentelemetry-exporter-zipkin | 1.45.0 | |
Prometheus Exporter | Prometheus metric exporter | opentelemetry-exporter-prometheus | 1.45.0-alpha | |
Exporter Common | Shared exporter components (internal) | opentelemetry-exporter-common | 1.45.0 | |
OkHttp Sender | OkHttp implementation of HttpSender (internal) | opentelemetry-exporter-sender-okhttp | 1.45.0 | |
JDK Sender | Java 11+ native HttpClient implementation of HttpSender (internal) | opentelemetry-exporter-sender-jdk | 1.45.0 | |
gRPC ManagedChannel Sender | gRPC ManagedChannel implementation of GrpcSender (internal) | opentelemetry-exporter-sender-grpc-managed-channel | 1.45.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.45.0 | |
SDK Autoconfigure SPI | Service Provider Interface (SPI) definitions for autoconfigure | opentelemetry-sdk-extension-autoconfigure-spi | 1.45.0 | |
SDK Jaeger Remote Sampler Extension | Sampler which obtains sampling configuration from remote Jaeger server | opentelemetry-sdk-extension-jaeger-remote-sampler | 1.45.0 | |
SDK Incubator | SDK incubator, including YAML based view configuration, LeakDetectingSpanProcessor | opentelemetry-sdk-extension-incubator | 1.45.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.45.0-alpha | |
OpenTracing Shim | Bridge opentracing spans into the OpenTelemetry trace API | opentelemetry-opentracing-shim | 1.45.0 |
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:
Gradle
implementation('io.opentelemetry:{{artifact-id}}')
Maven
<dependency>
<groupId>io.opentelemetry</groupId>
<artifactId>{{artifact-id}}</artifactId>
</dependency>
Snapshots
Snapshots of the main
branch are available as follows:
Gradle
repositories {
maven { url 'https://oss.sonatype.org/content/repositories/snapshots' }
}
dependencies {
implementation platform("io.opentelemetry:opentelemetry-bom:1.46.0-SNAPSHOT")
implementation('io.opentelemetry:opentelemetry-api')
}
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.46.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.
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
Code owners
Triagers:
- Gregor Zeitlinger, Grafana Labs
Find more about the triager role in community repository.
Approvers (@open-telemetry/java-approvers):
- Jason Plumb, Splunk
- Josh Suereth, Google
- Lauri Tulmin, Splunk
- Trask Stalnaker, Microsoft
Find more about the approver role in community repository.
Maintainers (@open-telemetry/java-maintainers):
- Jack Berg, New Relic
- John Watson, Verta.ai
Emeritus:
- Maintainer Bogdan Drutu
- Maintainer Carlos Alberto
- Approver Mateusz Rzeszutek
Find more about the maintainer role in community repository.
Thanks to all the people who have contributed
Made with contrib.rocks.
Top Related Projects
OpenTracing API for Java. 🛑 This library is DEPRECATED! https://github.com/opentracing/specification/issues/163
Zipkin is a distributed tracing system
Prometheus instrumentation library for JVM applications
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