Documentation
¶
Overview ¶
Package metrics is GoGraph's optional observability surface.
The package exposes lightweight counters and latency observers that public blocking APIs can populate. Two backends are wired up:
- the default no-op backend: zero overhead, used when no external metrics system is configured.
- a Prometheus-compatible backend (opt-in via SetBackend): once installed, latency histograms and counters are exported through the standard prometheus.Registry mechanism.
The Prometheus client_golang import is intentionally NOT a dependency of this package: keeping it out of go.mod means every consumer that doesn't want Prometheus pays no module-graph cost. Callers that want the Prometheus backend implement the Backend interface in their own code; the [Prometheus] helper lives in a separate internal/metrics/prometheus subpackage when added later.
Wire-up. Every public blocking API in search/, search/centrality/, search/community/, search/flow/, search/extern/, graph/io/{csv,graphml,dot,jsonl}, and store/{wal,snapshot,txn,checkpoint,recovery,bulk} emits a latency observation under the name "<package-path>.<ExportedSymbol>" and increments a paired "<package-path>.<ExportedSymbol>.errors" counter on the error path. The authoritative inventory of every wired metric is in docs/metrics.md; the wireup smoke test in internal/metrics/wireup_test.go fails loudly if a wired symbol stops emitting its expected name.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func IncCounter ¶
IncCounter increments the named counter by delta on the current backend.
func ObserveLatency ¶
ObserveLatency records a latency sample on the current backend.
func SetBackend ¶
func SetBackend(b Backend)
SetBackend swaps the global metrics sink. Pass nil to restore the no-op default. The function is safe to call from any goroutine at any time; in-flight events on the previous backend complete against the previous pointer.
Types ¶
type Backend ¶
type Backend interface {
// IncCounter increments the named counter by delta.
IncCounter(name string, delta uint64)
// ObserveLatency records a single latency sample under name.
ObserveLatency(name string, d time.Duration)
// SetGauge records the CURRENT value of a quantity that can go down as
// well as up.
//
// A counter cannot express one: the module's bounded-resources mandate asks
// that every cache, pool and queue surface its UTILISATION, and utilisation
// falls when the resource is released. MVCC version memory is the case that
// forced it — the number of live version records rises with write churn and
// falls when the reclaimer sweeps, and a monotonic counter can describe
// neither the level nor the bound.
SetGauge(name string, v float64)
}
Backend is the interface every metrics sink implements. It is intentionally tiny so the no-op default is zero overhead.
type Stopwatch ¶ added in v0.6.0
type Stopwatch struct {
// contains filtered or unexported fields
}
Stopwatch measures the latency of one operation. Obtain it from Time and call Stopwatch.Stop — typically deferred — to record the elapsed time under the operation's name.
Unlike a returned closure (which escapes to the heap), a Stopwatch is a value returned by value, so the idiomatic `defer metrics.Time("op").Stop()` records no per-call heap allocation: the value lives in the caller's frame and the deferred value-receiver call is open-coded.
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
Package prometheus provides a [metrics.Backend] implementation that produces Prometheus-compatible text exposition output — with no dependency on github.com/prometheus/client_golang.
|
Package prometheus provides a [metrics.Backend] implementation that produces Prometheus-compatible text exposition output — with no dependency on github.com/prometheus/client_golang. |