3.12 Validating a Metric Record

4 min read

Failures on this channel are silent, exactly as on the log channel (§3.4, §3.8). The scopes are the same, with one difference that matters: a metric record has no ignorable field. Every field a metric record carries participates either in the series identity or in the measurement, so there is nothing whose loss leaves a usable record behind. A malformed timestamp costs the log line nothing and costs the sample everything.

3.12.1 The datagram is discarded #

  • it is not valid MessagePack
  • it decodes to something that is neither a map nor an array of maps
  • no KACS sender token arrived
  • the kernel reported its data or ancillary data truncated (§3.9)
  • the collector cannot query the sender token or resolve publication policy

3.12.2 The record is discarded #

A collector MUST discard a record, leaving the rest of its batch untouched, for any of the following.

Structure

  • a required field is absent, or has the wrong type
  • the map contains a duplicate top-level key
  • type is not exactly "counter", "gauge" or "histogram"

Name and labels (§3.10)

  • name is empty or does not match the identifier grammar
  • a label key or value is not a string, or is empty
  • a label key does not match the identifier grammar
  • a label value contains = or ,
  • a label key is repeated within the record
  • a label key is one of timestamp, boot_id, name, type, value, overflow

Timestamp

  • timestamp is present and is not an integer, is negative, or is outside the timestamp domain (§3.5)

Counter and gauge values

  • the value is not a number
  • it converts to a non-finite binary64
  • it is negative and the type is counter

Histogram values

  • the value is not a map, or its map has a duplicate key
  • a field is absent or has the wrong type
  • boundaries is empty
  • a boundary or sum converts to a non-finite binary64
  • counts and boundaries differ in length
  • the converted boundaries are not strictly increasing
  • a count is negative, the counts are not non-decreasing, or a count exceeds total_count
  • total_count is zero and any count or sum is non-zero

Series consistency

  • the record resolves to an existing series whose type differs (§3.10)

Publication policy

  • the conveyed KACS token is denied EVENTD_PUBLISH for name (§3.9)

3.12.3 Why the timestamp rule differs from logs #

On the log channel a malformed timestamp is ignored and the record kept; here it discards the record.

The asymmetry is not an inconsistency. A log line with the wrong time is still the line, and reading it is still worth doing. A sample is a (time, value) pair and nothing else: attaching the collector's receipt time to a measurement taken at an unknown moment does not recover the sample, it fabricates one, and it fabricates one that will be charted next to real ones. Discarding leaves a gap, which is honest (§3.4).

Absence is different from malformation. A record that simply omits timestamp is asserting "now", and the collector's clock is the right answer to that.

3.12.4 Silence, again #

A collector MUST NOT emit an event, write a durable log, or increment anything a query client can observe in response to any failure in this article — with no exception for the series-consistency failure, which is the one that most looks like it deserves one. Local in-memory diagnostic counters and rate-limited standard-error output are permitted by §3.4.

A producer that changes a metric's type is misconfigured, and the misconfiguration is permanent: every sample is discarded for as long as the series exists, and the producer receives no response. Peios eventd increments an in-memory total, retains the latest conflicting metric name and expected and received types, emits at most one coalesced standard-error warning per minute, and includes the total and latest conflict in its SIGQUIT diagnostic dump. None of those signals is part of the query interface or grows in proportion to rejected input.

Edit this page