Package io.honeycomb.beeline.tracing

Class Tracer

java.lang.Object

io.honeycomb.beeline.tracing.Tracer

public class Tracer
extends Object

The Tracer manages Spans using thread-local context. It has additional helper methods to support advanced use cases and deal with propagation to other threads.

This class is meant to be used in conjunction with SpanBuilderFactory, which is capable of constructing the Span arguments that must be passed into methods like startTrace(Span).

Span vs. TracerSpan

Some methods in this class return TracerSpan. This is done to clarify that such instances are now managed by the Tracer and user code should no longer interact with the argument. in fact, TracerSpans generally act as decorators around the Span arguments. In any case, most users of the API will want to simply up-cast to Span for cleaner code.

On the other hand, where a method returns just Span, expect the instance to longer be managed by the tracer.

Thread-safety

This class is thread-safe so that it can be shared across the application. In fact, it is recommended to use it as a singleton (e.g. as a singleton bean in Spring application), since thread-local state is tied to the instance (it's an instance variable) and not the class (it is not static).. This state is the hierarchy of Spans representing the trace managed using a thread-local stack.

Because of the thread-local nature of the Tracer, TracerSpans are meant to be used on the thread they are created on. They directly interact with the Tracer's thread-local context.

There are guards and logging in place to deal with situations where this may be violated.

Propagation to other threads

Because of the use of thread-local context you might find traces breaking as you execute code asynchronously.

You can use the trace[Callable/Runnable/...] methods in this class to wrap various functional interfaces and automatically manage propagation when these get passed to, for instance, a CompletableFuture or some Executor.

You can also use startDetachedChildSpan(String) to create a child span that you can pass on to another thread (assuming you safely establish a happens-before relation), where you can choose to handle them manually or start a new trace.

See the javadoc of each of the mentioned methods for more details.

Constructor Summary

Constructors

Constructor	Description
Tracer(SpanBuilderFactory factory)	Creates a tracer.
Tracer(SpanBuilderFactory factory, TracingContext context)

Method Summary

Modifier and Type	Method	Description
void	endTrace()	This ends the trace currently active on this thread and submits the "root" Span to Honeycomb.
TracerSpan	getActiveSpan()	Returns the span that is currently active on this thread - the one that is top of the stack.
Span	popSpan(Span spanToPop)	Detaches the span identified by the argument's spanId from the thread-local context (i.e.
TracerSpan	pushSpan(Span span)	Attaches the Span to the tracer's thread-local context (i.e.
Span	startChildSpan(String childSpanName)	Starts and returns a new span as the child of the previous span.
Span	startDetachedChildSpan(String childSpanName)	Starts and returns a new span as the child of the previous span, but without being attached to this Tracer's thread-local context.
TracerSpan	startTrace(Span span)	Starts a trace by attaching the provided Span to the Tracer's thread-local context as the new "root".
<T> Callable<T>	traceCallable(String childSpanName, Callable<? extends T> callable)	Wraps the supplied Callable so that the currently active trace can be continued within it even if executed asynchronously in a different thread.
<T> Consumer<T>	traceConsumer(String childSpanName, Consumer<? super T> consumer)	Wraps the supplied Consumer so that the currently active trace can be continued within it even if executed asynchronously in a different thread.
<T,R> Function<T,R>	traceFunction(String childSpanName, Function<? super T,? extends R> function)	Wraps the supplied Function so that the currently active trace can be continued within it even if executed asynchronously in a different thread.
Runnable	traceRunnable(String childSpanName, Runnable runnable)	Wraps the supplied Runnable so that the currently active trace can be continued within it even if executed asynchronously in a different thread.
<T> Supplier<T>	traceSupplier(String childSpanName, Supplier<? extends T> supplier)	Wraps the supplied Supplier so that the currently active trace can be continued within it even if executed asynchronously in a different thread.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

Tracer

public Tracer(SpanBuilderFactory factory)

Creates a tracer. You can also use Tracing's factory methods.

Parameters:

factory - used to construct spans internally.

Tracer

public Tracer(SpanBuilderFactory factory,
              TracingContext context)

Method Detail

startTrace

public TracerSpan startTrace(Span span)

Starts a trace by attaching the provided Span to the Tracer's thread-local context as the new "root". It is subsequently wrapped and returned as a managed TracerSpan. See the Tracer's class-level Javadoc for details.

The trace should eventually be ended by calling endTrace() or Span.close() on the "root" Span.

Note that if any Spans are still attached to this Tracer, when this method is called then they will be cleared and submitted to Honeycomb, whilst also logging a warning that trace has been improperly ended.

Parameters:

span - to be attached to this tracer - must not be null.

Returns:

a TracerSpan that wraps the attached Span.

Throws:

IllegalArgumentException - if argument is null.

See Also:

SpanBuilderFactory

pushSpan

public TracerSpan pushSpan(Span span)

Attaches the Span to the tracer's thread-local context (i.e. it pushes onto the stack), so that it becomes the new active Span.

It is subsequently wrapped and returned as a managed TracerSpan. See the Tracer's class-level Javadoc for details.

This differs to startTrace(Span) in that it does not clear existing context, but rather treats the added Span as the child of the previous active Span (i.e. you are pushing it onto a stack).

Note that no checks are performed for whether the new Span's parentSpanId or traceId match with the previous Span. This technically allows the nesting of traces without having to clear the previous trace.

Parameters:

span - to attach to the Tracer.

Returns:

a TracerSpan that wraps the attached Span.

Throws:

IllegalArgumentException - if the argument is null.

popSpan

public Span popSpan(Span spanToPop)

Detaches the span identified by the argument's spanId from the thread-local context (i.e. it pops it off the stack) and returns an instance of it that is no longer managed by this Tracer. Any active children of the Span will also be removed from the stack and submitted to Honeycomb.

Since the returned Span is no longer managed by this Tracer you must explicitly call Span.close() on it in order to submit it to Honeycomb.

If the Span had a parent, then the parent span will become the new active span (i.e. you are popping the active span off of a stack).

Parameters:

spanToPop - used to find the correct span.

Returns:

a detached copy of the span.

Throws:

IllegalArgumentException - if the argument is null.

endTrace

public void endTrace()

This ends the trace currently active on this thread and submits the "root" Span to Honeycomb. This is equivalent to calling Span.close() on the "root" Span instance (e.g. returned by startTrace(Span)).

If children of the "root" Span are still active, because Span.close() has not been properly called on them, then the tracer will perform cleanup of the active children regardless. Note that in that case span durations may be skewed.

getActiveSpan

public TracerSpan getActiveSpan()

Returns the span that is currently active on this thread - the one that is top of the stack. Note, this method is null-safe - a "noop" span is returned if no trace is currently active. This may be due to startTrace not having been called, or because the trace was not sampled (see SpanBuilderFactory.

Example

 if (underAttack) {
      final Span currentSpan = tracer.getActiveSpan()
           .addField("alert-message", "We are under attack!")
           .addField("alert-level", "red");
 }
 

Returns:

the active span.

startChildSpan

public Span startChildSpan(String childSpanName)

Starts and returns a new span as the child of the previous span.

This means the child becomes the new active span (see getActiveSpan() on this thread. The old active span (i.e the "parent span") is linked to the child via the Parent ID and via reference. When Span.close() closing the child} the parent will be reset to being the active span.

Because of the parent and child being linked by reference, the child's lifetime is tied and limited to that of the parent.

Example

 // try-with-resources statement automatically closes the span
 try (Span childSpan = tracer.startChildSpan("http-call")) {
      childSpan.addField("http-url", url);
      return httpClient.get(url);
 }
 

Parameters:

childSpanName - to use as the name of the new span - must not be empty.

Returns:

new child span.

Throws:

IllegalArgumentException - if the argument is null or empty.

startDetachedChildSpan

public Span startDetachedChildSpan(String childSpanName)

Starts and returns a new span as the child of the previous span, but without being attached to this Tracer's thread-local context. Thus, the active span remains unchanged. This also means the returned span's lifetime is not tied to the lifetime of the parent. It is linked to its parent via the parentSpanId only.

This is for advanced use cases when, for instance, you need to track asynchronous computations and call Span.markStart() and Span.close() at specific points.

The trace*() methods might be useful if you need to trace lambdas/functional interfaces.

If your computation does not cross thread boundaries startChildSpan(String) may be more convenient.

Example

 final Span httpServiceSpan = tracer.startDetachedChildSpan("http-call");
 httpServiceSpan.addField("http-url", url);

 CompletableFuture
      .supplyAsync(()-> {         // on a different thread, so using the tracer won't work here
          httpServiceSpan.markStart();    // start measuring time when thread actually starts processing
          return httpClient.get(url);
      })
      .thenApplyAsync(this::convertResponse)
      .thenApplyAsync(this::handleResponse)
      // add exception message if something went wrong
      .exceptionally(e-> httpServiceSpan.addField("error-message", e.getMessage()))
      .thenRun(httpServiceSpan::close);     // close span and submit to Honeycomb
 

Parameters:

childSpanName - to use as the name of the new span - must not be empty.

Returns:

new detached child span.

Throws:

IllegalArgumentException - if the argument is null or empty.

traceRunnable

public Runnable traceRunnable(String childSpanName,
                              Runnable runnable)

Wraps the supplied Runnable so that the currently active trace can be continued within it even if executed asynchronously in a different thread. The child span's lifetime is therefore not tied to the lifetime of the parent.

If the returned Runnable is executed on another thread it initializes the tracer's thread-local context for that thread, while leaving the current thread's context unaffected.

If run on the same thread while the current trace is still active this will simply start a new child span within the current thread's context.

Example

 CompletableFuture.runAsync(tracer.traceRunnable("http-call", ()-> httpClient.get(url)));
 

Parameters:

childSpanName - name of the child Span created for the runnable - must not be null or empty.

runnable - to wrap - must not be null.

Returns:

a traced Runnable.

Throws:

IllegalArgumentException - if arguments are null or empty.

traceCallable

public <T> Callable<T> traceCallable(String childSpanName,
                                     Callable<? extends T> callable)

Wraps the supplied Callable so that the currently active trace can be continued within it even if executed asynchronously in a different thread. The child span's lifetime is therefore not tied to the lifetime of the parent.

If the returned Callable is executed on another thread it initializes the tracer's thread-local context for that thread, while leaving the current thread's context unaffected.

If run on the same thread while the current trace is still active this will simply start a new child span within the current thread's context.

Example

 Future<Response> responseFuture =
      executor.submit(tracer.traceCallable("http-call", ()-> httpClient.get(url)));
 

Type Parameters:

T - the return type.

Parameters:

childSpanName - name of the child Span created for the Callable - must not be null or empty.

callable - to wrap - must not be null.

Returns:

a traced Callable.

Throws:

IllegalArgumentException - if arguments are null or empty.

traceSupplier

public <T> Supplier<T> traceSupplier(String childSpanName,
                                     Supplier<? extends T> supplier)

Wraps the supplied Supplier so that the currently active trace can be continued within it even if executed asynchronously in a different thread. The child span's lifetime is therefore not tied to the lifetime of the parent.

If the returned Supplier is executed on another thread it initializes the tracer's thread-local context for that thread, while leaving the current thread's context unaffected.

If run on the same thread while the current trace is still active this will simply start a new child span within the current thread's context.

Example

 CompletableFuture.supplyAsync(tracer.traceSupplier("http-call", ()-> httpClient.get(url)))
 

Type Parameters:

T - the return type.

Parameters:

childSpanName - name of the child Span created for the Supplier - must not be null or empty.

supplier - to wrap - must not be null.

Returns:

a traced Supplier.

Throws:

IllegalArgumentException - if arguments are null or empty.

traceFunction

public <T,R> Function<T,R> traceFunction(String childSpanName,
                                         Function<? super T,? extends R> function)

Wraps the supplied Function so that the currently active trace can be continued within it even if executed asynchronously in a different thread. The child span's lifetime is therefore not tied to the lifetime of the parent.

If the returned Function is executed on another thread it initializes the tracer's thread-local context for that thread, while leaving the current thread's context unaffected.

If run on the same thread while the current trace is still active this will simply start a new child span within the current thread's context.

Example

 completableFuture.thenApply(tracer.traceFunction("handle-response", Converter::convertResponse));
 

Type Parameters:

T - the parameter type.

R - the return type.

Parameters:

childSpanName - name of the child Span created for the Function - must not be null or empty.

function - to wrap - must not be null.

Returns:

a traced Function.

Throws:

IllegalArgumentException - if arguments are null or empty.

traceConsumer

public <T> Consumer<T> traceConsumer(String childSpanName,
                                     Consumer<? super T> consumer)

Wraps the supplied Consumer so that the currently active trace can be continued within it even if executed asynchronously in a different thread. The child span's lifetime is therefore not tied to the lifetime of the parent.

If the returned Consumer is executed on another thread it initializes the tracer's thread-local context for that thread, while leaving the current thread's context unaffected.

If run on the same thread while the current trace is still active this will simply start a new child span within the current thread's context.

Example

 completableFuture.thenAccept(
      tracer.traceConsumer("handle-response", (response)-> handleResponse(response)));
 

Type Parameters:

T - the return type.

Parameters:

childSpanName - name of the child Span created for the Consumer - must not be null or empty.

consumer - to wrap - must not be null.

Returns:

a traced Consumer.

Throws:

IllegalArgumentException - if arguments are null or empty.