metrics

Documentation

Overview

Package metrics exposes Toise's internals as Prometheus metrics at /metrics.

The Toise-specific metrics are sampled at scrape time by a custom collector (it reads the live projection and store on each scrape) rather than by instrumenting the hot path — so it adds no overhead to ingestion and no metric can drift out of sync with the graph. The handler also registers the standard Go runtime and process collectors. See #44.

Index

• func Handler(c *Collector, extra ...prometheus.Collector) http.Handler
• func NewAuthFailures() prometheus.Counter
• func NewOpenTenants(count func() float64) prometheus.Collector
• func NewQuarantinedTenants() prometheus.Gauge
• type Collector
  • func NewCollector(g Grapher, s Storer, version, commit string) *Collector
  • func (c *Collector) Collect(ch chan<- prometheus.Metric)
  • func (c *Collector) Describe(ch chan<- *prometheus.Desc)
• type Grapher
• type Maintenance
  • func NewMaintenance() *Maintenance
  • func (m *Maintenance) Collectors() []prometheus.Collector
  • func (m *Maintenance) Observe(op, tenant string, fn func() error) error
• type QueryMetrics
  • func NewQueryMetrics() *QueryMetrics
  • func (m *QueryMetrics) Collectors() []prometheus.Collector
  • func (m *QueryMetrics) ObserveTool(tool, outcome string, dur time.Duration)
• type Storer

Functions

func Handler

func Handler(c *Collector, extra ...prometheus.Collector) http.Handler

Handler returns the /metrics HTTP handler: a private registry holding the Toise collector, the standard Go runtime and process collectors, and any extra collectors (the hot-path ingest and auth counters, #113).

func NewAuthFailures

func NewAuthFailures() prometheus.Counter

NewAuthFailures returns the counter for rejected authentications, wired to auth.Authenticator.OnFailure and registered via Handler's extra collectors.

func NewOpenTenants

func NewOpenTenants(count func() float64) prometheus.Collector

NewOpenTenants returns a gauge that reports, on each scrape, how many tenant stacks are currently open — watched against max_tenants for capacity planning and to decide when to shard tenants across nodes (ADR 0029). It is computed at scrape time via count, so it never goes stale. Register it via Handler's extras.

func NewQuarantinedTenants

func NewQuarantinedTenants() prometheus.Gauge

NewQuarantinedTenants returns the gauge for tenants whose store failed to open at boot and were skipped (their directories are left on disk for recovery). Set once after the registry opens and registered via Handler's extra collectors.

Types

type Collector

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

Collector samples the live graph and store on each Prometheus scrape.

func NewCollector

func NewCollector(g Grapher, s Storer, version, commit string) *Collector

NewCollector builds a collector over the graph and store, stamping build info from version/commit.

func (*Collector) Collect

func (c *Collector) Collect(ch chan<- prometheus.Metric)

Collect implements prometheus.Collector, sampling the live state.

func (*Collector) Describe

func (c *Collector) Describe(ch chan<- *prometheus.Desc)

Describe implements prometheus.Collector.

type Grapher

type Grapher interface {
	EntityCount() int
	RelationCount() int
	CountByType() map[string]int
}

Grapher is the slice of the projection the collector samples.

type Maintenance

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

Maintenance instruments the per-tenant background loops (liveness sweep, heartbeat coalescing, retention pruning, snapshots): how often each op runs, whether it fails, and how long the last pass took. These carry a tenant label — the aggregate gauges sum across tenants, which is exactly what hides a single tenant's failing or slowing maintenance (#143). Cardinality is bounded by the open-tenant cap.

func NewMaintenance

func NewMaintenance() *Maintenance

NewMaintenance builds the maintenance instruments.

func (*Maintenance) Collectors

func (m *Maintenance) Collectors() []prometheus.Collector

Collectors returns the underlying collectors for registration.

func (*Maintenance) Observe

func (m *Maintenance) Observe(op, tenant string, fn func() error) error

Observe runs fn as one maintenance pass and records its outcome and duration. A nil *Maintenance observes nothing and just runs fn.

type QueryMetrics

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

QueryMetrics records per-tool MCP call counts and durations — the query-side observability hung off the mcp.Observer seam (#166). One instance is shared across tenants; register its Collectors via Handler's extras.

func NewQueryMetrics

func NewQueryMetrics() *QueryMetrics

NewQueryMetrics builds the per-tool call counter and duration histogram.

func (*QueryMetrics) Collectors

func (m *QueryMetrics) Collectors() []prometheus.Collector

Collectors exposes the metrics for registration via Handler's extras.

func (*QueryMetrics) ObserveTool

func (m *QueryMetrics) ObserveTool(tool, outcome string, dur time.Duration)

ObserveTool implements mcp.Observer: one finished tool call.

type Storer

type Storer interface {
	Sequence() uint64
	DiskUsage() uint64
	PrunedEvents() uint64
	PrunedBytes() uint64
	SnapshotSeq() uint64
	SnapshotsWritten() uint64
	PruneHorizon() time.Time
}

Storer is the slice of the event store the collector samples.