Documentation
¶
Overview ¶
Package agenttest provides a mock APM agent for inspecting traces in tests.
The agent collects spans sent via its in-process HTTP transport and exposes them for assertions. No real networking is involved, allowing for flushes to be deterministic and immediate.
agent := agenttest.New()
agent.HandleTraces("/v0.4/traces", myHandler)
agent.Start(t)
// ... start tracer with agent.Addr() / agent.Transport() ...
// ... create spans, flush ...
span := agent.RequireSpan(t, agenttest.With().Operation("http.request"))
By design, this API does not expose span slices or iterators. Order-dependent assertions are a common source of test flakiness; any future iterator must randomize its traversal order.
Index ¶
- type Agent
- type Info
- type Span
- type SpanMatch
- func (m *SpanMatch) Condition(desc string, fn func(*Span) bool) *SpanMatch
- func (m *SpanMatch) FailedConditions(s *Span) []string
- func (m *SpanMatch) Matches(s *Span) bool
- func (m *SpanMatch) Operation(operation string) *SpanMatch
- func (m *SpanMatch) ParentOf(parentID uint64) *SpanMatch
- func (m *SpanMatch) Resource(resource string) *SpanMatch
- func (m *SpanMatch) Service(service string) *SpanMatch
- func (m *SpanMatch) Tag(key string, value any) *SpanMatch
- func (m *SpanMatch) Type(spanType string) *SpanMatch
- type TraceHandler
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Agent ¶
type Agent interface {
// Info returns the agent info configuration (e.g. sampling rates).
Info() *Info
// HandleTraces registers a handler that decodes traces arriving at the given
// HTTP pattern (e.g. "/v0.4/traces") and stores the resulting spans.
HandleTraces(string, TraceHandler)
// Start initializes the agent. Call this before starting the tracer.
Start(testing.TB) error
// Addr returns the agent address to pass to the tracer via WithAgentAddr.
Addr() string
// Transport returns an optimized transport for interacting with the agent.
Transport() http.RoundTripper
// FindSpan returns the first collected span matching all provided conditions,
// or nil if none is found.
FindSpan(...*SpanMatch) *Span
// RequireSpan returns the first collected span matching all provided conditions.
// It fails the test immediately if no matching span is found.
RequireSpan(testing.TB, ...*SpanMatch) *Span
// CountSpans returns the total number of spans collected so far.
CountSpans() int
}
Agent is a mock APM agent that collects spans in-process for test assertions.
type Info ¶
Info holds agent configuration returned to the tracer on flush responses, such as per-service sampling rates.
func (*Info) RateByService ¶
RateByService sets the sampling rate for a given service/env pair. The tracer uses these rates when making sampling decisions.
type Span ¶
type Span struct {
SpanID uint64
// TraceID holds the lower 64 bits of the trace ID. For 128-bit trace IDs
// (which the tracer generates when DD_TRACE_128_BIT_TRACEID_GENERATION_ENABLED
// is set) the upper 64 bits are available in Meta["_dd.p.tid"]. Assertions on
// full 128-bit identity should use that tag rather than this field.
TraceID uint64
ParentID uint64
Service string
Operation string
Resource string
Type string
Start int64 // unix nanoseconds
Duration int64 // nanoseconds
Error int32
Meta map[string]string
Metrics map[string]float64
Tags map[string]any // merged view: meta + metrics + top-level attrs
Children []*Span
}
Span holds the data of a single collected span. Meta and Metrics contain the raw string and numeric tags respectively; Tags is a merged view of both plus top-level attributes (name, service, resource, type) for convenience.
type SpanMatch ¶
type SpanMatch struct {
// contains filtered or unexported fields
}
SpanMatch is a builder for span matching conditions. Create one with With and chain methods to add conditions. Pass the result to Agent.FindSpan or Agent.RequireSpan.
func With ¶
func With() *SpanMatch
With returns a new empty SpanMatch builder. Chain methods like Service, Operation, Tag, etc. to add matching conditions.
func (*SpanMatch) Condition ¶
Condition adds an arbitrary predicate condition with a human-readable description used in diagnostic output when the condition fails.
func (*SpanMatch) FailedConditions ¶
FailedConditions returns human-readable descriptions of conditions that did not match the given span, for use in diagnostic output.
func (*SpanMatch) Matches ¶
Matches reports whether the span satisfies all conditions in this SpanMatch.
func (*SpanMatch) Operation ¶
Operation adds a condition that the span's operation name must equal the given value.
func (*SpanMatch) ParentOf ¶
ParentOf adds a condition that the span's parent ID must equal the given value.
func (*SpanMatch) Resource ¶
Resource adds a condition that the span's resource must equal the given value.
func (*SpanMatch) Service ¶
Service adds a condition that the span's service must equal the given value.
type TraceHandler ¶
TraceHandler decodes trace data from an io.Reader and returns the decoded spans. Implementations handle a specific wire format (e.g. msgpack v0.4 or binary v1.0).
Source Files