event

Documentation

Overview

Package event contains functionality related to APM event extraction from traces.

APM Events constitute the core of Datadog's Trace Search functionality. These are, in a nutshell, individual spans containing important information (but not full trace tree) about an execution and which can therefore be sampled at a different rate (retaining greater cardinality than that of complete traces). Furthermore, all information in APM events can be indexed, allowing for very flexible searching.

For instance, consider a web server. The top-level span on traces from this web server likely contains interesting things such as customer/user id, IPs, HTTP tags, HTTP endpoint, among others. By extracting this top level span from each trace, converting it into an APM event and feeding it into trace search, you can potentially search and aggregate this information for all requests arriving at your web server. You couldn't do the same thing with traces because these capture entire execution trees which are much more expensive to process and store and are therefore heavily sampled.

Of course, if the trace from which APM events were extracted also survives sampling, you can easily see the execution tree associated with a particular APM event as this link is kept throughout the entire processing pipeline.

Index

• type Extractor
  • func NewFixedRateExtractor(rateByServiceAndName map[string]map[string]float64) Extractor
  • func NewLegacyExtractor(rateByService map[string]float64) Extractor
  • func NewMetricBasedExtractor() Extractor
  • func NewNoopExtractor() Extractor
  • func NewSingleSpanExtractor() Extractor
• type Processor
  • func NewProcessor(extractors []Extractor, maxEPS float64) *Processor
  • func (p *Processor) Process(root *pb.Span, t *pb.TraceChunk) (numEvents, numExtracted int64)
  • func (p *Processor) Start()
  • func (p *Processor) Stop()

Types

type Extractor

type Extractor interface {
	// Extract decides whether to extract an APM event from the provided span with the specified priority and returns
	// a suggested extraction sample rate and a bool value. If no event was extracted the bool value will be false and
	// the rate should not be used.
	Extract(span *pb.Span, priority sampler.SamplingPriority) (rate float64, ok bool)
}

Extractor extracts APM events from matching spans.

func NewFixedRateExtractor

func NewFixedRateExtractor(rateByServiceAndName map[string]map[string]float64) Extractor

NewFixedRateExtractor returns an APM event extractor that decides whether to extract APM events from spans following the provided extraction rates for a span's (service name, operation name) pair.

func NewLegacyExtractor

func NewLegacyExtractor(rateByService map[string]float64) Extractor

NewLegacyExtractor returns an APM event extractor that decides whether to extract APM events from spans following the specified extraction rates for a span's service.

func NewMetricBasedExtractor

func NewMetricBasedExtractor() Extractor

NewMetricBasedExtractor returns an APM event extractor that decides whether to extract APM events from spans based on the value of the event extraction rate metric set on those span.

func NewNoopExtractor

func NewNoopExtractor() Extractor

NewNoopExtractor returns a new APM event extractor that does not extract any events.

func NewSingleSpanExtractor

func NewSingleSpanExtractor() Extractor

NewSingleSpanExtractor returns a single span extractor that decides whether to extract single spans from traces based on the presence of the KeySpanSamplingMechanism tag set on those spans.

type Processor

type Processor struct {
	// contains filtered or unexported fields
}

Processor is responsible for all the logic surrounding extraction and sampling of APM events from processed traces.

func NewProcessor

func NewProcessor(extractors []Extractor, maxEPS float64) *Processor

NewProcessor returns a new instance of Processor configured with the provided extractors and max eps limitation.

Extractors will look at each span in the trace and decide whether it should be converted to an APM event or not. They will be tried in the provided order, with the first one returning an event stopping the chain.

All extracted APM events are then submitted to sampling. This sampling is 2-fold:

• A first sampling step is done based on the extraction sampling rate returned by an Extractor. If an Extractor returns an event accompanied with a 0.1 extraction rate, then there's a 90% chance that this event will get discarded.
• A max events per second maxEPSSampler is applied to all non-PriorityUserKeep events that survived the first step and will ensure that, in average, the total rate of events returned by the processor is not bigger than maxEPS.

func (*Processor) Process

func (p *Processor) Process(root *pb.Span, t *pb.TraceChunk) (numEvents, numExtracted int64)

Process takes a processed trace, extracts events from it and samples them, returning a collection of sampled events along with the total count of extracted events.

func (*Processor) Start

func (p *Processor) Start()

Start starts the processor.

func (*Processor) Stop

func (p *Processor) Stop()

Stop stops the processor.