Package 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

    • 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

      • 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