metrics

package
v0.19.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Oct 30, 2026 License: Apache-2.0 Imports: 6 Imported by: 0

README

internal/metrics

Overview

Prometheus metrics for the server on a private registry. The package defines typed enum labels, recorder functions, fixed-surface HTTP instrumentation, the bounded /metrics listener, and a test helper that reads series values.

Interface

  • Label enums: Surface (SurfaceAPI, SurfaceGit, SurfaceHealth), ContentionScope (ScopeRefs, ScopeScanState, ScopeMeta), SizeGuardResult (SizeGuardWarn, SizeGuardRefuse), MetaRefusal (MetaRefusedDecode, MetaRefusedStale, MetaRefusedVanished, MetaRefusedForeignNonce, MetaRefusedVanishedMark; MetaRefusal.String returns its label value), Job (JobOrphanSweep, JobRepack), Result (ResultSuccess, ResultNoop, ResultError), CommitGraphOutcome (nine CommitGraph* values) [metrics.go:Surface]
  • Recorders: S3WALContentionExhausted, S3WALLeaseRenewalFailed, SetS3WALLeaseHeld, S3WALManifestSizeGuard, S3WALMetaRefused, CommitGraphRefresh, JobRun [metrics.go:JobRun]
  • InstrumentHTTP, InstrumentMux — count requests by surface and status class and observe duration; InstrumentMux also counts mux-generated redirects [metrics.go:InstrumentMux]
  • Handler, NewServer — promhttp exposition and the metrics http.Server with one GET /metrics route [metrics.go:NewServer]
  • IsUnspecifiedBind — reports whether a listen address binds all interfaces [metrics.go:IsUnspecifiedBind]
  • Value — sums current series values that match labels, for tests [metrics.go:Value]
  • Metric names: openstorage_http_requests_total, openstorage_http_request_duration_seconds, openstorage_s3wal_cas_contention_exhausted_total, openstorage_s3wal_lease_renewal_failures_total, openstorage_s3wal_lease_held, openstorage_s3wal_manifest_size_guard_total, openstorage_s3wal_meta_refused_total, openstorage_commit_graph_refresh_total, openstorage_job_runs_total [metrics.go:httpRequests]

Invariants

  • name panics on an out-of-range enum value or an empty label [metrics.go:name]
  • JobRun panics when an orphan sweep reports a noop result [metrics.go:JobRun]
  • InstrumentHTTP panics on a nil handler; InstrumentMux panics on a nil mux or classifier [metrics.go:InstrumentMux]
  • statusWriter.WriteHeader records only the first status >= 200; codeClass maps status 0 to 2xx [metrics.go:codeClass]
  • Scrape bounds are fixed: Handler sets a 10 s timeout and 4 in-flight scrapes [metrics.go:Handler]; NewServer sets 8 KiB max header bytes [metrics.go:NewServer]
  • IsUnspecifiedBind returns false for a malformed address [metrics.go:IsUnspecifiedBind]

Side Effects

  • init registers nine collectors on the private registry and pre-creates label series, so a clean process exposes zero values [metrics.go:init]
  • Recorders mutate process-wide counters and gauges [metrics.go:S3WALContentionExhausted]
  • statusWriter.Unwrap exposes the wrapped writer for http.ResponseController [metrics.go:statusWriter.Unwrap]
  • NewServer sets 5 s header, 10 s read, 20 s write, and 60 s idle timeouts [metrics.go:NewServer]
  • Value calls registry.Gather [metrics.go:Value]

Verification

  • Run: go test ./internal/metrics/... -tags=openstorage_viewcheck -count=1 -race -timeout=30m

Documentation

Overview

Package metrics owns the opt-in Prometheus exposition (ADR-48, issue #325). Collectors live on a private registry, never the global default one, and every label value is a constant chosen here: callers pass typed enums, so no request data can reach a label. Incrementing is cheap and harmless when no metrics listener runs (hook subprocesses, or serve without OPENSTORAGE_METRICS_LISTEN).

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func CommitGraphRefresh

func CommitGraphRefresh(o CommitGraphOutcome)

CommitGraphRefresh counts one cache commit-graph refresh outcome.

func Handler

func Handler() http.Handler

Handler serves the private registry's exposition, bounded in time and concurrency.

func InstrumentHTTP

func InstrumentHTTP(s Surface, next http.Handler) http.Handler

InstrumentHTTP counts requests and their duration under the fixed surface label. Nothing from the request (path, host, headers, method) becomes a label value.

func InstrumentMux

func InstrumentMux(mux *http.ServeMux, classify func(pattern string) Surface) http.Handler

InstrumentMux instruments a whole ServeMux, so responses the mux generates itself (the /api → /api/ redirect, path-cleaning redirects) are counted too. The surface comes from classify applied to the pattern mux.Handler reports: the matched registration, or for a mux redirect the path the redirect leads to. classify must map every input to one of the fixed surfaces; the pattern itself never becomes a label.

func IsUnspecifiedBind

func IsUnspecifiedBind(addr string) bool

IsUnspecifiedBind reports whether addr binds every interface (empty host or an unspecified IP). Such binds get a startup warning; they are not refused (ADR-48). The warning is not exposure detection.

func JobRun

func JobRun(j Job, r Result)

JobRun counts one background job execution outcome.

func NewServer

func NewServer() *http.Server

NewServer builds the metrics listener's server: a private mux with the single GET /metrics route (HEAD is served by the same pattern; other methods get 405, other paths 404) and fixed timeouts.

func S3WALContentionExhausted

func S3WALContentionExhausted(scope ContentionScope)

S3WALContentionExhausted counts one S3WAL mutation that returned ErrCASContention to its caller.

func S3WALLeaseRenewalFailed

func S3WALLeaseRenewalFailed()

S3WALLeaseRenewalFailed counts one lease renewal write attempt that returned an error.

func S3WALManifestSizeGuard

func S3WALManifestSizeGuard(r SizeGuardResult)

S3WALManifestSizeGuard counts one manifest size-guard event.

func S3WALMetaRefused added in v0.19.0

func S3WALMetaRefused(c MetaRefusal)

S3WALMetaRefused counts one entry into a meta.json refusal state.

func SetS3WALLeaseHeld

func SetS3WALLeaseHeld(held bool)

SetS3WALLeaseHeld records whether this process holds the instance lease.

func Value

func Value(metric string, labels map[string]string) float64

Value returns the current value of one series (counter, gauge, or a histogram's _count/_sum), summed over series matching labels. It exists for tests in other packages, which assert deltas around fault seams.

Types

type CommitGraphOutcome

type CommitGraphOutcome int

CommitGraphOutcome is how one cache commit-graph refresh ended (ADR-47, issue #322). Label values equal githttp's outcome names, which are also its documented log contract.

const (
	CommitGraphWritten CommitGraphOutcome = iota
	CommitGraphWrittenPlain
	CommitGraphSkippedTipCap
	CommitGraphSkippedBusy
	CommitGraphLockHeld
	CommitGraphMemoryLimit
	CommitGraphTimedOut
	CommitGraphCanceled
	CommitGraphFailed
)

type ContentionScope

type ContentionScope int

ContentionScope names the S3WAL mutation loop that exhausted its CAS attempts.

const (
	ScopeRefs ContentionScope = iota
	ScopeScanState
	ScopeMeta
)

type Job

type Job int

Job names a background job whose executions are counted.

const (
	JobOrphanSweep Job = iota
	JobRepack
)

type MetaRefusal added in v0.19.0

type MetaRefusal int

MetaRefusal is the class of an S3WAL meta.json refusal (issue #516): the latch classes keep the last trusted state, the quarantine classes drop it until restart.

const (
	MetaRefusedDecode MetaRefusal = iota
	MetaRefusedStale
	MetaRefusedVanished
	MetaRefusedForeignNonce
	MetaRefusedVanishedMark
)

func (MetaRefusal) String added in v0.19.0

func (c MetaRefusal) String() string

type Result

type Result int

Result is a job execution outcome.

const (
	ResultSuccess Result = iota
	ResultNoop
	ResultError
)

type SizeGuardResult

type SizeGuardResult int

SizeGuardResult is the manifest size-guard outcome.

const (
	SizeGuardWarn SizeGuardResult = iota
	SizeGuardRefuse
)

type Surface

type Surface int

Surface is the fixed HTTP surface label, chosen per mux registration.

const (
	SurfaceAPI Surface = iota
	SurfaceGit
	SurfaceHealth
)

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL