dbpool

type Metrics ¶

type Metrics struct {
	// InUse is the number of connections currently checked out of the pool,
	// sampled instantaneously (not a max-since-last-sample - see Sampler).
	// Compare against MaxOpen for saturation; a value pinned at MaxOpen
	// together with a rising WaitCount is the pool-exhaustion signature that
	// made #2474 need a goroutine dump to diagnose.
	InUse metrics.Gauge
	// MaxOpen is the pool's configured connection limit (sql.DBStats.MaxOpenConnections),
	// exported so dashboards can compute saturation (InUse/MaxOpen) rather than
	// an absolute connection count that means nothing without cross-referencing
	// the node's core.yaml.
	MaxOpen metrics.Gauge
	// WaitCountTotal is the cumulative number of connection checkouts that had
	// to wait because the pool was at its limit. Unlike InUse this is
	// loss-free between samples: database/sql increments it once per blocked
	// checkout regardless of how often it is scraped, so a burst too short
	// for the gauge to catch still shows up here.
	WaitCountTotal metrics.Counter
	// WaitSecondsTotal is the cumulative time callers spent waiting for a
	// connection. Divided by WaitCountTotal (as a rate ratio, not a raw
	// division, since both are counters) it gives the mean wait per checkout:
	// rate(wait_seconds_total[$__rate_interval]) / rate(wait_count_total[$__rate_interval]).
	WaitSecondsTotal metrics.Counter
}

Metrics holds the instrumentation of a Sampler. Unlike most Panurus metrics families, these are exported under an explicitly set Namespace/Subsystem rather than letting the calling package derive the name - see "How a metric name is built" and "Metric hygiene" in docs/development/metrics.md. This is the first Panurus metric family to do so, a deliberate exception rather than an oversight: it is the fix the Metric hygiene section recommends for new metrics, and there is no existing dashboard or alert to break.

func NewMetrics(p metrics.Provider) *Metrics

type Sampler ¶

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

Sampler periodically reads (*sql.DB).Stats() for every registered pool and reports it through Metrics.

It exists because Panurus never checks out a connection itself - the pool lives inside fabric-smart-client's postgres.Open and reaches Panurus only as a *sql.DB - so (*sql.DB).Stats() is the only available signal, and metrics.Provider has no way to register a custom collector that would be evaluated at scrape time. Something has to poll.

The InUse and MaxOpen gauges are deliberately instantaneous, not a max-since-last-sample: sampling at DefaultPoolMetricsInterval (1s) makes a sustained exhaustion episode - the kind that actually hangs Select calls, as in #2474 - visible on most samples regardless, and a transient burst too short to land on a sample still shows up in WaitCountTotal, which database/sql increments once per blocked checkout independent of how often anything scrapes it. Peak occupancy is a PromQL concern (max_over_time(db_pool_in_use[...])), not something the sampler itself needs to track. Do not raise the interval back toward something like 10s without re-reading this: at a slower poll the gauge can sit well below MaxOpen throughout an episode that was in fact permanently exhausted between samples.

func NewSampler(cfg driver3.Config, p metrics.Provider) *Sampler

func (s *Sampler) Register(key, label string, db *sql.DB)

func (s *Sampler) Sample()

func (s *Sampler) Start() error

func (s *Sampler) Stop() error