Package io.micrometer.tracing

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:
1.0.0
See Also:

  • Field Details

    • NOOP

      static final Tracer 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

      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

      CurrentTraceContext currentTraceContext()
      Returns the CurrentTraceContext.
      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