Package brave.test

Class ITRemote

java.lang.Object

brave.test.ITRemote

@Timeout(value=20L,
         unit=MINUTES)
public abstract class ITRemote
extends Object

This is the base class for remote integration tests. It has a few features to ensure tests cover common instrumentation bugs. Most of this optimizes for instrumentation occurring on a different thread than main (which does the assertions).

   
StrictCurrentTraceContext double-checks threads don't leak contexts
   
IntegrationTestSpanHandler helps avoid race conditions or accidental errors
 

Timeout

We use a global rule instead of surefire config as this could be executed in gradle, sbt, etc. This way, there's visibility on which method hung without asking the end users to edit build config.

Normal tests will pass in less than 5 seconds. This timeout is set to 20 to be higher than needed even in an overloaded CI server or extreme garbage collection pause.

Field Summary

Fields

Modifier and Type	Field	Description
static BaggageField	BAGGAGE_FIELD
static String	BAGGAGE_FIELD_KEY	Sets a propagation key for BAGGAGE_FIELD, which can work with JMS (that prohibits the '-' character).
protected CurrentTraceContext	currentTraceContext
protected Propagation.Factory	propagationFactory
protected String	testName
protected IntegrationTestSpanHandler	testSpanHandler
protected Tracing	tracing

Constructor Summary

Constructors

Modifier	Constructor	Description
protected	ITRemote()

Method Summary

Modifier and Type	Method	Description
protected void	assertChildOf(MutableSpan child, MutableSpan parent)
protected void	assertChildOf(MutableSpan child, TraceContext parent)
protected void	assertChildOf(TraceContext child, TraceContext parent)
protected void	assertNoError(MutableSpan result)
protected void	assertNoErrorTag(MutableSpan result)
protected void	assertSameIds(MutableSpan span, TraceContext parent)	Useful for checking server spans when Tracing.Builder.supportsJoin(boolean).
protected void	assertSequential(MutableSpan span1, MutableSpan span2)	Ensures the first finished before the other started.
protected void	assertSpanInInterval(MutableSpan span, long startTimestamp, long finishTimestamp)	Ensures the inputs are parent and child, the parent starts before the child, and the duration of the child is inside the parent's duration.
protected void	checkForLeakedScopes()	Override to disable scope leak enforcement.
protected void	close()	This closes the current instance of tracing, to prevent it from being accidentally visible to other test classes which call Tracing.current().
protected CurrentTraceContext.Builder	currentTraceContextBuilder()	Subclass to override the builder.
protected TraceContext	newTraceContext(SamplingFlags flags)	Returns a trace context for use in propagation tests.
protected Tracing.Builder	tracingBuilder(Sampler sampler)

Methods inherited from class java.lang.Object

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

Field Detail

BAGGAGE_FIELD

public static final BaggageField BAGGAGE_FIELD

BAGGAGE_FIELD_KEY

public static final String BAGGAGE_FIELD_KEY

Sets a propagation key for BAGGAGE_FIELD, which can work with JMS (that prohibits the '-' character).

Note: If we didn't do this, it would be propagated all lowercase, ex "userid", which is harmless. We reset this for two reasons:

• Ensures BaggagePropagationConfig.SingleBaggageField.keyNames() are used on the wire, instead of BaggageField.name()
• Warn maintainers about JMS related naming choices.

See Also:

Constant Field Values

testSpanHandler

@RegisterExtension
protected IntegrationTestSpanHandler testSpanHandler

testName

protected String testName

currentTraceContext

protected final CurrentTraceContext currentTraceContext

propagationFactory

protected final Propagation.Factory propagationFactory

tracing

protected Tracing tracing

Constructor Detail

ITRemote

protected ITRemote()

Method Detail

newTraceContext

protected TraceContext newTraceContext(SamplingFlags flags)

Returns a trace context for use in propagation tests.

currentTraceContextBuilder

protected CurrentTraceContext.Builder currentTraceContextBuilder()

Subclass to override the builder. The result will have StrictScopeDecorator added

tracingBuilder

protected Tracing.Builder tracingBuilder(Sampler sampler)

close

@AfterEach
protected void close()
              throws Exception

This closes the current instance of tracing, to prevent it from being accidentally visible to other test classes which call Tracing.current().

This also checks for scope leaks. It is important that you have closed all resources prior to this method call. Otherwise, in-flight request cleanup may be mistaken for scope leaks. This may involve blocking on completion, if using executors.

Ex.

{@code

Throws:

Exception

checkForLeakedScopes

protected void checkForLeakedScopes()
                             throws IOException

Override to disable scope leak enforcement.

Throws:

IOException

assertSpanInInterval

protected void assertSpanInInterval(MutableSpan span,
                                    long startTimestamp,
                                    long finishTimestamp)

Ensures the inputs are parent and child, the parent starts before the child, and the duration of the child is inside the parent's duration.

assertSequential

protected void assertSequential(MutableSpan span1,
                                MutableSpan span2)

Ensures the first finished before the other started.

assertSameIds

protected void assertSameIds(MutableSpan span,
                             TraceContext parent)

Useful for checking server spans when Tracing.Builder.supportsJoin(boolean).

assertChildOf

protected void assertChildOf(TraceContext child,
                             TraceContext parent)

assertChildOf

protected void assertChildOf(MutableSpan child,
                             TraceContext parent)

assertChildOf

protected void assertChildOf(MutableSpan child,
                             MutableSpan parent)

assertNoError

protected void assertNoError(MutableSpan result)

assertNoErrorTag

protected void assertNoErrorTag(MutableSpan result)