Documentation
¶
Index ¶
- Constants
- func DiagnosticEnabled() bool
- func EnsureMigrationRoles(ctx context.Context, dsn string) error
- func PGXPoolerConfig(dsn string) (*pgx.ConnConfig, error)
- func Validate(samples []Sample, interval time.Duration, prefix string) error
- type Activity
- type ActivityKey
- type ActivityRecord
- type ActivitySnapshot
- type Clock
- type ClockFunc
- type Config
- type ConfigSnapshot
- type ConnFactory
- type Counter
- type Diagnostic
- func (d *Diagnostic) EmitReport(emit any) error
- func (d *Diagnostic) RecordPhase(p Phase)
- func (d *Diagnostic) SetMeasuredOverhead(off, on []time.Duration)
- func (d *Diagnostic) Start(ctx context.Context, off, on []time.Duration) error
- func (d *Diagnostic) Stop() DiagnosticReport
- func (d *Diagnostic) WaitFirstSample(ctx context.Context) bool
- type DiagnosticReport
- type DiagnosticStatus
- type Observer
- type Overhead
- type OverheadReport
- type PgBouncerSnapshot
- type Phase
- type PhaseEvent
- type Pool
- type QueryConn
- type Rows
- type Sample
- type Server
Constants ¶
const DiagnosticFirstSampleTimeout = 30 * time.Second
DiagnosticFirstSampleTimeout bounds startup even when a caller supplies a context without a deadline.
Variables ¶
This section is empty.
Functions ¶
func DiagnosticEnabled ¶
func DiagnosticEnabled() bool
DiagnosticEnabled intentionally checks only the exact opt-in value.
func EnsureMigrationRoles ¶
EnsureMigrationRoles serializes the cluster-global role bootstrap used by PostgreSQL integration packages. The session lock covers the check/create sequence across databases and processes on the same test cluster.
func PGXPoolerConfig ¶
func PGXPoolerConfig(dsn string) (*pgx.ConnConfig, error)
PGXPoolerConfig derives the administrative connection from the supplied pooler DSN. The caller's database is intentionally not used for SHOW commands; it remains the observer's row-filter prefix instead.
Types ¶
type ActivityKey ¶
type ActivityKey struct{ Application, State, WaitEvent string }
type ActivityRecord ¶
type ActivityRecord struct {
Database string `json:"database,omitempty"`
Application string `json:"application,omitempty"`
State string `json:"state,omitempty"`
WaitEvent string `json:"wait,omitempty"`
PID int64 `json:"pid"`
QuerySHA256 string `json:"query_sha256,omitempty"`
XactStart *time.Time `json:"xact_start,omitempty"`
QueryStart *time.Time `json:"query_start,omitempty"`
}
type ActivitySnapshot ¶
type ActivitySnapshot []ActivityRecord
func ParseActivity ¶
func ParseActivity(rows Rows) (ActivitySnapshot, error)
type Config ¶
type Config struct {
RunPrefix, Source string
Interval time.Duration
Pooler, Postgres ConnFactory
Clock Clock
// contains filtered or unexported fields
}
type ConfigSnapshot ¶
type ConnFactory ¶
func PGXFactory ¶
func PGXFactory(dsn string) ConnFactory
PGXFactory creates one persistent pgx connection. Observer caches the returned connection, so samples share a session and terminal shutdown owns its close; callers never need to expose a DSN in observer output.
func PGXPoolerFactory ¶
func PGXPoolerFactory(dsn string) ConnFactory
PGXPoolerFactory uses pgx's simple protocol, which is required by the PgBouncer administrative database. Extended-protocol prepared statements are not supported by that database.
type Counter ¶
type Counter struct{ Xacts, Queries, Received, Sent, Wait, QueryTime, XactTime, Assignments, ClientParse, ServerParse, ClientBind int64 }
type Diagnostic ¶
type Diagnostic struct {
// contains filtered or unexported fields
}
func NewDiagnostic ¶
func NewDiagnostic(c Config) *Diagnostic
func (*Diagnostic) EmitReport ¶
func (d *Diagnostic) EmitReport(emit any) error
EmitReport emits the one diagnostic line. The caller supplies the logger so this package never couples telemetry to testing.T or a production logger. JSON contains only bounded observer data and the sanitized run identity.
func (*Diagnostic) RecordPhase ¶
func (d *Diagnostic) RecordPhase(p Phase)
func (*Diagnostic) SetMeasuredOverhead ¶
func (d *Diagnostic) SetMeasuredOverhead(off, on []time.Duration)
SetMeasuredOverhead replaces the provisional gate measurements after the sampler has been started. This is used by wired tests whose ON arm must be measured while the observer is live.
func (*Diagnostic) Start ¶
Start performs the overhead gate before the sampler is started. Empty or mismatched baselines are incomplete telemetry, not a pass.
func (*Diagnostic) Stop ¶
func (d *Diagnostic) Stop() DiagnosticReport
Stop is cancellation-safe and idempotent. A started sampler is always stopped before the snapshot is returned.
func (*Diagnostic) WaitFirstSample ¶
func (d *Diagnostic) WaitFirstSample(ctx context.Context) bool
WaitFirstSample waits until the sampler has successfully populated one complete sample. A timeout is a diagnostic gap, never a pass.
type DiagnosticReport ¶
type DiagnosticReport struct {
Identity string `json:"identity"`
Status DiagnosticStatus `json:"status"`
Overhead OverheadReport `json:"overhead"`
Complete bool `json:"complete"`
Gaps []string `json:"gaps,omitempty"`
Samples []Sample `json:"samples,omitempty"`
PhaseEvents []PhaseEvent `json:"phase_events,omitempty"`
Truncated bool `json:"truncated,omitempty"`
}
type DiagnosticStatus ¶
type DiagnosticStatus string
Diagnostic is an opt-in, fail-closed telemetry controller for C32. It is deliberately separate from the protocol runner: its verdict is never an input to the runner's PASS/FAIL decision.
const ( DiagnosticPass DiagnosticStatus = "PASS" DiagnosticBlocked DiagnosticStatus = "BLOCKED" DiagnosticInconclusive DiagnosticStatus = "INCONCLUSIVE" DiagnosticInterval = 100 * time.Millisecond )
type Observer ¶
type Observer struct {
// contains filtered or unexported fields
}
func NewObserver ¶
type OverheadReport ¶
type PgBouncerSnapshot ¶
type PgBouncerSnapshot struct {
Stats map[string]Counter
Pools map[string]Pool
Servers map[string]Server
Truncated bool `json:"truncated,omitempty"`
}
func ParsePGBouncer ¶
func ParsePGBouncer(stats, pools, servers Rows, prefix string) (PgBouncerSnapshot, error)
ParsePGBouncer parses SHOW STATS, SHOW POOLS, and SHOW SERVERS using column names (never positional columns), aggregating only databases in RunPrefix.
type PhaseEvent ¶
type Pool ¶
type Pool struct{ ClientActive, ClientWaiting, ServerActive, ServerIdle, ServerUsed, ServerTested, ServerLogin, MaxWait int64 }
type Rows ¶
type Rows interface {
Next() bool
Values() ([]any, error)
Err() error
Close()
FieldDescriptions() []pgconn.FieldDescription
}
Rows is the small part of pgx.Rows needed by the observer. It also makes the parser usable with in-memory rows in unit tests.
type Sample ¶
type Sample struct {
Offset time.Duration
Wall time.Time
Sequence uint64
Gap time.Duration
Stats PgBouncerSnapshot
Activity ActivitySnapshot
Config ConfigSnapshot
Truncated bool `json:"truncated,omitempty"`
ActivityTruncated bool `json:"activity_truncated,omitempty"`
}