tailsamplingprocessor

README

Tail Sampling Processor

Supported pipeline types: traces

The tail sampling processor samples traces based on a set of defined policies. Today, this processor only works with a single instance of the collector. Technically, trace ID aware load balancing could be used to support multiple collector instances, but this configuration has not been tested. Please refer to config.go for the config spec.

The following configuration options are required:

• policies (no default): Policies used to make a sampling decision

Multiple policies exist today and it is straight forward to add more. These include:

• always_sample: Sample all traces
• numeric_attribute: Sample based on number attributes
• string_attribute: Sample based on string attributes
• rate_limiting: Sample based on rate

The following configuration options can also be modified:

• decision_wait (default = 30s): Wait time since the first span of a trace before making a sampling decision
• num_traces (default = 50000): Number of traces kept in memory
• expected_new_traces_per_sec (default = 0): Expected number of new traces (helps in allocating data structures)

Examples:

processors:
  tail_sampling:
    decision_wait: 10s
    num_traces: 100
    expected_new_traces_per_sec: 10
    policies:
      [
          {
            name: test-policy-1,
            type: always_sample
          },
          {
            name: test-policy-2,
            type: numeric_attribute,
            numeric_attribute: {key: key1, min_value: 50, max_value: 100}
          },
          {
            name: test-policy-3,
            type: string_attribute,
            string_attribute: {key: key2, values: [value1, value2]}
          },
          {
            name: test-policy-4,
            type: rate_limiting,
            rate_limiting: {spans_per_second: 35}
         }
      ]

Refer to tail_sampling_config.yaml for detailed examples on using the processor.

Documentation

Index

• func SamplingProcessorMetricViews(level telemetry.Level) []*view.View
• type Config
• type Factory
  • func (f *Factory) CreateDefaultConfig() configmodels.Processor
  • func (f *Factory) CreateMetricsProcessor(logger *zap.Logger, nextConsumer consumer.MetricsConsumerOld, ...) (component.MetricsProcessorOld, error)
  • func (f *Factory) CreateTraceProcessor(logger *zap.Logger, nextConsumer consumer.TraceConsumerOld, ...) (component.TraceProcessorOld, error)
  • func (f *Factory) Type() configmodels.Type
• type NumericAttributeCfg
• type Policy
• type PolicyCfg
• type PolicyType
• type RateLimitingCfg
• type StringAttributeCfg

Functions

func SamplingProcessorMetricViews

func SamplingProcessorMetricViews(level telemetry.Level) []*view.View

SamplingProcessorMetricViews return the metrics views according to given telemetry level.

Types

type Config

type Config struct {
	configmodels.ProcessorSettings `mapstructure:",squash"`
	// DecisionWait is the desired wait time from the arrival of the first span of
	// trace until the decision about sampling it or not is evaluated.
	DecisionWait time.Duration `mapstructure:"decision_wait"`
	// NumTraces is the number of traces kept on memory. Typically most of the data
	// of a trace is released after a sampling decision is taken.
	NumTraces uint64 `mapstructure:"num_traces"`
	// ExpectedNewTracesPerSec sets the expected number of new traces sending to the tail sampling processor
	// per second. This helps with allocating data structures with closer to actual usage size.
	ExpectedNewTracesPerSec uint64 `mapstructure:"expected_new_traces_per_sec"`
	// PolicyCfgs sets the tail-based sampling policy which makes a sampling decision
	// for a given trace when requested.
	PolicyCfgs []PolicyCfg `mapstructure:"policies"`
}

Config holds the configuration for tail-based sampling.

type Factory

type Factory struct {
}

Factory is the factory for Tail Sampling processor.

func (*Factory) CreateDefaultConfig

func (f *Factory) CreateDefaultConfig() configmodels.Processor

CreateDefaultConfig creates the default configuration for processor.

func (*Factory) CreateMetricsProcessor

func (f *Factory) CreateMetricsProcessor(
	logger *zap.Logger,
	nextConsumer consumer.MetricsConsumerOld,
	cfg configmodels.Processor,
) (component.MetricsProcessorOld, error)

CreateMetricsProcessor creates a metrics processor based on this config.

func (*Factory) CreateTraceProcessor

func (f *Factory) CreateTraceProcessor(
	logger *zap.Logger,
	nextConsumer consumer.TraceConsumerOld,
	cfg configmodels.Processor,
) (component.TraceProcessorOld, error)

CreateTraceProcessor creates a trace processor based on this config.

func (*Factory) Type

func (f *Factory) Type() configmodels.Type

Type gets the type of the config created by this factory.

type NumericAttributeCfg

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

NumericAttributeCfg holds the configurable settings to create a numeric attribute filter sampling policy evaluator.

type Policy

type Policy struct {
	// Name used to identify this policy instance.
	Name string
	// Evaluator that decides if a trace is sampled or not by this policy instance.
	Evaluator sampling.PolicyEvaluator
	// contains filtered or unexported fields
}

Policy combines a sampling policy evaluator with the destinations to be used for that policy.

type PolicyCfg

type PolicyCfg struct {
	// Name given to the instance of the policy to make easy to identify it in metrics and logs.
	Name string `mapstructure:"name"`
	// Type of the policy this will be used to match the proper configuration of the policy.
	Type PolicyType `mapstructure:"type"`
	// Configs for numeric attribute filter sampling policy evaluator.
	NumericAttributeCfg NumericAttributeCfg `mapstructure:"numeric_attribute"`
	// Configs for string attribute filter sampling policy evaluator.
	StringAttributeCfg StringAttributeCfg `mapstructure:"string_attribute"`
	// Configs for rate limiting filter sampling policy evaluator.
	RateLimitingCfg RateLimitingCfg `mapstructure:"rate_limiting"`
}

PolicyCfg holds the common configuration to all policies.

type PolicyType

type PolicyType string

PolicyType indicates the type of sampling policy.

const (
	// AlwaysSample samples all traces, typically used for debugging.
	AlwaysSample PolicyType = "always_sample"
	// NumericAttribute sample traces that have a given numeric attribute in a specified
	// range, e.g.: attribute "http.status_code" >= 399 and <= 999.
	NumericAttribute PolicyType = "numeric_attribute"
	// StringAttribute sample traces that a attribute, of type string, matching
	// one of the listed values.
	StringAttribute PolicyType = "string_attribute"
	// RateLimiting allows all traces until the specified limits are satisfied.
	RateLimiting PolicyType = "rate_limiting"
)

type RateLimitingCfg

type RateLimitingCfg struct {
	// SpansPerSecond sets the limit on the maximum nuber of spans that can be processed each second.
	SpansPerSecond int64 `mapstructure:"spans_per_second"`
}

RateLimitingCfg holds the configurable settings to create a rate limiting sampling policy evaluator.

type StringAttributeCfg

type StringAttributeCfg struct {
	// Tag that the filter is going to be matching against.
	Key string `mapstructure:"key"`
	// Values is the set of attribute values that if any is equal to the actual attribute value to be considered a match.
	Values []string `mapstructure:"values"`
}

StringAttributeCfg holds the configurable settings to create a string attribute filter sampling policy evaluator.