Package brave.sampler

Class DeclarativeSampler<M>

java.lang.Object

brave.sampler.DeclarativeSampler<M>

Type Parameters:

M - The type that uniquely identifies this method, specifically for tracing. Most often a trace annotation, but could also be a Method or another declarative reference such as javax.ws.rs.container.ResourceInfo.

public final class DeclarativeSampler<M>
extends Object

This is an implementation of how to decide whether to trace a request using annotations on a java method. It is not an implementation of aspect-oriented or otherwise declarative tracing. See the test cases for this class for example implementations.

Example: A user defines an annotation, for example com.myco.Traced, and a lookup function for its rate (could be simple as reading a field, or even a constant). An interceptor uses this sampler on each invocation of a potentially annotated target. The result decides whether a new trace should be started or not.

No runtime parameters are considered here, but that doesn't mean you can't achieve parameterized sampling using this. If your method is annotated such that it only accepts a fraction of requests, adding a custom @Traced annotation would apply to that subset. For example, if you have a JAX-RS method, it is already qualified by method and likely path. A user can add and inspect their own grouping annotation to override whatever the default rate is.

Under the scenes, a map of samplers by method is maintained. The size of this map should not be a problem when it directly relates to declared methods. For example, this would be invalid if annotations were created at runtime and didn't match.

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static interface	DeclarativeSampler.RateForMethod<M>

Method Summary

Modifier and Type	Method	Description
static <M> DeclarativeSampler<M>	create(DeclarativeSampler.RateForMethod<M> rateForMethod)
SamplingFlags	sample(M method)
Sampler	toSampler(M method)	Used with Tracer.withSampler(Sampler) to override the default sampling decision.
Sampler	toSampler(M method, Sampler fallback)	Like toSampler(Object), except allows a fallback decision, usually from Tracing.sampler(), when there was no rate for an input

Methods inherited from class java.lang.Object

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

Method Detail

create

public static <M> DeclarativeSampler<M> create(DeclarativeSampler.RateForMethod<M> rateForMethod)

toSampler

public Sampler toSampler(M method)

Used with Tracer.withSampler(Sampler) to override the default sampling decision.

Ex:

 // When there is no trace in progress, this decides using an annotation
 Sampler decideUsingAnnotation = declarativeSampler.toSampler(traced);
 Tracer tracer = tracing.tracer().withSampler(decideUsingAnnotation);

 // This code looks the same as if there was no declarative override
 Span span = tracer.nextSpan().name(name).start();
 

Parameters:

method - input to the sampling function

Returns:

false if there was no rate associated with the input

toSampler

public Sampler toSampler(M method,
                         Sampler fallback)

Like toSampler(Object), except allows a fallback decision, usually from Tracing.sampler(), when there was no rate for an input

Ex:

 // When there is no trace in progress, this decides using an annotation
 Sampler decideUsingAnnotation = declarativeSampler.toSampler(traced, tracing.sampler());
 Tracer tracer = tracing.tracer().withSampler(decideUsingAnnotation);

 // This code looks the same as if there was no declarative override
 brave.Span span = tracer.nextSpan().name("").start();
 

Parameters:

method - input to the sampling function

fallback - when there is no rate for the input, usually Tracing.sampler()

sample

public SamplingFlags sample(@Nullable
                            M method)