Interface Tracer
- All Superinterfaces:
BaggageManager
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:
- 1.0.0
- See Also:
-
Nested Class Summary
Nested Classes -
Field Summary
Fields -
Method Summary
Modifier and TypeMethodDescriptionRetrieves the current span in scope ornull
if one is not available.Allows to customize the current span in scope.Returns theCurrentTraceContext
.nextSpan()
This creates a new span based on the current span in scope.This creates a new span whose parent isSpan
.In some cases (e.g.startScopedSpan
(String name) Returns a new child span if there's acurrentSpan()
or a new trace if there isn't.Builder forTraceContext
.Makes the given span the "current span" and returns an object that exits that scope on close.Methods inherited from interface io.micrometer.tracing.BaggageManager
createBaggage, createBaggage, getAllBaggage, getBaggage, getBaggage
-
Field Details
-
NOOP
A noop implementation.
-
-
Method Details
-
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
- Parameters:
parent
- parent span- Returns:
- a child span for the given parent,
null
if context was empty.
-
withSpan
Makes the given span the "current span" and returns an object that exits that scope on close. Calls tocurrentSpan()
andcurrentSpanCustomizer()
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
Returns a new child span if there's acurrentSpan()
or a new trace if there isn't. The result is the "current span" untilScopedSpan.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 withPropagator.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 forTraceContext
.- Returns:
- a trace context builder
-
currentTraceContext
CurrentTraceContext currentTraceContext()Returns theCurrentTraceContext
.- Returns:
- current trace context
-
currentSpanCustomizer
Allows to customize the current span in scope.- Returns:
- current span customizer
-
currentSpan
Retrieves the current span in scope ornull
if one is not available.- Returns:
- current span in scope
-