Documentation
¶
Overview ¶
Package poolstats exposes engine-agnostic connection-pool statistics for the storage drivers in this module.
Pool stats are opt-in: the large PersistentStorage/KeyValue interfaces are unchanged, and drivers additionally implement PoolStatsProvider. Consumers type-assert the value returned by the existing factories:
store, _ := persistent.NewPersistentStorage(opts)
if p, ok := store.(poolstats.PoolStatsProvider); ok {
stats, err := p.PoolStats(ctx)
if err == nil && stats.Present.Has(poolstats.FieldInUse) {
metrics.Gauge("pool_in_use", stats.InUse)
}
}
Not every backend reports every field. Only emit a metric for a field whose bit is set in Present; a zero value with the bit unset means "not reported", not "zero".
Example ¶
Example shows the opt-in type-assertion pattern. `store` stands in for the value returned by persistent.NewPersistentStorage, connector.NewConnector or temporal.NewKeyValue.
package main
import (
"context"
"fmt"
"github.com/TykTechnologies/storage/poolstats"
)
func main() {
var store interface{}
if p, ok := store.(poolstats.PoolStatsProvider); ok {
stats, err := p.PoolStats(context.Background())
if err == nil && stats.Present.Has(poolstats.FieldInUse) {
fmt.Printf("%s: %d connections in use\n", stats.Engine, stats.InUse)
}
}
}
Output:
Index ¶
Examples ¶
Constants ¶
const ( EnginePostgres = "postgres" EngineMongo = "mongo" EngineMgo = "mgo" EngineRedis = "redis" )
Engine values reported in PoolStats.Engine.
Variables ¶
var ErrClosed = errors.New("pool stats: store is closed")
ErrClosed is wrapped into the error PoolStats returns once the underlying store is closed (or was never connected). Drivers also wrap their own subsystem sentinel (e.g. temperr.ClosedConnection), so either matches with errors.Is; generic consumers can test just ErrClosed to stop scraping.
Functions ¶
This section is empty.
Types ¶
type FieldSet ¶
type FieldSet uint8
FieldSet is a bitmask describing which PoolStats fields a backend reports.
type PoolStats ¶
type PoolStats struct {
// Engine identifies the backend: "postgres", "mongo", "mgo" or "redis".
Engine string
// MaxOpen is the configured maximum number of connections the client may
// hold open in total; 0 means unlimited/unset. For engines whose limit is
// configured per server (mongo), this is that limit times the number of
// live server pools, so it stays comparable to the aggregate Open.
MaxOpen int
// Open is the number of established connections (in use + idle).
Open int
// InUse is the number of connections currently checked out.
InUse int
// Idle is the number of idle connections.
Idle int
// WaitCount is the cumulative number of waits for a connection.
WaitCount int64
// WaitDuration is the cumulative time blocked waiting for a connection.
WaitDuration time.Duration
// CheckOutFailures is the cumulative number of failed attempts to check a
// connection out of the pool. The causes counted are engine-specific:
// mongo includes dial errors and timeouts, redis counts pool-wait timeouts
// only (a dial error alone does not increment it).
CheckOutFailures int64
// Present marks which of the above fields this backend actually reports.
Present FieldSet
}
PoolStats is an engine-agnostic snapshot of a driver's connection pool.
type PoolStatsProvider ¶
PoolStatsProvider is an optional capability interface implemented by drivers that can report pool statistics. Reading stats is cheap and, as a rule, never opens a connection or probes the backing dependency. Narrow exception: a redis cluster client synchronously fetches its cluster state if it was never loaded, so the first read on an idle cluster client can touch Redis (see the redis driver's PoolStats doc).
Implementations must return an error wrapping ErrClosed once the underlying store is closed (or before it is connected) instead of zero-valued stats, so a metrics poller cannot mistake a closed pool for a healthy empty one.
Source Files