spans

Documentation

Overview

Package spans governs inner spans on the way into the store.

An inner span is one operation inside a request: a query, a cache lookup, an outbound call. The timings are harmless; the ATTRIBUTES are not. A statement quotes its parameters, a cache key embeds an account id, an outbound URL carries a token in its query string. So attributes are scrubbed and capped BEFORE they are persisted, for the same reason app log lines are: "clean it up later" is after the data is already at rest.

Index

• Constants
• type Governor
  • func New(cfg *config.SpansCfg) (*Governor, error)
  • func (g *Governor) Admit(s *ext.Span) (bool, Reason)
  • func (g *Governor) Enabled() bool
• type Reason

Constants

const (
	DefaultMaxPerRequest = 200
	DefaultMaxAttrBytes  = 4 << 10 // 4 KiB — a long statement, not a whole dump
)

Defaults chosen so that enabling this without tuning it cannot swamp the store. An N+1 query inside a loop is the normal case, not the pathological one, and it is exactly what someone turns this on to find.

Types

type Governor

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

Governor applies the span policy. Safe for concurrent use: ingest is an HTTP handler and several requests land at once.

func New

func New(cfg *config.SpansCfg) (*Governor, error)

New builds a Governor from config. A nil or disabled config yields a Governor that rejects everything with ReasonDisabled, so callers need no special case.

func (*Governor) Admit

func (g *Governor) Admit(s *ext.Span) (bool, Reason)

Admit applies the policy to one span. It returns true when the span should be stored, or the reason it was dropped.

The span is mutated in place: redaction must happen before anything else can hold a reference to the raw attributes.

func (*Governor) Enabled

func (g *Governor) Enabled() bool

type Reason

type Reason string

Reason explains why a span was not stored. Every drop is counted under one of these: data discarded silently is data nobody knows they are missing.

const (
	ReasonOrphan     Reason = "orphan"      // no parent span — belongs to no request
	ReasonTooFast    Reason = "too_fast"    // under min_duration
	ReasonRequestCap Reason = "request_cap" // request already at max_per_request
	ReasonDisabled   Reason = "disabled"    // feature off
	ReasonEmpty      Reason = "empty"       // no name, nothing to file it under
)