Documentation
¶
Overview ¶
Package metrics is the cheap, lock-free observability seam between the request datapath (internal/server) and the admin/dashboard surface (internal/admin).
Design constraints:
- Zero cost when no admin block is configured: a *Metrics is threaded through the server, and is NIL when there is no admin block. Every recorder is a nil-safe no-op, so the datapath pays nothing.
- Never block a request: all live counters are atomic.Int64 (no mutex on the hot path). The latency histogram is fixed-bucket atomic counters.
- State that already lives somewhere authoritative (cache fill, upstream health) is NOT mirrored here — it is read on demand from the live objects by the admin layer, so it can never drift.
Index ¶
- type Metrics
- func (m *Metrics) DecUpgrade()
- func (m *Metrics) IncCoalesceWaiter()
- func (m *Metrics) IncCoalesceWinner()
- func (m *Metrics) IncInternalError()
- func (m *Metrics) IncOriginError()
- func (m *Metrics) IncOriginFetch()
- func (m *Metrics) IncRequest()
- func (m *Metrics) IncUpgrade()
- func (m *Metrics) RecordCacheStatus(status string)
- func (m *Metrics) RecordLatency(d time.Duration)
- func (m *Metrics) RecordRateLimit(action, _ string)
- func (m *Metrics) RecordSecurity(action, _ string)
- func (m *Metrics) Snapshot() Snapshot
- type Snapshot
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Metrics ¶
type Metrics struct {
// contains filtered or unexported fields
}
Metrics holds the process-wide live counters fed from the request datapath. The zero value is not usable; construct with New. A nil *Metrics is a valid no-op receiver for every method (so the server can hold a nil one with no overhead).
func (*Metrics) DecUpgrade ¶ added in v0.2.1
func (m *Metrics) DecUpgrade()
DecUpgrade records one torn-down connection-upgrade tunnel. Must be called exactly once per IncUpgrade (the tunnel's Close path guards single-call). Nil-safe.
func (*Metrics) IncCoalesceWaiter ¶
func (m *Metrics) IncCoalesceWaiter()
IncCoalesceWaiter counts a request that waited on another's in-flight fetch.
func (*Metrics) IncCoalesceWinner ¶
func (m *Metrics) IncCoalesceWinner()
IncCoalesceWinner counts a request that won the single-flight (did the fetch).
func (*Metrics) IncInternalError ¶
func (m *Metrics) IncInternalError()
IncInternalError counts a request that ended in a recovered panic (answered with a 500 by the ServeHTTP recover guard). Nil-safe.
func (*Metrics) IncOriginError ¶
func (m *Metrics) IncOriginError()
IncOriginError counts an origin fetch that failed (transport/5xx).
func (*Metrics) IncOriginFetch ¶
func (m *Metrics) IncOriginFetch()
IncOriginFetch counts an origin fetch that was attempted.
func (*Metrics) IncRequest ¶
func (m *Metrics) IncRequest()
IncRequest counts one served request (any outcome).
func (*Metrics) IncUpgrade ¶ added in v0.2.1
func (m *Metrics) IncUpgrade()
IncUpgrade records one newly-established connection-upgrade tunnel (the 101 hijack). Paired one-to-one with DecUpgrade on teardown so upgradesActive is an accurate live gauge. Nil-safe (a non-admin server pays nothing).
func (*Metrics) RecordCacheStatus ¶
RecordCacheStatus buckets a request by its final cache-status string (HIT/MISS/HIT-STALE/PASS/SYNTH/PURGE). Unknown values are ignored.
func (*Metrics) RecordLatency ¶
RecordLatency records one request's total wall time into the histogram.
func (*Metrics) RecordRateLimit ¶
RecordRateLimit counts one rate_limit decision by action: "throttle" (an enforced 429), "monitor" (a would-429 that passed), or "pass" (the rule applied but admitted the request). The rule name is accepted for a future per-rule breakdown (audit log slice). Unknown actions are ignored; nil-safe.
func (*Metrics) RecordSecurity ¶
RecordSecurity counts one security-gate decision by action: "allow" (an allowlist short-circuited the gate), "deny" (a deny was enforced -> 403), or "monitor" (a deny would have fired but monitor mode passed it). The rule name is accepted for a future per-rule breakdown (audit log slice); the v1a counter is per-action. Unknown actions are ignored.
type Snapshot ¶
type Snapshot struct {
UptimeSeconds float64 `json:"uptime_seconds"`
Requests int64 `json:"requests"`
Hits int64 `json:"hits"`
Misses int64 `json:"misses"`
HitsStale int64 `json:"hits_stale"`
Passes int64 `json:"passes"`
Synth int64 `json:"synth"`
Purges int64 `json:"purges"`
CoalesceWinners int64 `json:"coalesce_winners"`
CoalesceWaiters int64 `json:"coalesce_waiters"`
OriginFetches int64 `json:"origin_fetches"`
OriginErrors int64 `json:"origin_errors"`
InternalErrors int64 `json:"internal_errors"`
// Security gate (WAF v1a) per-action counters.
SecurityAllow int64 `json:"security_allow"`
SecurityDeny int64 `json:"security_deny"`
SecurityMonitor int64 `json:"security_monitor"`
// rate_limit (WAF v1b) per-action counters.
RateLimitThrottle int64 `json:"rate_limit_throttle"`
RateLimitMonitor int64 `json:"rate_limit_monitor"`
RateLimitPass int64 `json:"rate_limit_pass"`
// UpgradesActive is a GAUGE: connection-upgrade (WebSocket) tunnels currently open.
UpgradesActive int64 `json:"upgrades_active"`
// LatencyBucketBoundsMs are the inclusive upper bounds (ms) of LatencyBuckets;
// LatencyBuckets has one extra trailing overflow bucket.
LatencyBucketBoundsMs []float64 `json:"latency_bucket_bounds_ms"`
LatencyBuckets []int64 `json:"latency_buckets"`
LatencyCount int64 `json:"latency_count"`
// contains filtered or unexported fields
}
Snapshot is an immutable point-in-time view of the metrics, suitable for JSON and Prometheus rendering.
func (Snapshot) HitRatio ¶
HitRatio is hits / (hits + misses + stale-hits), or 0 when there is no cacheable traffic yet. Stale hits count as cache wins.
func (Snapshot) LatencyMeanMs ¶
LatencyMeanMs is the mean request latency in milliseconds (0 with no samples).
func (Snapshot) LatencyP50 ¶
LatencyP50 returns the 50th-percentile latency in milliseconds (bucket-bound estimate). Returns 0 with no samples.
func (Snapshot) LatencyP99 ¶
LatencyP99 returns the 99th-percentile latency in milliseconds (bucket-bound estimate). Returns 0 with no samples.
Source Files