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!

Nested and Inner Type Summary

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

Field Summary

Modifier and Type	Field and Description
public static final Tracer	NOOP Hides io.micrometer.tracing.BaggageManager.NOOP. A noop implementation.

Method Summary

Modifier and Type	Method and Description
public Span	Returns: current span in scope currentSpan() Retrieves the current span in scope or `null` if one is not available.
public SpanCustomizer	Returns: current span customizer currentSpanCustomizer() Allows to customize the current span in scope.
public CurrentTraceContext	Returns: current trace context currentTraceContext() Returns the `CurrentTraceContext`.
public Span	Returns: a child span or a new trace if no span was present nextSpan() This creates a new span based on the current span in scope.
public Span	Returns: a child span for the given parent, `null` if context was empty. nextSpan(Span parent span parent) This creates a new span whose parent is `Span`.
public Span.Builder	Returns: a 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).
public ScopedSpan	Returns: span in scope startScopedSpan(String of the span in scope name) Returns a new child span if there's a `currentSpan()` or a new trace if there isn't.
public TraceContext.Builder	Returns: a trace context builder traceContextBuilder() Builder for `TraceContext`.
public Tracer.SpanInScope	Returns: scope with span in it withSpan(Span span to place into scope or null to clear the scope span) Makes the given span the "current span" and returns an object that exits that scope on close.

Inherited from io.micrometer.tracing.BaggageManager:: createBaggage createBaggage createBaggageInScope createBaggageInScope getAllBaggage getAllBaggage getBaggage getBaggage

Field Detail

NOOP	back to summary
public static final Tracer NOOP Hides io.micrometer.tracing.BaggageManager.NOOP. A noop implementation.

NOOP

back to summary

public static final Tracer NOOP

Hides io.micrometer.tracing.BaggageManager.NOOP.

A noop implementation.

Method Detail

currentSpan back to summary

currentSpan	back to summary
public Span currentSpan() Retrieves the current span in scope or `null` if one is not available. Returns:Span current span in scope Annotations @Nullable

public Span currentSpan()

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

Returns:Span

current span in scope

Annotations

@Nullable

currentSpanCustomizer	back to summary
public SpanCustomizer currentSpanCustomizer() Allows to customize the current span in scope. Returns:SpanCustomizer current span customizer Annotations @Nullable

currentSpanCustomizer

back to summary

public SpanCustomizer currentSpanCustomizer()

Allows to customize the current span in scope.

Returns:SpanCustomizer

current span customizer

Annotations

@Nullable

currentTraceContext back to summary

currentTraceContext	back to summary
public CurrentTraceContext currentTraceContext() Returns the `CurrentTraceContext`. Returns:CurrentTraceContext current trace context

public CurrentTraceContext currentTraceContext()

Returns the CurrentTraceContext.

Returns:CurrentTraceContext: current trace context

nextSpan	back to summary
public 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:Span a child span or a new trace if no span was present

nextSpan

back to summary

public 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:Span: a child span or a new trace if no span was present

nextSpan back to summary

nextSpan	back to summary
public Span nextSpan(Span parent) This creates a new span whose parent is `Span`. If parent is `null` then will create act as `nextSpan()`. Parameters parent:Span parent span Returns:Span a child span for the given parent, `null` if context was empty.

public Span nextSpan(Span parent)

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

Parameters

parent:Span: parent span

Returns:Span

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

spanBuilder back to summary

spanBuilder	back to summary
public 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:Span.Builder a span builder

public 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:Span.Builder: a span builder

startScopedSpan back to summary

startScopedSpan	back to summary
public 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:String of the span in scope Returns:ScopedSpan span in scope

public 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:String: of the span in scope

Returns:ScopedSpan

span in scope

traceContextBuilder back to summary

traceContextBuilder	back to summary
public TraceContext.Builder traceContextBuilder() Builder for `TraceContext`. Returns:TraceContext.Builder a trace context builder

public TraceContext.Builder traceContextBuilder()

Builder for TraceContext.

Returns:TraceContext.Builder: a trace context builder

withSpan back to summary

withSpan	back to summary
public Tracer.SpanInScope withSpan(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 span to place into scope or null to clear the scope Returns:Tracer.SpanInScope scope with span in it

public Tracer.SpanInScope withSpan(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: span to place into scope or null to clear the scope

Returns:Tracer.SpanInScope

scope with span in it

io.micrometer.tracing back to summary

public Interface Tracer.SpanInScope

extends Closeable

Scope of a span. Needs to be closed so that resources are let go (e.g. MDC is cleared).

Method Summary

Modifier and Type	Method and Description
public void	close() Redeclares java.io.Closeable.close. Closes this stream and releases any system resources associated with it.

Method Detail

close back to summary

close	back to summary
public void close() Redeclares java.io.Closeable.close. Doc from java.io.Closeable.close. Closes this stream and releases any system resources associated with it. If the stream is already closed then invoking this method has no effect. As noted in `AutoCloseable#close()`, cases where the close may fail require careful attention. It is strongly advised to relinquish the underlying resources and to internally mark the `Closeable` as closed, prior to throwing the `IOException`. Annotations @Override

public void close()

Redeclares java.io.Closeable.close.

Doc from java.io.Closeable.close.

Closes this stream and releases any system resources associated with it. If the stream is already closed then invoking this method has no effect.

As noted in AutoCloseable#close(), cases where the close may fail require careful attention. It is strongly advised to relinquish the underlying resources and to internally mark the Closeable as closed, prior to throwing the IOException.

Annotations

@Override