org.springframework.cloud.sleuth

Interface Tracer

All Superinterfaces:

SpanAccessor

All Known Implementing Classes:

DefaultTracer

public interface Tracer
extends SpanAccessor

The Tracer class is the primary way for instrumentation code (note user code) to interact with the library. It provides methods to create and manipulate spans.

A 'span' represents a length of time. It has many other attributes such as a name, ID, and even potentially a set of key/value strings attached to it.

Each thread in your application has a single currently active currentSpan associated with it. When this is non-null, it represents the current operation that the thread is doing. spans are NOT thread-safe, and must never be used by multiple threads at once. With care, it is possible to safely pass a span object between threads, but in most cases this is not necessary.

Most crucial methods in terms of span lifecycle are:

• The createSpan method in this class starts a new span.
• The createSpan method creates a new span which has this thread's currentSpan as one of its parents
• The continueSpan method creates a new instance of span that logically is a continuation of the provided span.

Closing a TraceScope does a few things:

• It closes the span which the scope was managing.
• Set currentSpan to the previous currentSpan (which may be null).

Since:

1.0.0

Method Summary

Modifier and Type	Method and Description
void	addTag(String key, String value) Adds a tag to the current span if tracing is currently on.
Span	close(Span span) Remove this span from the current thread, stop it and send it for collection.
Span	continueSpan(Span span) Contributes to a span started in another thread.
Span	createSpan(String name) Creates a new Span.
Span	createSpan(String name, Sampler sampler) Start a new span if the sampler allows it or if we are already tracing in this thread.
Span	createSpan(String name, Span parent) Creates a new Span with a specific parent.
Span	detach(Span span) Remove this span from the current thread, but don't stop it yet or send it for collection.
<V> Callable<V>	wrap(Callable<V> callable) Returns a wrapped Callable which will be recorded as a span in the current trace.
Runnable	wrap(Runnable runnable) Returns a wrapped Runnable which will be recorded as a span in the current trace.

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

getCurrentSpan, isTracing

Method Detail

createSpan

Span createSpan(String name)

Creates a new Span.

If this thread has a currently active span, it will be the parent of the span we create here. If there is no currently active trace span, the trace scope we create will be empty.

Parameters:

name - The name field for the new span to create.

createSpan

Span createSpan(String name,
                Span parent)

Creates a new Span with a specific parent. The parent might be in another process or thread.

If this thread has a currently active trace span, it must be the 'parent' span that you pass in here as a parameter. The trace scope we create here will contain a new span which is a child of 'parent'.

Parameters:

name - The name field for the new span to create.

createSpan

Span createSpan(String name,
                Sampler sampler)

Start a new span if the sampler allows it or if we are already tracing in this thread. A sampler can be used to limit the number of traces created.

Parameters:

name - the name of the span

sampler - a sampler to decide whether to create the span or not

continueSpan

Span continueSpan(Span span)

Contributes to a span started in another thread. The returned span shares mutable state with the input.

addTag

void addTag(String key,
            String value)

Adds a tag to the current span if tracing is currently on.

Every span may also have zero or more key/value Tags, which do not have timestamps and simply annotate the spans. Check TraceKeys for examples of most common tag keys

detach

Span detach(Span span)

Remove this span from the current thread, but don't stop it yet or send it for collection. This is useful if the span object is then passed to another thread for use with continueSpan(Span).

Example of usage:

     // Span "A" was present in thread "X". Let's assume that we're in thread "Y" to which span "A" got passed
     Span continuedSpan = tracer.continueSpan(spanA);
     // Now span "A" got continued in thread "Y".
     ... // Some work is done... state of span "A" could get mutated
     Span previouslyStoredSpan = tracer.detach(continuedSpan);
     // Span "A" got removed from the thread Y but it wasn't yet sent for collection.
     // Additional work can be done on span "A" in thread "X" and finally it can get closed and sent for collection
     tracer.close(spanA);
 

Returns:

the saved trace if there was one before the trace started (null otherwise)

close

Span close(Span span)

Remove this span from the current thread, stop it and send it for collection.

Parameters:

span - the span to close

Returns:

the saved span if there was one before the trace started (null otherwise)

wrap

<V> Callable<V> wrap(Callable<V> callable)

Returns a wrapped Callable which will be recorded as a span in the current trace.

wrap

Runnable wrap(Runnable runnable)

Returns a wrapped Runnable which will be recorded as a span in the current trace.