Documentation
¶
Overview ¶
Package ci builds and compares baseline snapshots for the `spaniel ci` subcommand. The types and algorithms here are deliberately decoupled from HTTP, storage, and the rest of spaniel — they take plain inputs so they stay easy to test.
Index ¶
Constants ¶
const SnapshotVersion = 1
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type CheckOptions ¶
type CheckOptions struct {
// DurationThresholdPct: an operation's p95 may grow by at most this much
// before it counts as a regression. Same threshold applies to total root
// duration. Default 20.
DurationThresholdPct float64
// N1Threshold: how many extra repetitions of a fingerprint count as a new
// N+1 regression (vs. a baseline that already saw some repetition). Default 10.
N1Threshold int
}
CheckOptions tunes regression sensitivity. Zero values fall back to the defaults documented in DefaultCheckOptions.
func DefaultCheckOptions ¶
func DefaultCheckOptions() CheckOptions
DefaultCheckOptions returns the values used when CheckOptions fields are 0.
type ErrorOp ¶
type ErrorOp struct {
Service string `json:"service"`
Name string `json:"name"`
Count int `json:"count"`
}
ErrorOp is a (service, name) pair that produced at least one ERROR span.
type N1Group ¶
type N1Group struct {
Fingerprint string `json:"fingerprint"`
Count int `json:"count"`
WastedNs int64 `json:"wasted_ns"`
}
N1Group is a normalized DB fingerprint that fired the N+1 detector.
type Operation ¶
type Operation struct {
Service string `json:"service"`
Name string `json:"name"`
Count int `json:"count"`
P50Ns int64 `json:"p50_ns"`
P95Ns int64 `json:"p95_ns"`
P99Ns int64 `json:"p99_ns"`
}
Operation aggregates duration statistics for a (service, name) pair.
type Regression ¶
type Regression struct {
Kind string `json:"kind"` // "duration" | "root_duration" | "n_plus_one" | "error"
Service string `json:"service,omitempty"`
Operation string `json:"operation,omitempty"`
Fingerprint string `json:"fingerprint,omitempty"`
BaselineP95 int64 `json:"baseline_p95_ns,omitempty"`
CurrentP95 int64 `json:"current_p95_ns,omitempty"`
BaselineNs int64 `json:"baseline_ns,omitempty"`
CurrentNs int64 `json:"current_ns,omitempty"`
BaselineCnt int `json:"baseline_count,omitempty"`
CurrentCnt int `json:"current_count,omitempty"`
DeltaPct float64 `json:"delta_pct,omitempty"`
Message string `json:"message"`
}
Regression is one specific reason `ci check` would fail.
type Result ¶
type Result struct {
Pass bool `json:"pass"`
Options CheckOptions `json:"options"`
Regressions []Regression `json:"regressions"`
}
Result is the outcome of a Compare call. Pass is true only when Regressions is empty.
func Compare ¶
func Compare(baseline, current Snapshot, opts CheckOptions) Result
Compare evaluates current against baseline and reports any regressions.
- Each operation's p95 may grow by at most DurationThresholdPct.
- The root trace duration may grow by at most DurationThresholdPct.
- Any N+1 fingerprint not present in the baseline is a regression. Existing fingerprints are a regression when current_count exceeds baseline_count + N1Threshold.
- Any (service, operation) producing errors in current but not in baseline.
type Snapshot ¶
type Snapshot struct {
Version int `json:"version"`
ExportedAt int64 `json:"exported_at_ns"`
SessionLabel string `json:"session_label"`
TraceCount int `json:"trace_count"`
SpanCount int `json:"span_count"`
RootDurationNs int64 `json:"root_duration_ns"`
Operations []Operation `json:"operations"`
NPlusOne []N1Group `json:"n_plus_one"`
Errors []ErrorOp `json:"errors"`
}
Snapshot is the on-disk baseline format. It captures enough about a session for `ci check` to detect regressions without needing access to every span.
func BuildSnapshot ¶
func BuildSnapshot(label string, exportedAtNs int64, spans []*storage.Span, issues []*storage.TraceIssue) Snapshot
BuildSnapshot constructs a Snapshot from a session's spans and issues. label is the session label to embed in the snapshot. exportedAtNs is the timestamp to embed (so callers can use time.Now() or freeze in tests).
Source Files