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 ¶
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.
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).
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.
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