samplingrules

Documentation

Overview

Package samplingrules defines the types and parsing logic for trace and span sampling rules. It is shared between ddtrace/tracer (runtime sampling) and internal/config (configuration ownership).

Index

• func EqualsFalseNegative(a, b []SamplingRule) bool
• func GlobMatch(pattern string) *regexp.Regexp
• func GlobsToRegexps(globs map[string]string) map[string]*regexp.Regexp
• func RegexEqualsFalseNegative(a, b *regexp.Regexp) bool
• type Provenance
  • func (p Provenance) MarshalJSON() ([]byte, error)
  • func (p Provenance) String() string
  • func (p *Provenance) UnmarshalJSON(data []byte) error
• type RateLimiter
  • func NewRateLimiter(ratePerSecond float64) *RateLimiter
  • func NewSingleSpanRateLimiter(mps float64) *RateLimiter
  • func (r *RateLimiter) AllowOne(now time.Time) (bool, float64)
  • func (r *RateLimiter) Limit() float64
• type Rule
• type SamplingRule
  • func NewRCSamplingRule(service, name, resource string, rate float64, prov Provenance, ...) SamplingRule
  • func SpanSamplingRules(rules ...Rule) []SamplingRule
  • func SplitByType(rules []SamplingRule) (trace, span []SamplingRule)
  • func TraceSamplingRules(rules ...Rule) []SamplingRule
  • func UnmarshalSamplingRules(b []byte, spanType SamplingRuleType) ([]SamplingRule, error)
  • func (sr *SamplingRule) AllowOne(now time.Time) (bool, float64)
  • func (sr *SamplingRule) EqualsFalseNegative(other *SamplingRule) bool
  • func (sr SamplingRule) MarshalJSON() ([]byte, error)
  • func (sr *SamplingRule) RuleType() SamplingRuleType
  • func (sr SamplingRule) String() string
  • func (sr *SamplingRule) UnmarshalJSON(b []byte) error
• type SamplingRuleType
  • func (sr SamplingRuleType) String() string

Functions

func EqualsFalseNegative

func EqualsFalseNegative(a, b []SamplingRule) bool

EqualsFalseNegative tests whether two slices of SamplingRules are the same. The result may be false negative: true guarantees equality.

func GlobMatch

func GlobMatch(pattern string) *regexp.Regexp

GlobMatch compiles a glob pattern into a regexp. Returns nil for "" or "*".

func GlobsToRegexps

func GlobsToRegexps(globs map[string]string) map[string]*regexp.Regexp

GlobsToRegexps compiles a map of glob-pattern strings to regexp patterns.

func RegexEqualsFalseNegative

func RegexEqualsFalseNegative(a, b *regexp.Regexp) bool

RegexEqualsFalseNegative reports whether two regexp patterns have the same string representation. True guarantees equality; false may be a false negative.

Types

type Provenance

type Provenance int32

Provenance describes the source of a sampling rule received via Remote Config.

const (
	Local    Provenance = 0
	Customer Provenance = 1
	Dynamic  Provenance = 2
)

func (Provenance) MarshalJSON

func (p Provenance) MarshalJSON() ([]byte, error)

func (Provenance) String

func (p Provenance) String() string

func (*Provenance) UnmarshalJSON

func (p *Provenance) UnmarshalJSON(data []byte) error

type RateLimiter

type RateLimiter struct {
	Limiter *rate.Limiter

	PrevTime    time.Time // +checklocks:mu
	Allowed     float64   // +checklocks:mu
	Seen        float64   // +checklocks:mu
	PrevAllowed float64   // +checklocks:mu
	PrevSeen    float64   // +checklocks:mu
	// contains filtered or unexported fields
}

RateLimiter is a token-bucket rate limiter that also tracks the effective allowance rate over the previous and current second.

func NewRateLimiter

func NewRateLimiter(ratePerSecond float64) *RateLimiter

NewRateLimiter returns a RateLimiter capped at ratePerSecond events.

func NewSingleSpanRateLimiter

func NewSingleSpanRateLimiter(mps float64) *RateLimiter

NewSingleSpanRateLimiter returns a RateLimiter for per-rule span rate limiting. A zero or negative mps means unlimited.

func (*RateLimiter) AllowOne

func (r *RateLimiter) AllowOne(now time.Time) (bool, float64)

AllowOne returns whether a single event is allowed and the effective rate.

func (*RateLimiter) Limit

func (r *RateLimiter) Limit() float64

Limit returns the configured rate limit in events per second.

type Rule

type Rule struct {
	ServiceGlob  string
	NameGlob     string
	ResourceGlob string
	Tags         map[string]string
	Rate         float64
	MaxPerSecond float64
}

Rule is used to create a SamplingRule via TraceSamplingRules or SpanSamplingRules.

type SamplingRule

type SamplingRule struct {
	// Service specifies the regex pattern that a span service name must match.
	Service *regexp.Regexp

	// Name specifies the regex pattern that a span operation name must match.
	Name *regexp.Regexp

	// Rate specifies the sampling rate that should be applied to spans that match
	// service and/or name of the rule.
	Rate float64

	// MaxPerSecond specifies max number of spans per second that can be sampled per the rule.
	// If not specified, the default is no limit.
	MaxPerSecond float64

	// Resource specifies the regex pattern that a span resource must match.
	Resource *regexp.Regexp

	// Tags specifies the map of key-value patterns that span tags must match.
	Tags map[string]*regexp.Regexp

	Provenance Provenance
	// contains filtered or unexported fields
}

SamplingRule is used for applying sampling rates to spans that match the service name, operation name or both. For basic usage, consider using the helper functions TraceSamplingRules and SpanSamplingRules.

func NewRCSamplingRule

func NewRCSamplingRule(service, name, resource string, rate float64, prov Provenance, tagGlobs map[string]*regexp.Regexp, tagStrs map[string]string) SamplingRule

NewRCSamplingRule constructs a SamplingRule from a Remote Config update. tagGlobs maps tag keys to pre-compiled regexp patterns; tagStrs preserves the original glob strings for JSON serialisation. Pass nil tagStrs to omit tags.

func SpanSamplingRules

func SpanSamplingRules(rules ...Rule) []SamplingRule

SpanSamplingRules creates sampling rules that apply to individual spans without affecting the trace sampling decision.

func SplitByType

func SplitByType(rules []SamplingRule) (trace, span []SamplingRule)

SplitByType partitions a mixed slice of rules into trace rules and span rules.

func TraceSamplingRules

func TraceSamplingRules(rules ...Rule) []SamplingRule

TraceSamplingRules creates sampling rules that apply to the entire trace if any spans satisfy the criteria.

func UnmarshalSamplingRules

func UnmarshalSamplingRules(b []byte, spanType SamplingRuleType) ([]SamplingRule, error)

UnmarshalSamplingRules parses JSON sampling rules of the given type. On error, any rules that parsed successfully are still returned alongside the error — callers should log the error and use the partial result.

func (*SamplingRule) AllowOne

func (sr *SamplingRule) AllowOne(now time.Time) (bool, float64)

AllowOne applies the per-rule rate limiter. Returns whether the span is allowed and the effective rate. If no limiter is set, it always allows.

func (*SamplingRule) EqualsFalseNegative

func (sr *SamplingRule) EqualsFalseNegative(other *SamplingRule) bool

EqualsFalseNegative compares two SamplingRules. The result may be false negative: true guarantees equality; false does not guarantee inequality.

func (SamplingRule) MarshalJSON

func (sr SamplingRule) MarshalJSON() ([]byte, error)

MarshalJSON implements json.Marshaler.

func (*SamplingRule) RuleType

func (sr *SamplingRule) RuleType() SamplingRuleType

RuleType returns the rule's type (trace or span).

func (SamplingRule) String

func (sr SamplingRule) String() string

func (*SamplingRule) UnmarshalJSON

func (sr *SamplingRule) UnmarshalJSON(b []byte) error

UnmarshalJSON implements json.Unmarshaler.

type SamplingRuleType

type SamplingRuleType int

SamplingRuleType represents a type of sampling rule spans are matched against.

const (
	SamplingRuleUndefined SamplingRuleType = 0
	SamplingRuleTrace     SamplingRuleType = 1
	SamplingRuleSpan      SamplingRuleType = 2
)

func (SamplingRuleType) String

func (sr SamplingRuleType) String() string