Overview

Metrics are numeric measurements over time. CPU usage, memory consumption, request counts, queue depths, error rates -- any quantity that varies and is worth tracking. Metrics are fundamentally different from events and logs: they are dense time-series data (many samples of the same measurement) rather than discrete occurrences or text output.

eventd is a metric sink, not a metric collector. Services and collection agents push metrics to eventd. eventd does not scrape endpoints, read from /proc, or poll for data. The collection mechanism (e.g., a collectord daemon that gathers system metrics) is outside eventd's scope.

§6.1.1 Data model #

A metric data point consists of:

• Name -- a dot-separated string identifying the measurement (e.g., cpu.usage, http.requests.total, disk.read.bytes).
• Labels -- a set of key-value string pairs providing dimensions (e.g., core="0", service="loregd", method="GET"). Labels distinguish different instances of the same measurement.
• Type -- one of counter, gauge, or histogram. The type determines how the metric is interpreted by the query engine.
• Timestamp -- wall clock time of the measurement.
• Value -- the numeric measurement. The encoding depends on the type.

The combination of name and labels uniquely identifies a time series. cpu.usage{core="0"} and cpu.usage{core="1"} are distinct time series.

§6.1.2 Metric types #

§6.1.2.1 Counter #

A monotonically increasing value that resets to zero when the emitting process restarts. Used for cumulative quantities: total requests served, total bytes transmitted, total errors encountered.

The raw counter value is rarely queried directly. The query engine derives rate (change per unit time) from counter samples, handling resets correctly.

A counter value MUST be a non-negative 64-bit floating-point number.

§6.1.2.2 Gauge #

A point-in-time value that can increase or decrease arbitrarily. Used for current state: CPU usage percentage, memory in use, queue depth, temperature.

The raw gauge value is the measurement. Aggregation over time uses min, max, and average -- not rate.

A gauge value MUST be a 64-bit floating-point number (may be negative).

§6.1.2.3 Histogram #

A distribution of observed values across predefined buckets. Used for latency, request sizes, and other quantities where the distribution matters more than the average.

A histogram value consists of:

• An array of bucket boundaries (upper bounds), monotonically increasing.
• An array of cumulative counts, one per bucket. Each count represents the number of observations less than or equal to the corresponding boundary.
• A total count of all observations.
• A sum of all observed values.

Bucket boundaries are defined by the emitter and MUST be consistent across all samples of the same time series. If bucket boundaries change, it is treated as a new time series.

§6.1.3 Loss tolerance #

Metric loss has similar tolerance characteristics to log loss. A missed data point creates a gap in the time series -- the gap is visible but not catastrophic. The query engine interpolates or indicates the gap. Services MUST NOT assume lossless metric delivery.