stats

Documentation

Overview

Package stats produces a workload-level snapshot of a PostgreSQL database derived from pg_stat_statements. It complements the per-plan `analyze` command: where `analyze` asks "why is this one query slow?", stats asks "where is the time going across the whole database?"

All types here are serialisable to the JSON shape documented in schemas/stats-v1.json. Field names are frozen for v1; renaming requires a new schema version.

Index

• Constants
• type Meta
• type Options
  • func DefaultOptions() Options
• type QueryGroup
• type RawQueryRow
• type Recommendation
• type WorkloadStats
  • func Compute(ctx context.Context, pool *pgxpool.Pool, opts Options) (*WorkloadStats, error)
  • func ComputeFromRows(rows []RawQueryRow, meta Meta, opts Options) *WorkloadStats

Constants

const SchemaVersion = "stats-v1"

SchemaVersion tags every emitted WorkloadStats so consumers can reject incompatible versions without attempting to parse them.

Types

type Meta

type Meta struct {
	Database       string    `json:"database"`
	ServerVersion  string    `json:"server_version"`
	SnapshotAt     time.Time `json:"snapshot_at"`
	StatsSince     time.Time `json:"stats_since,omitempty"`
	DBAgentVersion string    `json:"dbagent_version"`
	SchemaVersion  string    `json:"schema_version"`
}

Meta records provenance for a workload snapshot.

type Options

type Options struct {
	TopN int
	// SinceMinutes is accepted for forward compatibility but is not
	// currently applied as a rolling filter — pg_stat_statements has
	// no per-statement timestamp. It is propagated to the fetcher so
	// a real filter can be added without touching callers.
	SinceMinutes  int
	ExcludeRegexp []string // skip queries whose text matches any of these patterns
	IncludeSystem bool     // disable the default noise filter (pg_catalog, SET/SHOW, VACUUM, ...)
}

Options tunes the Compute / ComputeFromRows behaviour.

func DefaultOptions

func DefaultOptions() Options

DefaultOptions returns the default tuning (TopN=10, no filters).

type QueryGroup

type QueryGroup struct {
	Rank           int     `json:"rank"`
	QueryID        int64   `json:"query_id"`
	Calls          int64   `json:"calls"`
	TotalTimeMs    float64 `json:"total_time_ms"`
	MeanTimeMs     float64 `json:"mean_time_ms"`
	Rows           int64   `json:"rows"`
	SharedBlksHit  int64   `json:"shared_blks_hit"`
	SharedBlksRead int64   `json:"shared_blks_read"`

	// CacheHitRatio is -1 when neither hit nor read counters are set
	// (for example on DDL that doesn't touch shared buffers).
	CacheHitRatio float64 `json:"cache_hit_ratio"`

	PctOfTotal float64 `json:"pct_of_total"`
	QueryText  string  `json:"query_text"`
	QueryKind  string  `json:"query_kind"`
}

QueryGroup is one query's contribution to a workload, ranked within a particular top-list.

type RawQueryRow

type RawQueryRow = pgstat.WorkloadRow

RawQueryRow is the shape Compute consumes. Aliased to pgstat.WorkloadRow so the fetcher and aggregator share exactly one canonical row type — no translation step, no drift — while still letting the stats package keep a clean top-level API.

type Recommendation

type Recommendation struct {
	ID       string         `json:"id"`
	Severity rules.Severity `json:"-"`

	// SeverityName exists purely for JSON — rules.Severity is an int
	// enum and serialising the integer leaks implementation detail.
	SeverityName string         `json:"severity"`
	Title        string         `json:"title"`
	Message      string         `json:"message"`
	Evidence     map[string]any `json:"evidence,omitempty"`
	Action       string         `json:"action,omitempty"`
}

Recommendation is a workload-level observation distinct from a plan-level rule finding. Rules analyse plans; recommendations analyse aggregated workload metrics.

type WorkloadStats

type WorkloadStats struct {
	Meta Meta `json:"meta"`

	TotalQueries    int64   `json:"total_queries"`
	TotalExecutions int64   `json:"total_executions"`
	TotalTimeMs     float64 `json:"total_time_ms"`
	ReadTimeMs      float64 `json:"read_time_ms"`
	WriteTimeMs     float64 `json:"write_time_ms"`
	CacheHitRatio   float64 `json:"cache_hit_ratio"`

	TopByTotalTime []QueryGroup `json:"top_by_total_time"`
	TopByCallCount []QueryGroup `json:"top_by_call_count"`
	TopByMeanTime  []QueryGroup `json:"top_by_mean_time"`
	TopByIO        []QueryGroup `json:"top_by_io"`
	TopByLowCache  []QueryGroup `json:"top_by_low_cache"`

	Recommendations []Recommendation `json:"recommendations"`
}

WorkloadStats is the top-level snapshot returned by Compute.

func Compute

func Compute(ctx context.Context, pool *pgxpool.Pool, opts Options) (*WorkloadStats, error)

Compute pulls pg_stat_statements data live and returns a fully populated WorkloadStats. It composes pgstat.FetchWorkload (fetches raw rows) and ComputeFromRows (aggregates and ranks) so tests can exercise the math without a live database.

func ComputeFromRows

func ComputeFromRows(rows []RawQueryRow, meta Meta, opts Options) *WorkloadStats

ComputeFromRows is the pure-function core of Compute. It takes already-fetched rows plus Meta and returns the snapshot. Safe to call with a nil or empty row slice.

Recommendation freshness (R7) anchors on meta.SnapshotAt rather than time.Now(), so the "X minutes ago" reasoning stays consistent with the Stats-since line shown in the renderers and tests get a deterministic output for a given fixture.