observe

Documentation

Overview

Package observe is the in-process metrics + JSONL dumping layer shared by the controller, relay, and agent. The surface is deliberately minimal — Counter, Gauge, Histogram, plus a Registry that owns named instances. No external observability stack (Prometheus, OpenTelemetry) is pulled in: the project ships a JSONL dump (Dumper) and a localhost-only debug endpoint (DebugMux) so operators can collect data without running a TSDB.

Index

• Variables
• func DebugMux(reg *Registry) http.Handler
• func ServeDebug(ctx context.Context, addr string, reg *Registry) error
• type Counter
  • func (c *Counter) Add(n int64)
  • func (c *Counter) Inc()
  • func (c *Counter) Value() int64
• type Dumper
  • func NewDumper(reg *Registry, path string, interval time.Duration) *Dumper
  • func (d *Dumper) Run(ctx context.Context) error
• type Gauge
  • func (g *Gauge) Dec()
  • func (g *Gauge) Inc()
  • func (g *Gauge) Set(n int64)
  • func (g *Gauge) Value() int64
• type Histogram
  • func NewHistogram(bounds ...time.Duration) *Histogram
  • func (h *Histogram) Observe(d time.Duration)
  • func (h *Histogram) Quantile(q float64) time.Duration
  • func (h *Histogram) Snapshot() HistogramSnapshot
• type HistogramSnapshot
• type Registry
  • func NewRegistry() *Registry
  • func (r *Registry) Counter(name string) *Counter
  • func (r *Registry) Gauge(name string) *Gauge
  • func (r *Registry) Histogram(name string, bounds ...time.Duration) *Histogram
  • func (r *Registry) Snapshot() Snapshot
• type Snapshot

Variables

var DefaultDurationBounds = []time.Duration{
	time.Microsecond,
	10 * time.Microsecond,
	100 * time.Microsecond,
	time.Millisecond,
	10 * time.Millisecond,
	100 * time.Millisecond,
	time.Second,
	10 * time.Second,
}

DefaultDurationBounds covers ~10ns through 10s in roughly decade steps; it's the default for histograms that observe a duration.

Functions

func DebugMux

func DebugMux(reg *Registry) http.Handler

DebugMux returns an http.Handler that serves: - /debug/metrics: JSON snapshot of the registry - /debug/pprof/*: standard net/http/pprof handlers

Mount on a localhost-only listener so it's not reachable from the outside.

func ServeDebug

func ServeDebug(ctx context.Context, addr string, reg *Registry) error

ServeDebug binds to addr and serves DebugMux(reg) until ctx cancels. Blocks until the server stops.

Types

type Counter

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

Counter is a monotonically increasing int64.

func (*Counter) Add

func (c *Counter) Add(n int64)

func (*Counter) Inc

func (c *Counter) Inc()

func (*Counter) Value

func (c *Counter) Value() int64

type Dumper

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

Dumper periodically writes a Snapshot of the Registry as one JSON line to a file. Each line is self-contained, so downstream tooling (e.g. `tools/correlate`, a notebook) can stream the file without holding state across lines.

func NewDumper

func NewDumper(reg *Registry, path string, interval time.Duration) *Dumper

NewDumper writes JSONL lines to path every interval. path is created if missing; its parent directory must already exist (or be ".").

func (*Dumper) Run

func (d *Dumper) Run(ctx context.Context) error

Run blocks until ctx cancels, dumping snapshots at the configured interval. The first dump happens immediately after Run starts so short-lived test processes still produce output.

type Gauge

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

Gauge is a freely-mutable int64 (concurrent stream count, RSS, etc).

func (*Gauge) Dec

func (g *Gauge) Dec()

func (*Gauge) Inc

func (g *Gauge) Inc()

func (*Gauge) Set

func (g *Gauge) Set(n int64)

func (*Gauge) Value

func (g *Gauge) Value() int64

type Histogram

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

Histogram is a bucketed observation distribution. Buckets are open-bottom, closed-top: counts[i] holds observations <= bounds[i], counts[len(bounds)] is the overflow ("> bounds[last]") bucket.

func NewHistogram

func NewHistogram(bounds ...time.Duration) *Histogram

NewHistogram constructs a histogram. If bounds is empty, DefaultDurationBounds is used.

func (*Histogram) Observe

func (h *Histogram) Observe(d time.Duration)

Observe records one duration sample.

func (*Histogram) Quantile

func (h *Histogram) Quantile(q float64) time.Duration

Quantile estimates the value at q (0 < q < 1) via linear bucket interpolation. Returns 0 if there are no observations.

func (*Histogram) Snapshot

func (h *Histogram) Snapshot() HistogramSnapshot

Snapshot copies counter values; cheap.

type HistogramSnapshot

type HistogramSnapshot struct {
	Bounds []time.Duration `json:"bounds_ns"`
	Counts []int64         `json:"counts"`
	SumNs  int64           `json:"sum_ns"`
	N      int64           `json:"n"`
}

HistogramSnapshot is a point-in-time view used by dumpers / HTTP.

type Registry

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

Registry owns named metrics. It is goroutine-safe and the same instance is shared across server constructors.

func NewRegistry

func NewRegistry() *Registry

NewRegistry returns an empty registry.

func (*Registry) Counter

func (r *Registry) Counter(name string) *Counter

Counter returns (or creates) the named counter.

func (*Registry) Gauge

func (r *Registry) Gauge(name string) *Gauge

Gauge returns (or creates) the named gauge.

func (*Registry) Histogram

func (r *Registry) Histogram(name string, bounds ...time.Duration) *Histogram

Histogram returns (or creates) the named histogram with the given bounds. If a histogram is already registered with the same name, the existing one is returned regardless of bounds — first registration wins.

func (*Registry) Snapshot

func (r *Registry) Snapshot() Snapshot

Snapshot collects every metric. Names within each kind are sorted for stable JSONL output.

type Snapshot

type Snapshot struct {
	TsUnixMs   int64                        `json:"ts_unix_ms"`
	Counters   map[string]int64             `json:"counters"`
	Gauges     map[string]int64             `json:"gauges"`
	Histograms map[string]HistogramSnapshot `json:"histograms"`
}

Snapshot is a flat point-in-time view of every registered metric.