Convert Figma logo to code with AI

open-telemetry logoopentelemetry-java

OpenTelemetry Java SDK

2,063
848
2,063
158

Top Related Projects

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

16,970

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

  1. 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();
}
  1. Adding attributes to a span:
Span span = tracer.spanBuilder("my span").startSpan();
span.setAttribute("http.method", "GET");
span.setAttribute("http.url", "https://example.com");
  1. 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.

16,970

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 Figma logo designs to code with AI

Visual Copilot

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

Try Visual Copilot

README

OpenTelemetry Java

Continuous Build Coverage Status Maven Central Reproducible Builds

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.

ComponentDescriptionArtifact IDVersionJavadoc
Bill of Materials (BOM)Bill of materials for stable artifactsopentelemetry-bom1.45.0N/A
Alpha Bill of Materials (BOM)Bill of materials for alpha artifactsopentelemetry-bom-alpha1.45.0-alphaN/A
API

The OpenTelemetry API for recording telemetry.

ComponentDescriptionArtifact IDVersionJavadoc
APIOpenTelemetry API, including metrics, traces, baggage, contextopentelemetry-api1.45.0Javadocs
API IncubatorAPI incubator, including pass through propagator, and extended tracer, and Event APIopentelemetry-api-incubator1.45.0-alphaJavadocs
Context APIOpenTelemetry context APIopentelemetry-context1.45.0Javadocs
API Extensions

Extensions to the OpenTelemetry API.

ComponentDescriptionArtifact IDVersionJavadoc
Kotlin ExtensionContext extension for coroutinesopentelemetry-extension-kotlin1.45.0Javadocs
Trace Propagators ExtensionTrace propagators, including B3, Jaeger, OT Traceopentelemetry-extension-trace-propagators1.45.0Javadocs
SDK

The OpenTelemetry SDK for managing telemetry producing by the API.

ComponentDescriptionArtifact IDVersionJavadoc
SDKOpenTelemetry SDK, including metrics, traces, and logsopentelemetry-sdk1.45.0Javadocs
Metrics SDKOpenTelemetry metrics SDKopentelemetry-sdk-metrics1.45.0Javadocs
Trace SDKOpenTelemetry trace SDKopentelemetry-sdk-trace1.45.0Javadocs
Log SDKOpenTelemetry log SDKopentelemetry-sdk-logs1.45.0Javadocs
SDK CommonShared SDK componentsopentelemetry-sdk-common1.45.0Javadocs
SDK TestingComponents for testing OpenTelemetry instrumentationopentelemetry-sdk-testing1.45.0Javadocs
SDK Exporters

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

ComponentDescriptionArtifact IDVersionJavadoc
OTLP ExportersOTLP gRPC & HTTP exporters, including traces, metrics, and logsopentelemetry-exporter-otlp1.45.0Javadocs
OTLP Logging ExportersLogging exporters in OTLP JSON encoding, including traces, metrics, and logsopentelemetry-exporter-logging-otlp1.45.0Javadocs
OTLP CommonShared OTLP components (internal)opentelemetry-exporter-otlp-common1.45.0Javadocs
Logging ExporterLogging exporters, including metrics, traces, and logsopentelemetry-exporter-logging1.45.0Javadocs
Zipkin ExporterZipkin trace exporteropentelemetry-exporter-zipkin1.45.0Javadocs
Prometheus ExporterPrometheus metric exporteropentelemetry-exporter-prometheus1.45.0-alphaJavadocs
Exporter CommonShared exporter components (internal)opentelemetry-exporter-common1.45.0Javadocs
OkHttp SenderOkHttp implementation of HttpSender (internal)opentelemetry-exporter-sender-okhttp1.45.0Javadocs
JDK SenderJava 11+ native HttpClient implementation of HttpSender (internal)opentelemetry-exporter-sender-jdk1.45.0Javadocs
gRPC ManagedChannel SendergRPC ManagedChannel implementation of GrpcSender (internal)opentelemetry-exporter-sender-grpc-managed-channel1.45.0Javadocs
SDK Extensions

Extensions to the OpenTelemetry SDK.

ComponentDescriptionArtifact IDVersionJavadoc
SDK AutoconfigureAutoconfigure OpenTelemetry SDK from env vars, system properties, and SPIopentelemetry-sdk-extension-autoconfigure1.45.0Javadocs
SDK Autoconfigure SPIService Provider Interface (SPI) definitions for autoconfigureopentelemetry-sdk-extension-autoconfigure-spi1.45.0Javadocs
SDK Jaeger Remote Sampler ExtensionSampler which obtains sampling configuration from remote Jaeger serveropentelemetry-sdk-extension-jaeger-remote-sampler1.45.0Javadocs
SDK IncubatorSDK incubator, including YAML based view configuration, LeakDetectingSpanProcessoropentelemetry-sdk-extension-incubator1.45.0-alphaJavadocs
Shims

Shims for bridging data from one observability library to another.

ComponentDescriptionArtifact IDVersionJavadoc
OpenCensus ShimBridge opencensus metrics into the OpenTelemetry metrics SDKopentelemetry-opencensus-shim1.45.0-alphaJavadocs
OpenTracing ShimBridge opentracing spans into the OpenTelemetry trace APIopentelemetry-opentracing-shim1.45.0Javadocs

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:

Find more about the triager role in community repository.

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

Find more about the approver role in community repository.

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

Emeritus:

Find more about the maintainer role in community repository.

Thanks to all the people who have contributed

Made with contrib.rocks.