config.go

config.go - Overview

This file defines the configuration structures for the tail sampling functionality in the OpenTelemetry collector. It includes configurations for policies, probabilistic sampling, attribute-based filtering (numeric and string), and overall sampling behavior.

Detailed Documentation

PolicyType

type PolicyType string

• Purpose: PolicyType is a string type alias used to represent the type of a sampling policy.

Config

type Config struct {
	DecisionWait            time.Duration `mapstructure:"decision_wait" yaml:"decision_wait"`
	NumTraces               uint64        `mapstructure:"num_traces" yaml:"num_traces"`
	ExpectedNewTracesPerSec uint64        `mapstructure:"expected_new_traces_per_sec" yaml:"expected_new_traces_per_sec"`
	PolicyCfgs              []PolicyCfg   `mapstructure:"policies" yaml:"policies"`

	// read only version number (optional)
	Version int
}

• Purpose: Config defines the overall configuration for the tail sampling component.
  • DecisionWait: The amount of time to wait for a decision on a trace.
  • NumTraces: The number of traces to keep in memory.
  • ExpectedNewTracesPerSec: The expected number of new traces per second.
  • PolicyCfgs: A slice of PolicyCfg structs, representing the defined sampling policies.
  • Version: An optional read-only version number.
• Parameters: None
• Returns: None

ProbabilisticCfg

type ProbabilisticCfg struct {
	// HashSalt allows one to configure the hashing salts. This is important in scenarios where multiple layers of collectors
	// have different sampling rates: if they use the same salt all passing one layer may pass the other even if they have
	// different sampling rates, configuring different salts avoids that.
	HashSalt string `mapstructure:"hash_salt" yaml:"hash_salt"`
	// SamplingPercentage is the percentage rate at which traces are going to be sampled. Defaults to zero, i.e.: no sample.
	// Values greater or equal 100 are treated as "sample all traces".
	SamplingPercentage float64 `mapstructure:"sampling_percentage" yaml:"sampling_percentage"`
}

• Purpose: ProbabilisticCfg defines the configuration for probabilistic sampling.
  • HashSalt: A string used as a salt for hashing, useful when multiple collectors with different sampling rates are used.
  • SamplingPercentage: The percentage of traces to be sampled. A value of 0 means no sampling, and values >= 100 mean all traces are sampled.
• Parameters: None
• Returns: None

NumericAttributeCfg

type NumericAttributeCfg struct {
	// Tag that the filter is going to be matching against.
	Key string `mapstructure:"key" yaml:"key"`
	// MinValue is the minimum value of the attribute to be considered a match.
	MinValue int64 `mapstructure:"min_value" yaml:"min_value"`
	// MaxValue is the maximum value of the attribute to be considered a match.
	MaxValue int64 `mapstructure:"max_value" yaml:"max_value"`
}

• Purpose: NumericAttributeCfg defines the configuration for filtering based on numeric attributes.
  • Key: The attribute key to match against.
  • MinValue: The minimum value for a match.
  • MaxValue: The maximum value for a match.
• Parameters: None
• Returns: None

StringAttributeCfg

type StringAttributeCfg struct {
	// Tag that the filter is going to be matching against.
	Key string `mapstructure:"key" yaml:"key"`
	// Values indicate the set of values or regular expressions to use when matching against attribute values.
	// StringAttribute Policy will apply exact value match on Values unless EnabledRegexMatching is true.
	Values []string `mapstructure:"values" yaml:"values"`
	// EnabledRegexMatching determines whether match attribute values by regexp string.
	EnabledRegexMatching bool `mapstructure:"enabled_regex_matching" yaml:"enabled_regex_matching"`
	// CacheMaxSize is the maximum number of attribute entries of LRU Cache that stores the matched result
	// from the regular expressions defined in Values.
	// CacheMaxSize will not be used if EnabledRegexMatching is set to false.
	CacheMaxSize int `mapstructure:"cache_max_size" yaml:"cache_max_size"`
	// InvertMatch indicates that values or regular expressions must not match against attribute values.
	// If InvertMatch is true and Values is equal to 'acme', all other values will be sampled except 'acme'.
	// Also, if the specified Key does not match on any resource or span attributes, data will be sampled.
	InvertMatch bool `mapstructure:"invert_match" yaml:"invert_match"`
}

• Purpose: StringAttributeCfg defines the configuration for filtering based on string attributes.
  • Key: The attribute key to match against.
  • Values: A list of string values or regular expressions to match.
  • EnabledRegexMatching: A boolean indicating whether to use regular expression matching.
  • CacheMaxSize: The maximum size of the LRU cache for regex matching results. Only used when EnabledRegexMatching is true.
  • InvertMatch: If true, the policy will match if the attribute value does not match the provided values/regexes.
• Parameters: None
• Returns: None

PolicyFilterCfg

type PolicyFilterCfg struct {
	// values: AND | OR
	FilterOp string `mapstructure:"filter_op" yaml:"filter_op"`

	StringAttributeCfgs  []StringAttributeCfg  `mapstructure:"string_attributes" yaml:"string_attributes"`
	NumericAttributeCfgs []NumericAttributeCfg `mapstructure:"numeric_attributes" yaml:"numeric_attributes"`
}

• Purpose: PolicyFilterCfg defines the configuration for a policy filter, allowing combinations of string and numeric attribute filters.
  • FilterOp: The operator to use when combining filters ("AND" or "OR").
  • StringAttributeCfgs: A list of StringAttributeCfg structs.
  • NumericAttributeCfgs: A list of NumericAttributeCfg structs.
• Parameters: None
• Returns: None

PolicyCfg

type PolicyCfg struct {
	// name of the policy
	Name string `mapstructure:"name" yaml:"name"`

	// Type of the policy this will be used to match the proper configuration of the policy.
	Type PolicyType `mapstructure:"type" yaml:"type"`

	// Set to true for sampling rule (root) and false for conditions
	Root bool `mapstructure:"root" yaml:"root"`

	Priority int `mapstructure:"priority" yaml:"priority"`

	// sampling applied when  PolicyFilter matches
	ProbabilisticCfg `mapstructure:",squash" yaml:"sampling"`

	// filter to activate policy
	PolicyFilterCfg `mapstructure:",squash" yaml:"policy_filter"`

	SubPolicies []PolicyCfg `mapstructure:"sub_policies" yaml:"sub_policies"`
}

• Purpose: PolicyCfg defines the configuration for a sampling policy.
  • Name: The name of the policy.
  • Type: The type of the policy.
  • Root: Indicates whether this is a root sampling rule (true) or a condition (false).
  • Priority: The priority of the policy.
  • ProbabilisticCfg: The configuration for probabilistic sampling to apply if the filter matches.
  • PolicyFilterCfg: The filter configuration to activate the policy.
  • SubPolicies: A list of sub-policies.
• Parameters: None
• Returns: None

Include in Getting Started: NO