obs

Documentation

Overview

Package obs is the observability seam. Live today: the Metrics interface with an OpenMetrics Registry (served at /_metrics), alongside the slow-query log (driver TraceProfile — see backend.InstallSlowLog) and the admin audit log (meta store). The Channels type below is a seam for later work: routing each structured channel to its own sink (file, per-database file, syslog) and the live MONITOR tail are not yet wired — every channel currently fans to the default logger.

Index

• type Channels
  • func Default() *Channels
• type Exposer
• type Metrics
• type Nop
  • func (Nop) Forget(string)
  • func (Nop) IncRequests(string, string)
  • func (Nop) ObserveLatency(string, time.Duration)
• type Registry
  • func NewRegistry() *Registry
  • func (r *Registry) Forget(db string)
  • func (r *Registry) IncRequests(db, _ string)
  • func (r *Registry) ObserveLatency(db string, d time.Duration)
  • func (r *Registry) SetGauge(name string, sample func() int64)
  • func (r *Registry) WriteOpenMetrics(w io.Writer)

Types

type Channels

type Channels struct {
	Server   *slog.Logger // lifecycle / errors
	Conn     *slog.Logger // connect / disconnect / auth outcome
	SQLExec  *slog.Logger // statements (opt-in verbose = general log)
	SQLSlow  *slog.Logger // over the slow threshold
	SQLAudit *slog.Logger // who ran what (security)
	SQLError *slog.Logger // statement errors
}

Channels holds one logger per structured channel. Phase 0 points them all at the default logger; Phase 7 gives each an independent sink and format.

func Default

func Default() *Channels

Default fans every channel to slog.Default.

type Exposer

type Exposer interface {
	WriteOpenMetrics(w io.Writer)
}

Exposer is implemented by a Metrics sink that can render itself as OpenMetrics/Prometheus text (the /_metrics endpoint checks for it).

type Metrics

type Metrics interface {
	IncRequests(db, principal string)
	ObserveLatency(db string, d time.Duration)
	Forget(db string) // drop a detached database's series
}

Metrics is the counter/latency sink. Phase 7 backs it with an OpenMetrics exporter; Nop is the Phase 0 default.

type Nop

type Nop struct{}

Nop is a no-op Metrics.

func (Nop) Forget

func (Nop) Forget(string)

func (Nop) IncRequests

func (Nop) IncRequests(string, string)

func (Nop) ObserveLatency

func (Nop) ObserveLatency(string, time.Duration)

type Registry

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

Registry is the in-process metrics sink: request counters and latency sums per database, plus named gauges sampled on scrape. It satisfies Metrics and renders OpenMetrics/Prometheus text. It is safe for concurrent use.

A single mutex guards the per-request counter bumps — fine at POC and moderate load (the critical section is one map write); shard by database or switch to per-database atomic counters if profiling ever shows contention at high QPS.

func NewRegistry

func NewRegistry() *Registry

NewRegistry builds an empty metrics registry.

func (*Registry) Forget

func (r *Registry) Forget(db string)

Forget drops a database's series (request count + latency) so a detached database stops appearing in scrapes and its maps don't grow unbounded across create/detach churn. Gauges are keyed by metric name, not db, so untouched.

func (*Registry) IncRequests

func (r *Registry) IncRequests(db, _ string)

IncRequests counts one request against a database. principal is accepted for the Metrics interface but not used as a label (unbounded cardinality).

func (*Registry) ObserveLatency

func (r *Registry) ObserveLatency(db string, d time.Duration)

ObserveLatency records a request's duration against a database.

func (*Registry) SetGauge

func (r *Registry) SetGauge(name string, sample func() int64)

SetGauge registers a live gauge sampled at scrape time (e.g. active sessions, open databases). A nil sampler removes the gauge.

func (*Registry) WriteOpenMetrics

func (r *Registry) WriteOpenMetrics(w io.Writer)

WriteOpenMetrics renders the registry as Prometheus/OpenMetrics text. Series are emitted in sorted order so the output is stable.