ops

Documentation

Overview

Package ops is the Isopace operational surface: liveness/readiness health checks (Health), a metrics registry with Prometheus text exposition (Metrics, which also implements the runtime.Observer facade), cluster membership (Cluster), and an HTTP admin/management API (API) that ties them together and is guarded by rbac when a policy is supplied.

Everything is stdlib-only (net/http, encoding/json). A distributed cluster membership backend (gossip/raft, or one built on the space NATS adapter) is a drop-in Cluster implementation; StaticCluster is the single-node / static default.

Index

• type API
  • func NewAPI(opts ...APIOption) *API
  • func (a *API) Handler() http.Handler
• type APIOption
  • func WithAuth(p *rbac.Policy) APIOption
  • func WithCluster(c Cluster) APIOption
  • func WithHealth(h *Health) APIOption
  • func WithInfo(info map[string]string) APIOption
  • func WithIntrospector(i Introspector) APIOption
  • func WithMetrics(m *Metrics) APIOption
• type CheckFunc
• type CheckResult
• type Cluster
• type Gauge
  • func (g *Gauge) Add(v float64, attrs ...runtime.Attr)
  • func (g *Gauge) Set(v float64, attrs ...runtime.Attr)
• type Health
  • func NewHealth() *Health
  • func (h *Health) Check(ctx context.Context) Report
  • func (h *Health) Deregister(name string)
  • func (h *Health) Names() []string
  • func (h *Health) Register(name string, fn CheckFunc)
• type Introspector
• type Member
• type Metrics
  • func NewMetrics() *Metrics
  • func (m *Metrics) Counter(name string) runtime.Counter
  • func (m *Metrics) Gauge(name string) *Gauge
  • func (m *Metrics) Histogram(name string) runtime.Histogram
  • func (m *Metrics) StartSpan(ctx context.Context, name string, attrs ...runtime.Attr) (context.Context, runtime.Span)
  • func (m *Metrics) WriteText(w io.Writer) error
• type Report
• type StaticCluster
  • func NewStaticCluster(self Member, peers ...Member) *StaticCluster
  • func (c *StaticCluster) Members() []Member
  • func (c *StaticCluster) Self() Member
• type Status

Types

type API

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

API is the HTTP admin/management surface. Build it with NewAPI and mount API.Handler. Liveness and metrics are unauthenticated; /info requires the "admin:read" permission when an rbac policy is configured (open otherwise, for local development).

func NewAPI

func NewAPI(opts ...APIOption) *API

NewAPI builds an API.

func (*API) Handler

func (a *API) Handler() http.Handler

Handler returns the configured HTTP routes.

type APIOption

type APIOption func(*API)

APIOption configures an API.

func WithAuth

func WithAuth(p *rbac.Policy) APIOption

WithAuth enables Basic-auth + permission checks on protected routes.

func WithCluster

func WithCluster(c Cluster) APIOption

WithCluster adds membership to /info.

func WithHealth

func WithHealth(h *Health) APIOption

WithHealth wires the readiness checks behind /readyz.

func WithInfo

func WithInfo(info map[string]string) APIOption

WithInfo adds static key/value info (build version, etc.) to /info.

func WithIntrospector

func WithIntrospector(i Introspector) APIOption

WithIntrospector adds the component list to /info.

func WithMetrics

func WithMetrics(m *Metrics) APIOption

WithMetrics wires the metrics registry behind /metrics.

type CheckFunc

type CheckFunc func(ctx context.Context) error

CheckFunc is a single readiness probe; returning a non-nil error marks it failed. It is given a context so a probe can honour a deadline.

type CheckResult

type CheckResult struct {
	OK    bool   `json:"ok"`
	Error string `json:"error,omitempty"`
}

CheckResult is the outcome of one named check.

type Cluster

type Cluster interface {
	// Self returns this node.
	Self() Member
	// Members returns all known members, including self.
	Members() []Member
}

Cluster reports cluster membership. A distributed implementation (gossip, raft, or one built on the space NATS adapter) is a drop-in; StaticCluster is the single-node / static-list default.

type Gauge

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

Gauge is a settable instrument.

func (*Gauge) Add

func (g *Gauge) Add(v float64, attrs ...runtime.Attr)

Add adds to the gauge value for the given labels.

func (*Gauge) Set

func (g *Gauge) Set(v float64, attrs ...runtime.Attr)

Set sets the gauge value for the given labels.

type Health

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

Health is a registry of readiness checks. It is safe for concurrent use.

func NewHealth

func NewHealth() *Health

NewHealth returns an empty health registry.

func (*Health) Check

func (h *Health) Check(ctx context.Context) Report

Check runs every registered check and aggregates the results. With no checks registered the report is healthy.

func (*Health) Deregister

func (h *Health) Deregister(name string)

Deregister removes a check.

func (*Health) Names

func (h *Health) Names() []string

Names returns the registered check names, sorted.

func (*Health) Register

func (h *Health) Register(name string, fn CheckFunc)

Register adds (or replaces) a named check.

type Introspector

type Introspector interface {
	Components() []string
}

Introspector exposes the running component names for the /info endpoint; *runtime.Host satisfies it.

type Member

type Member struct {
	ID   string `json:"id"`
	Addr string `json:"addr"`
	Self bool   `json:"self"`
}

Member is a node in the cluster.

type Metrics

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

Metrics is a metrics registry: counters, gauges, and summaries (count+sum, used for histograms and span durations), each broken out by label set. It implements runtime.Observer so instrumentation recorded through that facade is exposed here, and renders the Prometheus text exposition format via Metrics.WriteText. It is safe for concurrent use.

func NewMetrics

func NewMetrics() *Metrics

NewMetrics returns an empty metrics registry.

func (*Metrics) Counter

func (m *Metrics) Counter(name string) runtime.Counter

Counter returns a counter instrument by name (runtime.Observer).

func (*Metrics) Gauge

func (m *Metrics) Gauge(name string) *Gauge

Gauge returns a settable gauge instrument by name.

func (*Metrics) Histogram

func (m *Metrics) Histogram(name string) runtime.Histogram

Histogram returns a summary instrument by name (runtime.Observer).

func (*Metrics) StartSpan

func (m *Metrics) StartSpan(ctx context.Context, name string, attrs ...runtime.Attr) (context.Context, runtime.Span)

StartSpan records the span's duration (seconds) into a summary named "<name>_duration_seconds" when the span ends (runtime.Observer).

func (*Metrics) WriteText

func (m *Metrics) WriteText(w io.Writer) error

WriteText writes the registry in the Prometheus text exposition format. Series are emitted grouped by metric name with a single # TYPE line each.

type Report

type Report struct {
	Status Status                 `json:"status"`
	Checks map[string]CheckResult `json:"checks"`
}

Report aggregates the results of all checks.

type StaticCluster

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

StaticCluster is a fixed-membership Cluster: this node plus an optional static list of peers. It is the default when no dynamic membership backend is wired in (e.g. a single-node deployment).

func NewStaticCluster

func NewStaticCluster(self Member, peers ...Member) *StaticCluster

NewStaticCluster builds a cluster of self plus peers. self.Self is forced true and peers' Self is forced false.

func (*StaticCluster) Members

func (c *StaticCluster) Members() []Member

Members returns all members, sorted by ID.

func (*StaticCluster) Self

func (c *StaticCluster) Self() Member

Self returns this node.

type Status

type Status string

Status is the overall health verdict.

const (
	// StatusHealthy means every registered check passed.
	StatusHealthy Status = "healthy"
	// StatusUnhealthy means at least one check failed.
	StatusUnhealthy Status = "unhealthy"
)