Categorygithub.com/open-telemetry/opentelemetry-collector-contrib/pkg/sampling
modulepackage
0.121.0
Repository: https://github.com/open-telemetry/opentelemetry-collector-contrib.git
Documentation: pkg.go.dev
Overview
Versions
1
Dependencies
9
Dependents
2
Files
667 SLOC

# README

pkg/sampling

Overview

This package contains utilities for parsing and interpreting the W3C TraceState and all sampling-relevant fields specified by OpenTelemetry that may be found in the OpenTelemetry section of the W3C TraceState.

This package implements the draft specification in OTEP 235, which specifies two fields used by the OpenTelemetry consistent probability sampling scheme.

These are:

  • th: the Threshold used to determine whether a TraceID is sampled
  • rv: an explicit randomness value, which overrides randomness in the TraceID

OTEP 235 contains details on how to interpret these fields. The are not meant to be human readable, with a few exceptions. The tracestate entry ot=th:0 indicates 100% sampling.

# Functions

NewOpenTelemetryTraceState returns a parsed representation of the OpenTelemetry tracestate section.
NewW3CTraceState parses a W3C trace state, with special attention to the embedded OpenTelemetry trace state field.
ProbabilityToThreshold converts a probability to a Threshold.
ProbabilityToThresholdWithPrecision is like ProbabilityToThreshold with support for reduced precision.
RValueToRandomness parses NumHexDigits hex bytes into a Randomness.
ThresholdGreater allows direct comparison of Threshold values.
ThresholdLessThan allows direct comparison of Threshold values.
TraceIDToRandomness returns randomness from a TraceID (assumes the traceparent random flag was set).
TValueToThreshold returns a Threshold.
UnsignedToRandomness constructs a randomness using 56 random bits of unsigned number.
UnsignedToThreshold constructs a threshold expressed in terms defined by number of rejections out of MaxAdjustedCount, which equals the number of randomness values.

# Constants

MaxAdjustedCount is 2^56 i.e.
MinSamplingProbability is the smallest representable probability and is the inverse of MaxAdjustedCount.
NumHexDigits is the number of hex digits equalling 56 bits.

# Variables

AllProbabilitiesRandomness is sampled at all probabilities.
AlwaysSampleThreshold represents 100% sampling.
ErrInconsistentSampling is returned when a sampler update is illogical, indicating that the tracestate was not modified.
ErrProbabilityRange is returned when a value should be in the range [1/MaxAdjustedCount, 1].
ErrRValueSize is returned by RValueToRandomess in case of unexpected size.
ErrTraceStateSize is returned when a TraceState is over its size limit, as specified by W3C.
ErrEmptyTValue indicates no t-value was found, i.e., no threshold available.
ErrTValueSize is returned for t-values longer than NumHexDigits hex digits.
NeverSampledThreshold is a threshold value that will always not sample.

# Structs

KV represents a key-value parsed from a section of the TraceState.
OpenTelemetryTraceState represents the `ot` section of the W3C tracestate which is specified generically in https://opentelemetry.io/docs/specs/otel/trace/tracestate-handling/.
Randomness may be derived from R-value or TraceID.
Threshold represents an exact sampling probability using 56 bits of precision.
W3CTraceState represents the a parsed W3C `tracestate` header.