Class ExemplarSampler

Object

ExemplarSampler

@StableApi
public class ExemplarSampler
extends Object

The ExemplarSampler selects Spans as exemplars.

There are two types of Exemplars: Regular exemplars are sampled implicitly if a supported tracing library is detected. Custom exemplars are provided explicitly in code, for example if a developer wants to make sure an Exemplar is created for a specific code path.

Spans will be marked as being an Exemplar by calling SpanContext.markCurrentSpanAsExemplar(). The tracer implementation should set a Span attribute to mark the current Span as an Exemplar. This attribute can be used by a trace sampling algorithm to make sure traces with Exemplars are sampled.

The ExemplarSample is rate-limited, so only a small fraction of Spans will be marked as Exemplars in an application with a large number of requests.

See ExemplarSamplerConfig for configuration options.

Constructor Summary

Constructors

Constructor	Description
ExemplarSampler(ExemplarSamplerConfig config)
ExemplarSampler(ExemplarSamplerConfig config, SpanContext spanContext)	Constructor with an additional {code spanContext} argument.
ExemplarSampler(ExemplarSamplerConfig config, SpanContext spanContext, Supplier<Labels> additionalLabelsSupplier)	Constructor that additionally accepts a supplier of labels to be merged into every automatically-sampled exemplar.

Method Summary

Modifier and Type	Method	Description
Exemplars	collect()
void	observe(double value)
void	observeWithExemplar(double value, Labels labels)
void	reset()

Methods inherited from class Object

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

Constructor Details

ExemplarSampler

public ExemplarSampler(ExemplarSamplerConfig config)

ExemplarSampler

public ExemplarSampler(ExemplarSamplerConfig config,
 @Nullable
 SpanContext spanContext)

Constructor with an additional {code spanContext} argument. This is useful for testing, but may also be useful in some production scenarios. If spanContext != null that spanContext is used and SpanContextSupplier is not used. If spanContext == null SpanContextSupplier.getSpanContext() is called to find a span context.

ExemplarSampler

public ExemplarSampler(ExemplarSamplerConfig config,
 @Nullable
 SpanContext spanContext,
 @Nullable
 Supplier<Labels> additionalLabelsSupplier)

Constructor that additionally accepts a supplier of labels to be merged into every automatically-sampled exemplar. The supplier is called each time an exemplar is sampled from a span context, so it can return dynamic values (e.g. a request-scoped identifier). The supplier is only called when a valid, sampled span context is present.

Method Details

collect

public Exemplars collect()

reset

public void reset()

observe

public void observe(double value)

observeWithExemplar

public void observeWithExemplar(double value,
 Labels labels)