org.springframework.cloud.sleuth

Interface Tracer

All Superinterfaces:

BaggageManager

public interface Tracer
extends BaggageManager

This API was heavily influenced by Brave. Parts of its documentation were taken directly from Brave. Using a tracer, you can create a root span capturing the critical path of a request. Child spans can be created to allocate latency relating to outgoing requests. When tracing single-threaded code, just run it inside a scoped span:

 // Start a new trace or a span within an existing trace representing an operation
 ScopedSpan span = tracer.startScopedSpan("encode");
 try {
   // The span is in "scope" so that downstream code such as loggers can see trace IDs
   return encoder.encode();
 } catch (RuntimeException | Error e) {
   span.error(e); // Unless you handle exceptions, you might not know the operation failed!
   throw e;
 } finally {
   span.end();
 }
 

When you need more features, or finer control, use the Span type:

 // Start a new trace or a span within an existing trace representing an operation
 Span span = tracer.nextSpan().name("encode").start();
 // Put the span in "scope" so that downstream code such as loggers can see trace IDs
 try (SpanInScope ws = tracer.withSpanInScope(span)) {
   return encoder.encode();
 } catch (RuntimeException | Error e) {
   span.error(e); // Unless you handle exceptions, you might not know the operation failed!
   throw e;
 } finally {
   span.end(); // note the scope is independent of the span. Always finish a span.
 }
 

Both of the above examples report the exact same span on finish!

Since:

3.0.0

Author:

OpenZipkin Brave Authors, Marcin Grzejszczak

See Also:

Span, ScopedSpan, Propagator

Nested Class Summary

Nested Classes

Modifier and Type	Interface and Description
static interface	Tracer.SpanInScope Scope of a span.

Method Summary

Modifier and Type	Method and Description
Span	currentSpan() Retrieves the current span in scope or null if one is not available.
SpanCustomizer	currentSpanCustomizer() Allows to customize the current span in scope.
default CurrentTraceContext	currentTraceContext() Returns the CurrentTraceContext.
Span	nextSpan() This creates a new span based on the current span in scope.
Span	nextSpan(Span parent) This creates a new span whose parent is Span.
Span.Builder	spanBuilder() In some cases (e.g.
ScopedSpan	startScopedSpan(String name) Returns a new child span if there's a currentSpan() or a new trace if there isn't.
TraceContext.Builder	traceContextBuilder() Builder for TraceContext.
Tracer.SpanInScope	withSpan(Span span) Makes the given span the "current span" and returns an object that exits that scope on close.

Methods inherited from interface org.springframework.cloud.sleuth.BaggageManager

createBaggage, createBaggage, getAllBaggage, getBaggage, getBaggage

Method Detail

nextSpan

Span nextSpan()

This creates a new span based on the current span in scope. If there's no such span a new trace will be created.

Returns:

a child span or a new trace if no span was present

nextSpan

Span nextSpan(@Nullable
              Span parent)

This creates a new span whose parent is Span. If parent is null then will create act as nextSpan().

Parameters:

parent - parent span

Returns:

a child span for the given parent, null if context was empty.

withSpan

Tracer.SpanInScope withSpan(@Nullable
                            Span span)

Makes the given span the "current span" and returns an object that exits that scope on close. Calls to currentSpan() and currentSpanCustomizer() will affect this span until the return value is closed. The most convenient way to use this method is via the try-with-resources idiom. When tracing in-process commands, prefer startScopedSpan(String) which scopes by default. Note: While downstream code might affect the span, calling this method, and calling close on the result have no effect on the input. For example, calling close on the result does not finish the span. Not only is it safe to call close, you must call close to end the scope, or risk leaking resources associated with the scope.

Parameters:

span - span to place into scope or null to clear the scope

Returns:

scope with span in it

startScopedSpan

ScopedSpan startScopedSpan(String name)

Returns a new child span if there's a currentSpan() or a new trace if there isn't. The result is the "current span" until ScopedSpan.end() ()} is called. Here's an example:

 ScopedSpan span = tracer.startScopedSpan("encode");
 try {
   // The span is in "scope" so that downstream code such as loggers can see trace IDs
   return encoder.encode();
 } catch (RuntimeException | Error e) {
   span.error(e); // Unless you handle exceptions, you might not know the operation failed!
   throw e;
 } finally {
   span.end();
 }
 

Parameters:

name - of the span in scope

Returns:

span in scope

spanBuilder

Span.Builder spanBuilder()

In some cases (e.g. when dealing with Propagator.extract(Object, Propagator.Getter)'s we want to create a span that has not yet been started, yet it's heavily configurable (some options are not possible to be set when a span has already been started). We can achieve that by using a builder.

Returns:

a span builder

traceContextBuilder

TraceContext.Builder traceContextBuilder()

Builder for TraceContext.

Returns:

a trace context builder

currentTraceContext

@Nullable
default CurrentTraceContext currentTraceContext()

Returns the CurrentTraceContext. Can be null so that we don't break backward compatibility.

Returns:

current trace context

currentSpanCustomizer

@Nullable
SpanCustomizer currentSpanCustomizer()

Allows to customize the current span in scope.

Returns:

current span customizer

currentSpan

@Nullable
Span currentSpan()

Retrieves the current span in scope or null if one is not available.

Returns:

current span in scope