Interface Sampler
@ThreadSafe
public interface Sampler
A Sampler is used to make decisions on
Span
sampling.-
Method Summary
Modifier and TypeMethodDescriptionstatic Sampler
static Sampler
alwaysOn()
Returns the description of thisSampler
.static Sampler
parentBased
(Sampler root) Returns aSampler
that always makes the same decision as the parentSpan
to whether or not to sample.static ParentBasedSamplerBuilder
parentBasedBuilder
(Sampler root) Returns aParentBasedSamplerBuilder
that enables configuration of the parent-based sampling strategy.shouldSample
(io.opentelemetry.context.Context parentContext, String traceId, String name, io.opentelemetry.api.trace.SpanKind spanKind, io.opentelemetry.api.common.Attributes attributes, List<LinkData> parentLinks) Called duringSpan
creation to make a sampling samplingResult.static Sampler
traceIdRatioBased
(double ratio) Returns a new TraceIdRatioBasedSampler
.
-
Method Details
-
alwaysOn
- Returns:
- a
Sampler
that always makes a "yes"SamplingResult
forSpan
sampling.
-
alwaysOff
- Returns:
- a
Sampler
that always makes a "no"SamplingResult
forSpan
sampling.
-
parentBased
Returns aSampler
that always makes the same decision as the parentSpan
to whether or not to sample. If there is no parent, the Sampler uses the provided Sampler delegate to determine the sampling decision.This method is equivalent to calling
#parentBasedBuilder(Sampler).build()
- Parameters:
root
- theSampler
which is used to make the sampling decisions if the parent does not exist.- Returns:
- a
Sampler
that follows the parent's sampling decision if one exists, otherwise following the root sampler's decision.
-
parentBasedBuilder
Returns aParentBasedSamplerBuilder
that enables configuration of the parent-based sampling strategy. The parent's sampling decision is used if a parent span exists, otherwise this strategy uses the root sampler's decision. There are a several options available on the builder to control the precise behavior of how the decision will be made.- Parameters:
root
- the requiredSampler
which is used to make the sampling decisions if the parent does not exist.- Returns:
- a
ParentBasedSamplerBuilder
-
traceIdRatioBased
Returns a new TraceIdRatioBasedSampler
. The ratio of sampling a trace is equal to that of the specified ratio.The algorithm used by the
Sampler
is undefined, notably it may or may not use parts of the trace ID when generating a sampling decision. Currently, only the ratio of traces that are sampled can be relied on, not how the sampled traces are determined. As such, it is recommended to only use thisSampler
for root spans usingparentBased(Sampler)
.- Parameters:
ratio
- The desired ratio of sampling. Must be within [0.0, 1.0].- Returns:
- a new TraceIdRatioBased
Sampler
. - Throws:
IllegalArgumentException
- ifratio
is out of range
-
shouldSample
SamplingResult shouldSample(io.opentelemetry.context.Context parentContext, String traceId, String name, io.opentelemetry.api.trace.SpanKind spanKind, io.opentelemetry.api.common.Attributes attributes, List<LinkData> parentLinks) Called duringSpan
creation to make a sampling samplingResult.- Parameters:
parentContext
- the parent span'sSpanContext
. This can beSpanContext.INVALID
if this is a root span.traceId
- theTraceId
for the newSpan
. This will be identical to that in the parentContext, unless this is a root span.name
- the name of the newSpan
.spanKind
- theSpanKind
of theSpan
.attributes
-Attributes
associated with the span.parentLinks
- the parentLinks associated with the newSpan
.- Returns:
- sampling samplingResult whether span should be sampled or not.
-
getDescription
String getDescription()Returns the description of thisSampler
. This may be displayed on debug pages or in the logs.Example: "TraceIdRatioBased{0.000100}"
- Returns:
- the description of this
Sampler
.
-