pgstat

Documentation

Overview

Package pgstat reads from the pg_stat_statements extension and reports on its installation state.

Index

• Variables
• func FetchWorkload(ctx context.Context, pool *pgxpool.Pool, opts WorkloadOptions) ([]WorkloadRow, WorkloadMeta, error)
• type ExtensionStatus
  • func CheckExtension(ctx context.Context, pool *pgxpool.Pool) (ExtensionStatus, error)
  • func (s ExtensionStatus) Ready() bool
• type QueryStat
  • func TopQueries(ctx context.Context, pool *pgxpool.Pool, opts TopOptions) ([]QueryStat, error)
• type TopOptions
• type WorkloadMeta
• type WorkloadOptions
• type WorkloadRow

Variables

var ErrExtensionMissing = errors.New("pg_stat_statements extension is not installed")

ErrExtensionMissing is returned when queries that depend on pg_stat_statements are attempted without the extension present.

Functions

func FetchWorkload

func FetchWorkload(ctx context.Context, pool *pgxpool.Pool, opts WorkloadOptions) ([]WorkloadRow, WorkloadMeta, error)

FetchWorkload pulls the full pg_stat_statements snapshot plus the provenance metadata stats.Compute needs. Returns ErrExtensionMissing if pg_stat_statements is not available. Missing pg_stat_statements_info (PostgreSQL 13 and older) is NOT an error — StatsSince stays zero and the caller surfaces R8.

Types

type ExtensionStatus

type ExtensionStatus struct {
	ServerVersion            string
	InSharedPreloadLibraries bool
	ExtensionInstalled       bool
}

ExtensionStatus reports the state of pg_stat_statements on a server.

func CheckExtension

func CheckExtension(ctx context.Context, pool *pgxpool.Pool) (ExtensionStatus, error)

CheckExtension runs three queries to determine the state of pg_stat_statements on the current server and database.

func (ExtensionStatus) Ready

func (s ExtensionStatus) Ready() bool

Ready reports whether pg_stat_statements is both preloaded and installed as an extension in the current database.

type QueryStat

type QueryStat struct {
	QueryID        int64
	Query          string
	Calls          int64
	TotalExecTime  float64 // ms
	MeanExecTime   float64 // ms
	Rows           int64
	SharedBlksHit  int64
	SharedBlksRead int64
}

QueryStat is one row from pg_stat_statements.

func TopQueries

func TopQueries(ctx context.Context, pool *pgxpool.Pool, opts TopOptions) ([]QueryStat, error)

TopQueries returns up to opts.Limit rows from pg_stat_statements, ordered by the option-specified column. Returns ErrExtensionMissing if the extension is not installed.

type TopOptions

type TopOptions struct {
	Limit   int
	OrderBy string // "total" | "mean" | "calls" | "io" | "cache"
	// IncludeSystem disables the default noise filter (pg_catalog
	// scans, transaction-control, maintenance commands). Off by
	// default so `dbagent top` shows user workload.
	IncludeSystem bool
}

TopOptions configures a TopQueries call.

type WorkloadMeta

type WorkloadMeta struct {
	Database      string
	ServerVersion string
	SnapshotAt    time.Time
	StatsSince    time.Time
}

WorkloadMeta is the provenance block returned alongside the rows. ServerVersion is the raw pg_config value, StatsSince is the timestamp from pg_stat_statements_info (zero value if unavailable on older PostgreSQL — stats code surfaces this via recommendation R8 rather than as an error).

type WorkloadOptions

type WorkloadOptions struct {
	SinceMinutes int
	// IncludeSystem disables the default noise filter (pg_catalog
	// scans, transaction-control, maintenance commands, dbagent's
	// own probes). Off by default so `dbagent stats` shows user
	// workload.
	IncludeSystem bool
}

WorkloadOptions tunes FetchWorkload's SQL filters. Empty values mean no filter.

type WorkloadRow

type WorkloadRow struct {
	QueryID           int64
	Query             string
	Calls             int64
	TotalExecTimeMs   float64
	MeanExecTimeMs    float64
	Rows              int64
	SharedBlksHit     int64
	SharedBlksRead    int64
	SharedBlksDirtied int64
	SharedBlksWritten int64
}

WorkloadRow is the flat pg_stat_statements shape consumed by internal/stats's aggregation code. Stage 1's top.go fetches the same catalog with a different column set and top-N limit; keeping the workload fetch separate avoids entangling two callers with different filter / ordering needs.