io.opentracing.v_030.mock

Class MockTracer

java.lang.Object

io.opentracing.v_030.mock.MockTracer

All Implemented Interfaces:

ActiveSpanSource, Tracer

public class MockTracer
extends Object
implements Tracer

MockTracer makes it easy to test the semantics of OpenTracing instrumentation. By using a MockTracer as an io.opentracing.v_030.Tracer implementation for unittests, a developer can assert that Span properties and relationships with other Spans are defined as expected by instrumentation code. The MockTracerTest has simple usage examples.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static interface	MockTracer.Propagator Propagator allows the developer to intercept and verify any calls to inject() and/or extract().
class	MockTracer.SpanBuilder

Constructor Summary

Constructors

Constructor and Description
MockTracer()
MockTracer(ActiveSpanSource spanSource)
MockTracer(ActiveSpanSource spanSource, MockTracer.Propagator propagator)
MockTracer(MockTracer.Propagator propagator) Create a new MockTracer that passes through any calls to inject() and/or extract().

Method Summary

Modifier and Type	Method and Description
ActiveSpan	activeSpan() Return the active span.
MockTracer.SpanBuilder	buildSpan(String operationName) Return a new SpanBuilder for a Span with the given `operationName`.
<C> SpanContext	extract(Format<C> format, C carrier) Extract a SpanContext from a `carrier` of a given type, presumably after propagation across a process boundary.
List<MockSpan>	finishedSpans()
<C> void	inject(SpanContext spanContext, Format<C> format, C carrier) Inject a SpanContext into a `carrier` of a given type, presumably for propagation across process boundaries.
ActiveSpan	makeActive(Span span) Wrap and "make active" a Span by encapsulating it – and any active state (e.g., MDC state) in the current thread – in a new ActiveSpan.
protected void	onSpanFinished(MockSpan mockSpan) Noop method called on Span.finish().
void	reset() Clear the finishedSpans() queue.

Methods inherited from class java.lang.Object

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

Constructor Detail

MockTracer

public MockTracer()

MockTracer

public MockTracer(ActiveSpanSource spanSource)

MockTracer

public MockTracer(ActiveSpanSource spanSource,
                  MockTracer.Propagator propagator)

MockTracer

public MockTracer(MockTracer.Propagator propagator)

Create a new MockTracer that passes through any calls to inject() and/or extract().

Method Detail

reset

public void reset()

Clear the finishedSpans() queue. Note that this does *not* have any effect on Spans created by MockTracer that have not finish()ed yet; those will still be enqueued in finishedSpans() when they finish().

finishedSpans

public List<MockSpan> finishedSpans()

Returns:

a copy of all finish()ed MockSpans started by this MockTracer (since construction or the last call to MockTracer.reset()).

See Also:

reset()

onSpanFinished

protected void onSpanFinished(MockSpan mockSpan)

Noop method called on Span.finish().

activeSpan

public ActiveSpan activeSpan()

Description copied from interface: ActiveSpanSource

Return the active span. This does not affect the internal reference count for the ActiveSpan.

If there is an active span, it becomes an implicit parent of any newly-created span at Tracer.SpanBuilder.startActive() time (rather than at Tracer.buildSpan(String) time).

Specified by:

activeSpan in interface ActiveSpanSource

Returns:

the active span, or null if none could be found.

makeActive

public ActiveSpan makeActive(Span span)

Description copied from interface: ActiveSpanSource

Wrap and "make active" a Span by encapsulating it – and any active state (e.g., MDC state) in the current thread – in a new ActiveSpan.

Specified by:

makeActive in interface ActiveSpanSource

Parameters:

span - the Span to wrap in an ActiveSpan

Returns:

an ActiveSpan that encapsulates the given Span and any other ActiveSpanSource-specific context (e.g., the MDC context map)

buildSpan

public MockTracer.SpanBuilder buildSpan(String operationName)

Description copied from interface: Tracer

Return a new SpanBuilder for a Span with the given `operationName`.

You can override the operationName later via BaseSpan.setOperationName(String).

A contrived example:

   Tracer tracer = ...

   // Note: if there is a `tracer.activeSpan()`, it will be used as the target of an implicit CHILD_OF
   // Reference for "workSpan" when `startActive()` is invoked.
   try (ActiveSpan workSpan = tracer.buildSpan("DoWork").startActive()) {
       workSpan.setTag("...", "...");
       // etc, etc
   }

   // It's also possible to create Spans manually, bypassing the ActiveSpanSource activation.
   Span http = tracer.buildSpan("HandleHTTPRequest")
                     .asChildOf(rpcSpanContext)  // an explicit parent
                     .withTag("user_agent", req.UserAgent)
                     .withTag("lucky_number", 42)
                     .startManual();
 

Specified by:

buildSpan in interface Tracer

inject

public <C> void inject(SpanContext spanContext,
                       Format<C> format,
                       C carrier)

Description copied from interface: Tracer

Inject a SpanContext into a `carrier` of a given type, presumably for propagation across process boundaries.

Example:

 Tracer tracer = ...
 Span clientSpan = ...
 TextMap httpHeadersCarrier = new AnHttpHeaderCarrier(httpRequest);
 tracer.inject(span.context(), Format.Builtin.HTTP_HEADERS, httpHeadersCarrier);
 

Specified by:

inject in interface Tracer

Type Parameters:

C - the carrier type, which also parametrizes the Format.

Parameters:

spanContext - the SpanContext instance to inject into the carrier

format - the Format of the carrier

carrier - the carrier for the SpanContext state. All Tracer.inject() implementations must support io.opentracing.propagation.TextMap and java.nio.ByteBuffer.

See Also:

Format, Format.Builtin

extract

public <C> SpanContext extract(Format<C> format,
                               C carrier)

Description copied from interface: Tracer

Extract a SpanContext from a `carrier` of a given type, presumably after propagation across a process boundary.

Example:

 Tracer tracer = ...
 TextMap httpHeadersCarrier = new AnHttpHeaderCarrier(httpRequest);
 SpanContext spanCtx = tracer.extract(Format.Builtin.HTTP_HEADERS, httpHeadersCarrier);
 ... = tracer.buildSpan('...').asChildOf(spanCtx).startActive();
 

If the span serialized state is invalid (corrupt, wrong version, etc) inside the carrier this will result in an IllegalArgumentException.

Specified by:

extract in interface Tracer

Type Parameters:

C - the carrier type, which also parametrizes the Format.

Parameters:

format - the Format of the carrier

carrier - the carrier for the SpanContext state. All Tracer.extract() implementations must support io.opentracing.propagation.TextMap and java.nio.ByteBuffer.

Returns:

the SpanContext instance holding context to create a Span.

See Also:

Format, Format.Builtin