| Copyright | (c) Ian Duncan 2021 |
|---|---|
| License | BSD-3 |
| Maintainer | Ian Duncan |
| Stability | experimental |
| Portability | non-portable (GHC extensions) |
| Safe Haskell | None |
| Language | Haskell2010 |
OpenTelemetry.Trace.Sampler
Description
This module provides several built-in sampling strategies, as well as the ability to define custom samplers.
Sampling is the concept of selecting a few elements from a large collection and learning about the entire collection by extrapolating from the selected set. It's widely used throughout the world whenever trying to tackle a problem of scale: for example, a survey assumes that by asking a small group of people a set of questions, you can learn something about the opinions of the entire populace.
While it's nice to believe that every event is precious, the reality of monitoring high volume production infrastructure is that there are some attributes to events that make them more interesting than the rest. Failures are often more interesting than successes! Rare events are more interesting than common events! Capturing some traffic from all customers can be better than capturing all traffic from some customers.
Sampling as a basic technique for instrumentation is no different. By recording information about a representative subset of requests flowing through a system, you can learn about the overall performance of the system. And as with surveys and air monitoring, the way you choose your representative set (the sample set) can greatly influence the accuracy of your results.
Sampling is widespread in observability systems because it lowers the cost of producing, collecting, and analyzing data in systems anywhere cost is a concern. Developers and operators in an observability system apply or attach key=value properties to observability data, spans and metrics, and we use these properties to investigate hypotheses about our systems after the fact. It is interesting to look at how sampling impacts our ability to analyze observability data, using key=value restrictions for some keys and grouping the output based on other keys.
Sampling schemes let observability systems collect examples of data that are not merely exemplary, but also representative. Sampling schemes compute a set of representative items and, in doing so, score each item with what is commonly called the item's "sampling rate." A sampling rate of 10 indicates that the item represents an estimated 10 individuals in the original data set.
Synopsis
- data Sampler
- data SamplingResult
- data SamplingDecision = SamplingDecision {}
- data ParentBasedOptions = ParentBasedOptions {}
- shouldSample :: Sampler -> Context -> TraceId -> Text -> SpanArguments -> InstrumentationLibrary -> IO SamplingDecision
- getDescription :: Sampler -> Text
- alwaysOn :: Sampler
- alwaysOff :: Sampler
- traceIdRatioBased :: Double -> Sampler
- parentBased :: ParentBasedOptions -> Sampler
- parentBasedOptions :: Sampler -> ParentBasedOptions
- alwaysRecord :: Sampler -> Sampler
Types
Samplers control whether a span is recorded and/or sampled.
The built-in constructors cover the standard OTel samplers. Custom
samplers use the CustomSampler fallback.
Spec: https://opentelemetry.io/docs/specs/otel/trace/sdk/#sampler
Since: 0.0.1.0
Constructors
| AlwaysOnSampler | Always returns |
| AlwaysOffSampler | Always returns |
| TraceIdRatioSampler !Double !Word64 !Attribute | Sample based on the lower 63 bits of the trace ID (bytes 8-15). Fields: clamped fraction, precomputed upper bound, precomputed sampleRate attribute. |
| ParentBasedSampler !ParentBasedOptions | Delegates to child samplers depending on whether the parent span is remotelocal and sampledunsampled. |
| AlwaysRecordSampler !Sampler | Wraps another sampler, upgrading |
| CustomSampler !Text !(Context -> TraceId -> Text -> SpanArguments -> InstrumentationLibrary -> IO SamplingDecision) | Escape hatch for user-defined samplers.
The |
data SamplingResult Source #
The outcome of a call to shouldSample indicating
whether the Tracer should sample a Span.
Since: 0.0.1.0
Constructors
| Drop | isRecording == false. Span will not be recorded and all events and attributes will be dropped. |
| RecordOnly | isRecording == true, but Sampled flag MUST NOT be set. |
| RecordAndSample | isRecording == true, AND Sampled flag MUST be set. |
Instances
| Show SamplingResult Source # | |
Defined in OpenTelemetry.Internal.Trace.Types Methods showsPrec :: Int -> SamplingResult -> ShowS # show :: SamplingResult -> String # showList :: [SamplingResult] -> ShowS # | |
| Eq SamplingResult Source # | |
Defined in OpenTelemetry.Internal.Trace.Types Methods (==) :: SamplingResult -> SamplingResult -> Bool # (/=) :: SamplingResult -> SamplingResult -> Bool # | |
data SamplingDecision Source #
The result of sampling, with strict fields for unboxing.
Replaces the (SamplingResult, AttributeMap, TraceState) tuple so GHC
can unbox through strict fields rather than boxing a 3-tuple.
Since: 0.0.1.0
Constructors
| SamplingDecision | |
Fields | |
data ParentBasedOptions Source #
Options for ParentBasedSampler. Each field designates which sampler
to delegate to depending on the parent span's state.
Since: 0.0.1.0
Constructors
| ParentBasedOptions | |
Fields
| |
Running samplers
shouldSample :: Sampler -> Context -> TraceId -> Text -> SpanArguments -> InstrumentationLibrary -> IO SamplingDecision Source #
Execute the sampling decision for a Sampler.
The InstrumentationLibrary parameter is the instrumentation scope of the
Tracer creating the span, as required by the spec.
Spec: https://opentelemetry.io/docs/specs/otel/trace/sdk/#shouldsample
Non-recursive wrapper handles the two most common leaf samplers (AlwaysOn / AlwaysOff) inline.
Since: 0.0.1.0
getDescription :: Sampler -> Text Source #
Get the sampler's description string.
Since: 0.0.1.0
Built-in samplers
Returns RecordAndSample always.
Description returns AlwaysOnSampler.
Since: 0.1.0.0
Returns Drop always.
Description returns AlwaysOffSampler.
Since: 0.1.0.0
traceIdRatioBased :: Double -> Sampler Source #
The TraceIdRatioBased ignores the parent SampledFlag. To respect the parent SampledFlag,
the TraceIdRatioBased should be used as a delegate of the parentBased sampler specified below.
Description returns a string of the form "TraceIdRatioBased{RATIO}" with RATIO replaced with the Sampler instance's trace sampling ratio represented as a decimal number.
Since: 0.1.0.0
parentBased :: ParentBasedOptions -> Sampler Source #
A sampler which behaves differently based on the incoming sampling decision.
In general, this will sample spans that have parents that were sampled, and will not sample spans whose parents were not sampled.
Since: 0.1.0.0
Arguments
| :: Sampler | Root sampler |
| -> ParentBasedOptions |
This is a composite sampler. ParentBased helps distinguish between the following cases:
No parent (root span).
Remote parent (SpanContext.IsRemote() == true) with SampledFlag equals true
Remote parent (SpanContext.IsRemote() == true) with SampledFlag equals false
Local parent (SpanContext.IsRemote() == false) with SampledFlag equals true
Local parent (SpanContext.IsRemote() == false) with SampledFlag equals false
A smart constructor for ParentBasedOptions with reasonable starting
defaults.
Since: 0.1.0.0
alwaysRecord :: Sampler -> Sampler Source #
A decorator that ensures spans always reach processors (IsRecording=true) even when the wrapped sampler would DROP them. Per spec:
- DROP -> RECORD_ONLY (upgraded: processors see it, exporters don't)
- RECORD_ONLY -> RECORD_ONLY (unchanged)
- RECORD_AND_SAMPLE -> RECORD_AND_SAMPLE (unchanged)
Useful for span-to-metrics processors or debugging processors that need visibility into all spans without increasing export volume.
Since: 0.2.0.0