statistics

Statistics and metrics collection configuration for monitoring and performance analysis

statistics

The statistics clause configures lightweight in‑process metrics that the server maintains for observation and troubleshooting. Two metric types are supported:

counter – Accumulates event counts (e.g. authentication attempts, failures).
histogram – Tracks a distribution (e.g. response latency, session duration) using fixed bucket boundaries plus aggregate summaries.

Metrics are kept in ring buffers (bounded size) so memory usage remains predictable. Each metric can optionally override default retention (samples) and update/rollover interval (interval) settings.

Basic Example

statistics {
    defaults {
        samples 600;      # keep last 600 intervals
        interval 60000;   # 60s aggregation interval
    }

    counter "auth_requests";
    counter "auth_failures" {
        interval 30000;   # higher granularity
    }

    histogram "auth_latency_ms" {
        buckets [5, 10, 20, 50, 100, 250, 500];
    }
}

Elements

Block / Statement	Context	Required	Description
`statistics { ... }`	top level	Yes	Container for all metric definitions
`defaults { ... }`	statistics	No	Sets fallback `samples` / `interval` for following metrics
`counter "NAME" { ... }`	statistics	No	Defines a counter metric
`histogram "NAME" { ... }`	statistics	No	Defines a histogram metric
`samples N;`	defaults / counter / histogram	No	Ring buffer length (number of intervals retained)
`interval MS;`	defaults / counter / histogram	No	Aggregation window in milliseconds
`buckets [a,b,c,...];`	histogram	Recommended	Ascending integer boundaries forming bucket cut points

Ordering & Inheritance

defaults affects only metrics declared after it (top‑down).
Per‑metric overrides inside counter / histogram supersede defaults.
Multiple defaults blocks can appear; later ones override subsequent metrics.

Counters

Counters record an accumulated event count per interval. At each interval boundary, the current active count is finalized into the ring buffer and reset for the next window.

Typical counters:

auth_requests
auth_success
auth_failure
acct_start
acct_stop

Counter Example

counter "acct_start" {
    samples 300;
    interval 10000;  # 10s granularity for burst visibility
}

Histograms

Histograms bucket observed measurements (latency, size, duration, etc.). An observation is classified into the first bucket boundary ≥ value, or an implicit +Inf bucket beyond the last.

Histogram Example

histogram "session_duration_sec" {
    samples 1440;            # 1 day at 60s intervals
    interval 60000;
    buckets [60, 300, 600, 1800, 3600, 7200, 14400, 28800];
}

Retention (`samples`)

samples defines how many interval snapshots are retained (not raw events). Memory footprint is proportional to samples * metric_count.

Choose values balancing:

Resolution of historical trends.
Memory constraints.
Query / export cost (if later exposed).

Interval (`interval`)

Shorter intervals give finer temporal resolution but:

Increase rollover overhead.
Reduce per‑interval counts (potentially noisier data).

Typical ranges:

10s–30s for spiky load diagnostics.
60s–300s for general production trend monitoring.

Histogram Buckets (`buckets`)

Select boundaries reflecting real distribution percentiles:

Start with rough powers-of-two or known SLO thresholds.
Adjust after observing production percentiles.

Misconfigured (non‑ascending) buckets should produce a validation error.