agenttest

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

	// SetInfoEndpoints overrides the endpoints /info advertises, independent of
	// which HTTP patterns are actually registered via HandleTraces. By default,
	// /info advertises every registered pattern, mirroring the real agent
	// discovery contract. Tests can use this to advertise or withhold specific
	// endpoints (e.g. /v0.6/stats, /v1.0/traces) to control agent-capability-
	// driven tracer behavior (such as trace protocol selection) deterministically.
	SetInfoEndpoints(endpoints []string)

	// 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
}

type Info struct {
	Rates map[string]float64 `json:"rate_by_service"`
}

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
}

type SpanLister interface {
	// Spans returns a copy of every collected span in randomized order.
	// Randomized order exists to break order-dependent assertions, which are a
	// common source of test flakiness. Match spans by their attributes, not by
	// position. Each call returns a copy, so callers may mutate the span and
	// its maps without changing the collected spans. Copying covers the span
	// struct, the Meta, Metrics, and Tags maps, and Tags values of the JSON
	// shapes that trace decoders produce: nested maps and slices. Tags values
	// of any other reference type are shared with the collected span.
	Spans() []*Span
}

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

type TraceHandler func(io.Reader) []*Span