io.opentelemetry.trace

Interface Tracer

All Known Implementing Classes:

DefaultTracer

@ThreadSafe
public interface Tracer

Tracer is the interface for Span creation and interaction with the in-process context.

Users may choose to use manual or automatic Context propagation. Because of that this class offers APIs to facilitate both usages.

The automatic context propagation is done using Context which is a gRPC independent implementation for in-process Context propagation mechanism which can carry scoped-values across API boundaries and between threads. Users of the library must propagate the Context between different threads.

Example usage with automatic context propagation:

 class MyClass {
   private static final Tracer tracer = OpenTelemetry.getTracer();
   void doWork() {
     Span span = tracer.spanBuilder("MyClass.DoWork").startSpan();
     try(Scope ss = tracer.withSpan(span)) {
       tracer.getCurrentSpan().addEvent("Starting the work.");
       doWorkInternal();
       tracer.getCurrentSpan().addEvent("Finished working.");
     } finally {
       span.end();
     }
   }
 }
 

Example usage with manual context propagation:

 class MyClass {
   private static final Tracer tracer = OpenTelemetry.getTracer();
   void doWork(Span parent) {
     Span childSpan = tracer.spanBuilder("MyChildSpan")
         setParent(parent).startSpan();
     childSpan.addEvent("Starting the work.");
     try {
       doSomeWork(childSpan); // Manually propagate the new span down the stack.
     } finally {
       // To make sure we end the span even in case of an exception.
       childSpan.end();  // Manually end the span.
     }
   }
 }
 

Since:

0.1.0

Method Summary

Modifier and Type	Method and Description
Span	getCurrentSpan() Gets the current Span from the current Context.
Span.Builder	spanBuilder(String spanName) Returns a Span.Builder to create and start a new Span.
io.opentelemetry.context.Scope	withSpan(Span span) Enters the scope of code where the given Span is in the current Context, and returns an object that represents that scope.

Method Detail

getCurrentSpan

Span getCurrentSpan()

Gets the current Span from the current Context.

To install a Span to the current Context use withSpan(Span).

startSpan methods do NOT modify the current Context Span.

Returns:

a default Span that does nothing and has an invalid SpanContext if no Span is associated with the current Context, otherwise the current Span from the Context.

Since:

0.1.0

withSpan

@MustBeClosed
io.opentelemetry.context.Scope withSpan(Span span)

Enters the scope of code where the given Span is in the current Context, and returns an object that represents that scope. The scope is exited when the returned object is closed.

Supports try-with-resource idiom.

Can be called with DefaultSpan to enter a scope of code where tracing is stopped.

Example of usage:

 private static Tracer tracer = OpenTelemetry.getTracer();
 void doWork() {
   // Create a Span as a child of the current Span.
   Span span = tracer.spanBuilder("my span").startSpan();
   try (Scope ws = tracer.withSpan(span)) {
     tracer.getCurrentSpan().addEvent("my event");
     doSomeOtherWork();  // Here "span" is the current Span.
   }
   span.end();
 }
 

Prior to Java SE 7, you can use a finally block to ensure that a resource is closed regardless of whether the try statement completes normally or abruptly.

Example of usage prior to Java SE7:

 private static Tracer tracer = OpenTelemetry.getTracer();
 void doWork() {
   // Create a Span as a child of the current Span.
   Span span = tracer.spanBuilder("my span").startSpan();
   Scope ws = tracer.withSpan(span);
   try {
     tracer.getCurrentSpan().addEvent("my event");
     doSomeOtherWork();  // Here "span" is the current Span.
   } finally {
     ws.close();
   }
   span.end();
 }
 

Parameters:

span - The Span to be set to the current Context.

Returns:

an object that defines a scope where the given Span will be set to the current Context.

Throws:

NullPointerException - if span is null.

Since:

0.1.0

spanBuilder

Span.Builder spanBuilder(String spanName)

Returns a Span.Builder to create and start a new Span.

See Span.Builder for usage examples.

Parameters:

spanName - The name of the returned Span.

Returns:

a Span.Builder to create and start a new Span.

Throws:

NullPointerException - if spanName is null.

Since:

0.1.0