Documentation
¶
Overview ¶
Package observe provides lightweight, lock-free metrics collection for celeris servers.
Use Collector.Snapshot to retrieve a point-in-time Snapshot containing request counts, error rates, latency histogram, active connections, and engine-level metrics. All recording methods are safe for concurrent use.
For Prometheus and debug endpoint integration, see the middleware/metrics package.
Index ¶
- type CPUMonitor
- type Collector
- func (c *Collector) RecordError()
- func (c *Collector) RecordRequest(duration time.Duration, status int)
- func (c *Collector) RecordRequestSharded(workerID uint32, duration time.Duration, status int)
- func (c *Collector) RecordSwitch()
- func (c *Collector) SetCPUMonitor(m CPUMonitor)
- func (c *Collector) SetEngineMetricsFn(fn func() EngineMetrics)
- func (c *Collector) Snapshot() Snapshot
- type EngineMetrics
- type Snapshot
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type CPUMonitor ¶ added in v1.2.0
type CPUMonitor interface {
// Sample returns the current CPU utilization as a fraction in [0.0, 1.0].
Sample() (float64, error)
// Close releases any resources held by the monitor.
Close() error
}
CPUMonitor provides CPU utilization sampling. Implementations are platform-specific: Linux uses /proc/stat, other platforms use runtime/metrics. Use NewCPUMonitor to create the appropriate implementation for the current platform.
Call Close when the monitor is no longer needed to release resources (e.g., the /proc/stat file descriptor on Linux).
func NewCPUMonitor ¶ added in v1.2.0
func NewCPUMonitor() (CPUMonitor, error)
NewCPUMonitor creates a platform-appropriate CPU utilization monitor. On Linux, it reads /proc/stat for accurate system-wide CPU usage. Returns an error if the monitor cannot be initialized.
type Collector ¶
type Collector struct {
// contains filtered or unexported fields
}
Collector aggregates request metrics using lock-free counters. A Collector is safe for concurrent use by multiple goroutines. Hot counters are striped across shardCount shards keyed by worker ID (set on the Context by the engine) so concurrent RecordRequest calls from different workers don't contend on a single cache line.
func NewCollector ¶
func NewCollector() *Collector
NewCollector creates a new Collector with zeroed counters. The server creates one automatically unless Config.DisableMetrics is true.
func (*Collector) RecordError ¶
func (c *Collector) RecordError()
RecordError increments the error counter.
Note: RecordRequest automatically counts responses with status >= 500 as errors. Use RecordError only for errors that do not result in an HTTP response (e.g., connection-level failures). Lands on shard 0.
func (*Collector) RecordRequest ¶
RecordRequest increments the request counter and records the latency in the appropriate histogram bucket. Status codes >= 500 also increment the error counter.
Routes to shard 0 — callers who can supply a worker ID (engine handlers via Context.WorkerID) should prefer RecordRequestSharded to avoid the cross-worker cache-line contention on shard 0.
func (*Collector) RecordRequestSharded ¶ added in v1.4.1
RecordRequestSharded is the worker-aware variant: caller passes a worker ID (or any goroutine-stable value) so the increment lands on a per-worker shard. Eliminates the cross-core MESI ping-pong on a single counter.
func (*Collector) RecordSwitch ¶
func (c *Collector) RecordSwitch()
RecordSwitch increments the engine switch counter.
func (*Collector) SetCPUMonitor ¶ added in v1.2.0
func (c *Collector) SetCPUMonitor(m CPUMonitor)
SetCPUMonitor registers a CPU utilization monitor. When set, Snapshot() includes a CPUUtilization field sampled on each call (~every 15s is typical).
func (*Collector) SetEngineMetricsFn ¶
func (c *Collector) SetEngineMetricsFn(fn func() EngineMetrics)
SetEngineMetricsFn registers a function that returns current engine metrics.
type EngineMetrics ¶
type EngineMetrics = engine.EngineMetrics
EngineMetrics is a type alias for engine.EngineMetrics, re-exported here so users of the observe package do not need to import engine directly.
type Snapshot ¶
type Snapshot struct {
// RequestsTotal is the cumulative number of handled requests.
RequestsTotal uint64
// ErrorsTotal is the cumulative number of requests that returned HTTP 5xx.
ErrorsTotal uint64
// ActiveConns is the number of currently open connections.
ActiveConns int64
// EngineSwitches counts how many times the adaptive engine changed strategies.
EngineSwitches uint64
// LatencyBuckets holds request counts per latency histogram bucket.
LatencyBuckets []uint64
// BucketBounds are the upper-bound thresholds (in seconds) for each bucket.
BucketBounds []float64
// EngineMetrics contains the underlying engine's own performance counters.
EngineMetrics EngineMetrics
// CPUUtilization is the system CPU utilization as a fraction [0.0, 1.0].
// Returns -1 if no CPU monitor is configured or sampling failed.
CPUUtilization float64
}
Snapshot is a point-in-time copy of all collected metrics. All fields are read-only values captured at the moment Collector.Snapshot was called.
Source Files