web

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

type BoundaryWindow struct {
	Min    time.Time     `json:"min,omitzero"`
	Max    time.Time     `json:"max,omitzero"`
	Spread time.Duration `json:"spread_ns"`
}

type Meta struct {
	SchemaVersion int    `json:"schema_version"`
	Time          string `json:"time"`
	Generation    int64  `json:"generation"`
	Revision      string `json:"revision"`
	Dirty         bool   `json:"dirty"`
	// BuildSource says how Revision was obtained (vcs, ldflags, env, unknown).
	// ProvenanceValid is false for an unknown or dirty build, where a snapshot
	// cannot be reproduced from Revision alone.
	BuildSource     string `json:"build_source"`
	ProvenanceValid bool   `json:"provenance_valid"`
	// Score is the benchmark score supplied via POST /save?score=; persisted
	// snapshots always carry it so every report is attributable to a result.
	Score   string         `json:"score,omitempty"`
	Host    sysinfo.Info   `json:"host"`
	Partial bool           `json:"partial"`
	Health  []health.Entry `json:"health,omitempty"`
	Run     *RunInfo       `json:"run,omitempty"`
	// Profiles is the run's runtime-profile record: every capture attempted at
	// either boundary and the pairs that can be differenced. It is filled when
	// a run is persisted, because that is the first moment both halves exist;
	// a live report has no closing half yet and omits the field. Additive and
	// omitempty, so a v1.0 reader of this JSON is unaffected.
	Profiles *ProfileManifest `json:"profiles,omitempty"`
}

type ProfileCapture struct {
	RunID string       `json:"run_id"`
	Epoch uint64       `json:"epoch"`
	Point ProfilePoint `json:"point"`
	Kind  string       `json:"kind"`
	// File is the published ".pprof" name, empty when nothing was published.
	File string `json:"file,omitempty"`
	// Sidecar is this record's own file name, so a manifest entry can be
	// followed back to the record on disk.
	Sidecar  string `json:"sidecar"`
	OpenGate string `json:"open_gate,omitempty"`
	// Orphan marks an artifact whose run never reached a closing boundary. It
	// is written into the record rather than left to inference, because a lone
	// opening profile is otherwise indistinguishable from half of a pair whose
	// other half has not been taken yet.
	Orphan bool `json:"orphan,omitempty"`

	// The reference point this capture is measured from, copied from the
	// coordinator's boundary record. A boundary is an interval rather than an
	// instant, so the measured spreads travel with it and form the uncertainty
	// floor under every residual below. Legacy providers leave them zero, which
	// means "not reported", not "measured as zero".
	RefPhase         string    `json:"ref_phase"`
	RefAt            time.Time `json:"ref_at,omitzero"`
	RefSpreadNs      int64     `json:"ref_spread_ns"`
	BoundaryAt       time.Time `json:"boundary_at,omitzero"`
	BoundarySpreadNs int64     `json:"boundary_spread_ns"`

	// The measured capture instants. LagFromRefNs is the distance from the
	// boundary to the moment the write actually began, which is the number the
	// residual error is built out of.
	StartedAt    time.Time `json:"started_at,omitzero"`
	FinishedAt   time.Time `json:"finished_at,omitzero"`
	LagFromRefNs int64     `json:"lag_from_ref_ns"`
	DurationNs   int64     `json:"duration_ns"`
	Bytes        int64     `json:"bytes"`

	Status string `json:"status"`
	Code   string `json:"code,omitempty"`
	Err    string `json:"err,omitempty"`
}

type ProfileManifest struct {
	RunID    string           `json:"run_id"`
	Epoch    uint64           `json:"epoch"`
	Validity string           `json:"validity,omitempty"`
	Captures []ProfileCapture `json:"captures,omitempty"`
	// Pairs holds only the kinds whose two halves both exist. A kind with one
	// half is deliberately absent: a difference cannot be taken from it, and
	// listing it would invite the reader to try.
	Pairs []ProfilePair `json:"pairs,omitempty"`
}

type ProfilePair struct {
	Kind      string `json:"kind"`
	OpenFile  string `json:"open_file"`
	CloseFile string `json:"close_file"`
	OpenGate  string `json:"open_gate,omitempty"`
	// RunSpanNs is the distance between the two boundaries themselves.
	RunSpanNs int64 `json:"run_span_ns"`
	// HeadLossNs is the run's beginning that the difference does not contain.
	HeadLossNs int64 `json:"head_loss_ns"`
	// TailExcessNs is the post-boundary tail that the difference does contain.
	TailExcessNs int64 `json:"tail_excess_ns"`
	// ApproxErrorNs is HeadLossNs + TailExcessNs: the total by which the
	// difference is not the run.
	ApproxErrorNs int64  `json:"approx_error_ns"`
	DiffCommand   string `json:"diff_command"`
}

type ProfilePoint string

type Provider struct {
	SQL sqlSnapshotter
	// SQLGeneration and RotateSQL opt into atomic generation boundaries. They
	// are separate callbacks so simple aggregation tables remain usable in
	// tests and custom integrations.
	SQLGeneration func() int64
	RotateSQL     func() (generation int64, entries []agg.Entry)
	// RunGenerationManaged is shorthand for custom providers whose SQL, HTTP,
	// and Counters generations are all owned by StartRun. The per-collector
	// flags below let production preserve that guarantee when only a subset
	// registered successfully.
	RunGenerationManaged      bool
	SQLGenerationManaged      bool
	HTTPGenerationManaged     bool
	CountersGenerationManaged bool
	Health                    *health.Registry
	HTTP                      httpCollector
	AccessLog                 accessLogCollector
	AccessLogQuiet            time.Duration
	AccessLogPoll             time.Duration
	// AccessLogGenerationManaged says the access log's generation adapter is
	// registered with the run coordinator, so the coordinator's
	// BeginBoundary → Drain → Release cycle owns the aggregate's lifetime.
	//
	// POST /reset must then keep its hands off the legacy Snapshot()+Reset()
	// pair. Reset re-opens the log at the current end of file, drops the
	// aggregate and zeroes the health counters the drain's file-replacement
	// guard reads; running it between a closing boundary and that boundary's
	// drain leaves the drain nothing to seal, and the finished run's
	// access-log section silently comes out empty.
	AccessLogGenerationManaged bool
	CollectTimeout             time.Duration
	// InspectionTimeout bounds the context passed to DB and Advisor callbacks.
	InspectionTimeout time.Duration
	Proc              processCollector
	// ProcRunManaged says Proc is registered with the run coordinator. Its
	// reset and final snapshot then happen inside StartRun/FinishRun for both
	// the HTTP and embedded ResetNow entry points.
	ProcRunManaged bool
	// DB captures the database schema (tables/indexes). Called at handler
	// startup and on every reset so each generation records the pre-run state.
	DB func(context.Context) *dbinspect.Schema
	// Advisor reports well-known settings that are not configured. Captured
	// alongside the DB schema at startup and on every reset.
	Advisor func(context.Context) []advisor.Check
	// CacheTelemetry is evaluated at snapshot time so application cache
	// hit/miss/eviction counters can match the measured interval.
	CacheTelemetry func() (*advisor.CacheTelemetry, error)
	// QUICTelemetry is evaluated at snapshot time so packet counters can match
	// the completed benchmark interval rather than handler startup.
	QUICTelemetry func() (*advisor.QUICTelemetry, error)
	// ProtocolTrafficClientFacing is false when a CDN/LB terminates the client
	// connection before the locally collected access log.
	ProtocolTrafficClientFacing *bool
	// Counters exposes user-defined counters (isutools.Count). Reset per
	// generation.
	Counters interface {
		Snapshot() []counters.Entry
		Reset()
	}
	// DataDir persists snapshots for the dashboard history ("" = disabled).
	DataDir string
	// PprofDuration > 0 captures a CPU profile for that long after every
	// reset (i.e. covering the benchmark), stored in DataDir (0 = disabled).
	PprofDuration time.Duration
	// StartRun opens a measurement run at the reset boundary and names it in
	// the reset response. Nil keeps the legacy behaviour, in which a reset
	// only rotates the collector generations and no run id exists.
	//
	// A failure is not fatal to the reset: the generations have already been
	// rotated by the time it is called, and refusing to answer would leave the
	// bench script unable to proceed with measurements that are, in fact,
	// running.
	StartRun func(ctx context.Context) (RunStart, error)
	// FinishRun fixes the closing boundary of the run in flight and returns as
	// soon as that boundary exists. POST /finish calls it and answers 202:
	// draining and snapshot building continue in the background, and making
	// the caller wait for them would put snapshot-building time inside the
	// measured window of whatever runs next.
	//
	// Nil leaves POST /finish unavailable, which is the legacy behaviour of a
	// transport wired without a run coordinator.
	FinishRun func(ctx context.Context) (RunFinish, error)
	// CompleteRun finishes the run in flight, waits for its immutable
	// snapshot, and acknowledges it. POST /save calls it before rendering, so
	// the persisted report describes the interval the run measured rather than
	// whatever the live collectors happen to hold after their generations were
	// frozen.
	//
	// A process that never opened a run must report the zero RunFinish and no
	// error: /save predates the run lifecycle and has to keep working without
	// one.
	CompleteRun func(ctx context.Context) (RunFinish, error)
	// AbortRun abandons the run in flight and fences its background worker.
	// POST /abort is idempotent and publishes no snapshot; profile artifacts
	// already captured at the opening boundary are marked as orphans.
	AbortRun func(ctx context.Context) (RunAbort, error)
	// Sections supplies the completed run's collector sections keyed by
	// collector name, as produced by the run coordinator. Unknown keys and
	// unexpected types are ignored, so a collector can be added on one side of
	// the wiring before the other catches up.
	Sections func() map[string]any
	// RunSnapshot supplies the same sections together with the lifecycle
	// evidence that makes a completed run auditable. When set it supersedes
	// Sections; the older callback remains for custom-provider compatibility.
	RunSnapshot func() *RunSnapshot
	// RuntimeProfiles lists the runtime profiles ("mutex", "block", "heap")
	// captured at a run boundary, in capture order. Empty — the default —
	// captures nothing. The rates themselves are process-wide runtime
	// settings owned by the caller; this package only writes what it is told
	// is enabled, so a profile whose rate is zero must not appear here.
	RuntimeProfiles []string
}

type RunAbort struct {
	RunID     string    `json:"run_id,omitempty"`
	Epoch     uint64    `json:"epoch,omitempty"`
	Reason    string    `json:"reason,omitempty"`
	Detached  bool      `json:"detached,omitempty"`
	AbortedAt time.Time `json:"aborted_at,omitzero"`
	Partial   []string  `json:"partial,omitempty"`
}

type RunCollectorBoundary struct {
	Name      string    `json:"name"`
	Kind      string    `json:"kind"`
	Required  bool      `json:"required"`
	Phase     string    `json:"phase"`
	At        time.Time `json:"at,omitzero"`
	Committed bool      `json:"committed"`
	Code      string    `json:"code,omitempty"`
	Err       string    `json:"err,omitempty"`
	Dropped   bool      `json:"dropped,omitempty"`
}

type RunFinish struct {
	// RunID names the run whose boundary was fixed. Empty means no run was in
	// flight, which is not an error: the save/collect loop predates runs.
	RunID string `json:"run_id,omitempty"`
	// Epoch is the coordinator fencing token for this closing boundary.
	Epoch uint64 `json:"epoch,omitempty"`
	// Validity is the run's data-quality verdict ("valid", "partial",
	// "invalid"), copied verbatim like RunStart.Validity.
	Validity string `json:"validity,omitempty"`
	// AcceptedAt is the measured moment the closing boundary was fixed. It is
	// the end of the interval every section of this run describes.
	AcceptedAt time.Time `json:"accepted_at,omitzero"`
	// GenerationWindow and BoundaryWindow preserve the coordinator's measured
	// uncertainty at the closing boundary for profile residual accounting.
	GenerationWindow BoundaryWindow `json:"generation_window,omitzero"`
	BoundaryWindow   BoundaryWindow `json:"boundary_window,omitzero"`
}

type RunInfo struct {
	RunID            string                 `json:"run_id"`
	Epoch            uint64                 `json:"epoch"`
	Validity         string                 `json:"validity"`
	Trigger          string                 `json:"trigger,omitempty"`
	Collectors       []RunCollectorBoundary `json:"collectors,omitempty"`
	GenerationWindow BoundaryWindow         `json:"generation_window"`
	BoundaryWindow   BoundaryWindow         `json:"boundary_window"`
	StartedAt        time.Time              `json:"started_at,omitzero"`
	FinishedAt       time.Time              `json:"finished_at,omitzero"`
}

type RunSnapshot struct {
	Info     RunInfo
	Sections map[string]any
}

type RunStart struct {
	// RunID is the coordinator's run identifier, echoed in the reset response
	// so a bench script can name the run it started.
	RunID string
	// Epoch is the coordinator fencing token. It prevents a delayed boundary
	// artifact from being attached to a newer incarnation of the same run id.
	Epoch uint64
	// StartedAt is the opening boundary's moment. Boundary artifacts are named
	// after it rather than after the moment they are written, so an opening
	// and a closing artifact of one run share a filename prefix.
	StartedAt time.Time
	// Validity is the run's data-quality verdict ("valid", "partial",
	// "invalid"). It is a plain string because the transport copies it
	// verbatim and never branches on it.
	Validity string
	// GenerationWindow and BoundaryWindow preserve the coordinator's measured
	// uncertainty at the opening boundary for profile residual accounting.
	GenerationWindow BoundaryWindow
	BoundaryWindow   BoundaryWindow
}

type Snapshot struct {
	Meta        Meta                    `json:"meta"`
	DB          *dbinspect.Schema       `json:"db,omitempty"`
	Advisor     []advisor.Check         `json:"advisor,omitempty"`
	Counters    []counters.Entry        `json:"counters,omitempty"`
	Connections *httpstats.ConnSnapshot `json:"connections,omitempty"`
	SQL         []agg.Entry             `json:"sql"`
	HTTP        httpstats.Snapshot      `json:"http,omitempty"`
	AccessLog   *accesslog.Snapshot     `json:"accesslog,omitempty"`
	Proc        *procstats.Snapshot     `json:"proc,omitempty"`

	// The sections below come from the run coordinator's baseline collectors
	// rather than from a live collector read, so they describe the interval
	// between two run boundaries and are absent until a run has completed.
	// Every one of them is additive and omitempty: a v1.0 reader of this JSON
	// is unaffected by their presence.
	//
	// The JSON keys are the collector names the coordinator registers under,
	// so a section can be traced from the snapshot back to the collector that
	// filled it without a translation table.
	Host    *hoststats.Section     `json:"hoststats,omitempty"`
	Network *netstats.NetworkStats `json:"network,omitempty"`
	SQLRows *sqlrows.Section       `json:"sqlrows,omitempty"`
	DBPool  []dbpool.Entry         `json:"dbpool,omitempty"`
	// QueryPlan holds the EXPLAIN output captured in the run's enrich phase.
	// It is filled from the same section map as the others rather than from a
	// live read, which is what keeps a dashboard refresh from putting EXPLAIN
	// statements on the measured database.
	QueryPlan *queryplan.Section `json:"queryplan,omitempty"`
}