# FTDC binary format — verified specification Every claim here was checked against `github.com/mongodb/ftdc` at commit `4041a70` (cloned 2026-07-22). Line citations are to that repo. Where the Big Hole build brief disagreed with the reference implementation, the reference wins and the discrepancy is called out in **⚠ CORRECTION** blocks. Read this before writing a single line of `src/ftdc/`. --- ## 1. File layout A `diagnostic.data/` directory contains: - `metrics.` — completed capture files - `metrics.interim` — the file mongod is currently appending to. Same format. **Its last chunk is routinely truncated mid-write**; a decoder must return every chunk it fully decoded and treat a short read at EOF as normal termination, not as file corruption. Each file is a bare concatenation of BSON documents — no header, no index, no framing beyond BSON's own leading `int32` length. Read a document, advance by its length, repeat. Each document has a `type` field (`read.go:45-52`): | `type` | Meaning | |--------|---------| | `0` | Metadata. Plain BSON: `hostInfo`, `buildInfo`, `getCmdLineOpts`, etc. Keep for display and for host identity. | | `1` | Metric chunk. Contains the compressed sample block. | | other | Skip silently. The reference `continue`s rather than erroring — do the same. | A type-1 chunk document has: - `_id` — BSON datetime, the chunk's start time (`read.go:54`) - `type` — `1` - `data` — BSON binary, the payload described below ## 2. Chunk payload framing `data` is **not** BSON. Its structure (`read.go:61-69`): ``` [0..4) uint32 LE uncompressed length (informational; the reference ignores it) [4..] raw zlib stream ``` The reference implementation slices `zBytes[4:]` and hands the rest to `zlib.NewReader`. Note this is **zlib** (RFC 1950, with the 2-byte header and Adler-32 trailer), not raw deflate — use `fflate.unzlibSync`, not `inflateSync`. Inflating yields, in this exact order: ``` 1. A complete BSON document — the "reference sample" 2. uint32 LE metricsCount 3. uint32 LE deltaCount 4. packed varint deltas, column-major ``` **The counts come *after* the reference document, not before it** (`read.go:85-91`). The Go comment says "now go back and read the first few bytes", which is misleading — nothing seeks backwards. The brief got this right; don't let the comment confuse you. Total samples in the chunk = `deltaCount + 1` (`read.go:130`). Validate `metricsCount == flattenedMetrics.length` and reject the chunk if it differs (`read.go:96-98`) — this is the cheapest possible corruption detector and it catches most decoder bugs immediately. ## 3. Flattening the reference document → metric columns Walk the reference document depth-first in document order (`bson_metric.go:14-25`). The resulting order **is** the column order of the delta block. Get this wrong by one and every metric after the error point is silently attributed to the wrong path. Per BSON type (`bson_metric.go:43-141`): | BSON type | Emits | Starting value | |-----------|-------|----------------| | `Int32` | 1 metric | `int64(value)` | | `Int64` | 1 metric | `value` | | `Boolean` | 1 metric | `1` or `0` | | `DateTime` | 1 metric | epoch **milliseconds** | | `Double` | 1 metric | **`int64(value)`, truncated** — see ⚠ below | | `Timestamp` | **2 metrics** | `seconds * 1000`, then `.inc` = increment — see ⚠ below | | `EmbeddedDocument` | recurse, prefixing the path | — | | `Array` | recurse, child key = `.` | — | | `ObjectID`, `String`, `Decimal128` | **0 metrics** — skipped entirely | — | | anything else | 0 metrics | — | Paths are dotted joins of the parent path with the key — `strings.Join(append(ParentPath, KeyName), ".")` (`ftdc.go:80-82`). Array elements use their numeric index as a path segment, so replica-set members appear as `replSetGetStatus.members.0.state`, `replSetGetStatus.members.1.state`, and so on. The per-column `originalType` from the reference document **must be retained** — it is required to restore values correctly after undelta (`bson_restore.go:100-115`). A decoder that stores only paths and numbers is unrecoverably lossy. --- ### ⚠ CORRECTION 1 — mongod stores a Double as a truncated int64 mongod puts every numeric field into the metrics array as an `int64`. For a `Double` that is the value truncated toward zero, not its bit pattern. From `src/mongo/db/ftdc/util.cpp`, `extractMetricsFromDocument` (mongod 5.0+): ```cpp case NumberDouble: { double value = currentElement.numberDouble(); long long newValue = 0; if (std::isnan(value)) { newValue = 0; } else if (!(value < BSONElement::kLongLongMaxPlusOneAsDouble)) { newValue = std::numeric_limits::max(); } else if (value < std::numeric_limits::min()) { newValue = std::numeric_limits::min(); } else { newValue = static_cast(value); } metrics->emplace_back(newValue); ``` The comment above it in the source says so directly: *"all numeric types are extracted as long (int64) [...] and requires doubles to be integer"*. mongod's own reader puts the value back with `static_cast(metrics[...])`. So: - The first sample of a chunk is `int64(ref)`, computed from the reference document, and the deltas are ordinary value deltas. A `Double` column decodes exactly like an `Int64` column. - The fraction is gone before the value reaches the file. A load average of `0.37` is stored as `0`. Nothing a decoder does can recover it. - The edges: NaN → `0`, `≥ 2^63` and `+Inf` → `INT64_MAX`, `< -2^63` and `-Inf` → `INT64_MIN`. The seed matters past the first sample, because every later value in the chunk is that seed plus deltas. **Versions before 5.0** use `currentElement.numberLong()`, which for a Double is an unguarded `(long long)value` (`bsonelement.h`, r4.4.0). It is identical for every finite, in-range double. For NaN, ±Inf and `|v| ≥ 2^63` it is undefined behaviour in C++: x86 produces `INT64_MIN`, ARM saturates like 5.0+. We follow 5.0+. A pre-5.0 x86 chunk whose reference document holds one of those values would decode that column offset by the difference. No capture so far has shown one. **This section used to say the opposite**, and every Double column decoded wrong because of it. It cited `normalizeFloat` / `restoreFloat` in `github.com/mongodb/ftdc` (`util.go:93-94`, `bson_restore.go:107-108`). Those are real, but they belong to the Go library's own writer, and describe the files *that library* produces. Its reader applies the same convention to mongod's files: it seeds a Double column with the bit pattern of the reference value (`bson_metric.go:92`) and adds mongod's value deltas to it. The result is a value a few ULPs from the reference that moves by about one ULP per sample, then snaps back to the truth at every chunk boundary. On screen, `serverStatus.uptime` read flat at 29 while `uptimeMillis`, an `Int64` in the same document, counted correctly. It survived because the oracle (§7) is built on that same Go reader, so both sides made the same mistake and a 40-million-value equality test passed. `tools/oracle` now undoes the library's seed per chunk (`stored = Values[i] - Values[0] + int64(ref)`) and emits the integer mongod stored. Agreement with an oracle only proves agreement; a plausibility check on a value with a known rate (uptime, 1 per second) is what caught this. ### ⚠ CORRECTION 2 — BSON `Timestamp` expands to TWO columns `bson_metric.go:123-138`: ```go case bsontype.Timestamp: t, i := val.Timestamp() return []Metric{ {KeyName: key, startingValue: int64(t) * 1000}, {KeyName: key + ".inc", startingValue: int64(i)}, } ``` The brief lists `timestamp` as a single numeric leaf. It is two columns: the seconds component scaled to milliseconds, and a synthetic `.inc` column for the increment. This one is worse than CORRECTION 1 because it fails *silently and totally*. `replSetGetStatus` is full of BSON Timestamps (`optimes.lastCommittedOpTime`, `appliedOpTime`, `durableOpTime`, per-member optimes). Miss the `.inc` column on the first one and **every subsequent metric in the chunk is shifted by one column** — you get plausible-looking numbers attached to entirely the wrong metric names. The `metricsCount` check in §2 catches this, which is exactly why you must implement that check. ### ⚠ CORRECTION 3 — Deltas are unsigned varints holding wrapped signed int64 `read.go:112-123`: ```go delta, err = binary.ReadUvarint(buf) // uint64 ... metrics[i].Values[j] = int64(delta) // reinterpret, two's-complement wrap ``` and `util.go:48-55`: ```go out[idx+1] = out[idx] + delta // plain int64 addition, wraps on overflow ``` A delta of `-1` is transmitted as the uvarint `0xFFFFFFFFFFFFFFFF` (10 bytes) and only becomes `-1` via the signed reinterpretation. There is no zigzag encoding. This means **the delta reinterpretation must be exact 64-bit wrapping integer math**. A naive `Number` read of the uvarint gives `1.8446744073709552e19` where the answer is `-1`. ### Doing this fast — do NOT reach for BigInt `BigInt64Array` is the obvious answer and it is the wrong one. BigInt scalar arithmetic runs roughly 10–40× slower than `Number`, and a single node-day is ~216M values (2,500 columns × 86,400 samples). BigInt puts the decoder in the tens-of-seconds range per node-day. The fast design splits the problem, exploiting the fact that **the delta needs exact 64-bit handling but the accumulator usually does not**: **Read every uvarint into a `(hi, lo)` pair of 32-bit halves** — plain `Number` ops, no BigInt: ```js let lo = 0, hi = 0, shift = 0, b; do { b = buf[p++]; if (shift < 28) lo |= (b & 0x7f) << shift; else if (shift === 28) { lo |= (b & 0x0f) << 28; hi = (b & 0x7f) >>> 4; } else hi |= (b & 0x7f) << (shift - 32); shift += 7; } while (b & 0x80); lo >>>= 0; ``` **Accumulate exactly in hi/lo halves for _every_ column type**, with an explicit carry: ```js const sum = accLo + dLo; accLo = sum >>> 0; accHi = (accHi + dHi + (sum > 0xFFFFFFFF ? 1 : 0)) >>> 0; ``` Wrapping is intended: a delta of `-1` arrives as `hi=0xFFFFFFFF, lo=0xFFFFFFFF` and wraps back to exactly `-1`. Then convert **once per changed sample**, branching on the column's declared type. Each case reads straight off the halves, so all three are exact and none needs a modulo. A `Double` column takes the default case, because mongod stores it as an int64 (CORRECTION 1): ```js switch (kind) { case Int32: return lo | 0; // int32(value), sign-extended case Bool: return (hi !== 0 || lo !== 0) ? 1 : 0; default: return (hi >= 0x80000000 ? hi - 0x100000000 : hi) * 0x100000000 + lo; } ``` > **Earlier drafts of this document were wrong here.** They said integer columns could > accumulate directly in a `Float64Array` because "|value| < 2^53 holds for every realistic > FTDC integer." It does not. **WiredTiger timestamp columns routinely exceed 2^53** — they > are `seconds << 32`, so a 2026 timestamp is ~7.7e18. Accumulating such a column in double > precision rounds at every sample and drifts a full ULP away from the reference within a few > hundred samples. Caught by the oracle test at > `wiredTiger.transaction.transaction range of timestamps pinned by a checkpoint`, sample 223: > expected `7665349942738697000`, got `7665349942738696000`. > > Exact hi/lo accumulation with a single conversion at the end is *also* what makes the > output match: the reference converts its exact int64 once (int64 → JSON → double), so one > correctly-rounded conversion on our side lands on the identical double. **Known, bounded precision limit.** `Float64Array` storage cannot represent int64 values above 2^53 exactly, so WiredTiger timestamp columns are stored as the nearest double — a relative error around 1e-16, invisible at any chart scale, and identical to what the reference implementation's own consumers see. Every other column is exact. This is a storage-representation limit, not an accumulation error; do not "fix" it by reintroducing per-sample rounding. **Zero-run fast path** — when the run counter covers the rest of a column, the value is by definition unchanged, so fill it in one call instead of looping: ```js if (nzeroes >= remaining) { out.fill(current, j, nSamples); nzeroes -= remaining; break; } ``` On idle captures this collapses the majority of the decode into `TypedArray.prototype.fill`, which is memset-speed. Idle captures are also the common case in support work — a whole sends you the whole retention window and the incident is ten minutes of it. Net effect: pure `Number` and typed-array arithmetic throughout, one allocation per column, no intermediate JS objects, no BigInt. The brief's instruction to "prefer typed arrays for metric series" is right for *storage*. The point of this section is that the *decode arithmetic* needs deliberate design too — just not BigInt. ### ⚠ CORRECTION 4 — Zero-run state carries across column boundaries `read.go:101` declares the run counter **outside** the per-metric loop: ```go var nzeroes uint64 // <-- outside for i, v := range metrics { // per column for j := 0; j < ndeltas; j++ { // per sample if nzeroes != 0 { delta = 0; nzeroes-- } else { delta = ReadUvarint() if delta == 0 { nzeroes = ReadUvarint() } } ... } } ``` A zero run started near the end of column *i* continues consuming samples at the start of column *i+1* without any new bytes being read. The delta block is a single continuous stream that merely happens to be consumed in column-major order — it is **not** a sequence of independently decodable per-column segments. Anyone who "optimizes" by decoding columns independently, or who resets run state per column, produces a decoder that works perfectly on busy captures and corrupts idle ones — because long zero runs only appear when metrics aren't changing. Test explicitly with an idle-server fixture. The encoding itself: a literal `0` varint means "this delta is zero", and the varint immediately following it gives the count of **additional** consecutive zeros. The brief describes this correctly. --- ## 4. Reconstruction For each column: `series[0] = referenceValue`, `series[i] = series[i-1] + delta[i-1]`, giving `deltaCount + 1` values (`util.go:48-55`). Then apply the per-column type transform recorded during flattening. This is **narrowing, not just relabelling** (`bson_restore.go:100-115`): | Declared type | Restored as | |---|---| | `Double` | unchanged — mongod stored `int64(value)` (CORRECTION 1) | | `Int32` | **`int32(value)` — truncated to the low 32 bits, sign-extended** | | `Boolean` | `value != 0` | | `DateTime` | epoch ms, unchanged | | `Int64` and everything else | unchanged | The `Int32` truncation is not hypothetical. FTDC stores every metric as int64 regardless of its declared BSON type, and some columns overflow their declared width: `serverStatus.wiredTiger.transaction.transaction range of timestamps currently pinned` is declared `Int32` but carries a 64-bit WiredTiger timestamp. The reference decoder truncates it to `0`; a decoder that keeps the full accumulator reports `85899345920`. Match the reference. Every FTDC tool in the ecosystem shows the truncated value, and a support tool that disagrees with MongoDB's own tooling on identical bytes is worse than useless — the discrepancy will be blamed on the tool, correctly. ## 5. Timestamps — verified empirically Note that `github.com/mongodb/ftdc` **never derives per-sample timestamps at all**. It decodes columns and hands you documents (`iterator_sample.go:18-45`); choosing a time axis is left to the consumer. So unlike §§1–4, this section rests on observation of real captures rather than on the reference implementation. Confirmed against a mongod 6.0.26 capture (see `tools/fixtures/generate.sh`): ``` column 0: start [datetime] = 1784728337300 column 1: serverStatus.start [datetime] column 2: serverStatus.pid [int64] ... last column: end [datetime] ``` **`start` is column 0**, a `DateTime`, in epoch milliseconds. There is a matching `end` column at the tail. Use `start` as the sample clock. `DateTime` columns are epoch **milliseconds** (`bson_metric.go:119`, `util.go:95`) — note that `ftdc.WriteCSV` renders them as whole-second RFC3339 and destroys this precision, which is one of several reasons the oracle does not use it (§7). Implement with a documented fallback chain — `start`, then `serverStatus.localTime` — and fail loudly if neither is present rather than silently synthesising a time axis. The column is not guaranteed to be at index 0 across all server versions; look it up by path. Samples are *nominally* 1 s apart but **do not assume it**. Derive every sample's time from the column. Irregular spacing and inter-chunk gaps are real signal — a gap means mongod was down, stalled, or the host froze. Preserve gaps; never reindex to a synthetic uniform grid. ## 6. Schema drift across chunks Consecutive chunks can carry different reference documents — a version upgrade, a storage engine change, a replica-set member added or removed, a feature toggled. Column *count* and column *order* both change. ### ⚠ A dotted path is not a unique identifier BSON permits duplicate keys, and real captures contain them. Observed on a WSL host with two mounts at the same mountpoint: ``` 2x systemMetrics.mounts./run/user.capacity 2x systemMetrics.mounts./run/user.available 2x systemMetrics.mounts./run/user.free ``` Three duplicated paths out of 2,203 — rare, but enough to corrupt any consumer that treats the key list as a set. `metricsCount` counts *columns*, so the duplicates each occupy their own column and carry their own data. The decoder must stay faithful and emit both columns; deduplicating there would break equality with the reference. Disambiguation belongs one layer up, in whatever addresses series by name — Big Hole suffixes collisions within a chunk (`path`, `path#1`). Note that a suffixed path is only as stable as document order, exactly like the array-index paths below. ### ⚠ Metric names contain characters that break naive parsers Anything that accepts a metric path as *text* — a query language, a config file, a URL — has to cope with all of this. Counts are from one 2,573-path capture: | Hazard | Count | Example | |---|---|---| | embedded parentheses | 80 | `systemMetrics.memory.Active(anon)_kb` | | **trailing** space | 11 | `serverStatus.wiredTiger.reconciliation.pages written including an aggregated newest start durable timestamp ` | | embedded spaces | many | `serverStatus.wiredTiger.cache.bytes currently in the cache` | | slashes | many | `systemMetrics.mounts./run/user.free` | Two of these are actively dangerous: - **Parentheses.** A path may end with `)` — `...checkpoint prepare max time (msecs)` — so `name(...)` cannot be assumed to be a function call. Resolve by checking the prefix against a known function list and treating anything else as part of the path. - **Trailing whitespace is significant.** A reflexive `.trim()` makes those 11 metrics permanently unresolvable, and the symptom is "no such metric" rather than a parse error. **Leading** whitespace was never observed on any path, so stripping only the front is safe. Rules: - Merge across chunks **by dotted path**, never by column index. - A path absent from a chunk produces `NaN` for that chunk's sample range. Do not shift, do not forward-fill during decode. (Forward-fill is a *presentation* choice, decided per panel, and it is wrong for gauges.) - Array-index paths are unstable by nature: `replSetGetStatus.members.2.*` may refer to a different host after a reconfig. When a chunk's member array changes, re-map by `members.N.name` rather than trusting the index. ## 7. Test strategy — implemented, see `tools/oracle/` Full-matrix equality against MongoDB's own decoder. Not a spot-check: CORRECTIONS 2 and 4 both produce output that looks entirely reasonable on a handful of sampled values and is wrong everywhere. ### ⚠ Do not use `ftdc.WriteCSV` as the oracle The obvious choice is the shipped CSV exporter. It is unusable here, because its record writer is lossy in exactly the places our decoder is most likely to be wrong (`csv.go:25-34`): ```go case bsontype.Double, bsontype.Int32, bsontype.Int64, bsontype.Boolean, bsontype.Timestamp: fields[idx] = strconv.FormatInt(m.Values[i], 10) // Double as raw bit pattern case bsontype.DateTime: fields[idx] = time.Unix(m.Values[i]/1000, 0).Format(time.RFC3339) // ms precision lost } // other types -> empty string ``` - `Double` is emitted as the library's int64 for the column, which is mongod's value delta added to the reference's bit pattern (CORRECTION 1): neither the bit pattern nor the value. `ReadMetrics` has the same problem; the oracle corrects it. - `DateTime` is truncated to whole seconds — and the sample clock is a DateTime column (§5). - Any type outside the switch silently yields an empty string. **Use `ftdc.ReadChunks` with `chunk.Iterator` instead**, which is what `ReadMetrics` does inside. It runs `restoreFlat` (`bson_restore.go:100-115`) and yields per-sample documents with dotted keys and restored values. `tools/oracle/` does this, then replaces each Double with the int64 mongod stored, using the chunk's own starting value (CORRECTION 1). It emits JSONL with an ordered key list per schema, so column *order* is verified alongside values. ### Fixture coverage `tools/fixtures/generate.sh` produces these from a local mongod. Fast-sampling (`diagnosticDataCollectionPeriodMillis=100`) cuts chunk time from 5 min to 30 s. | Fixture | Covers | Status | |---|---|---| | `busy-replset` | dense deltas; BSON Timestamps via `replSetGetStatus.optimes.*.ts` + `.ts.inc` (CORRECTION 2); schema drift (§6) | ✅ 1541 samples, 5 schemas | | `idle` | long zero runs across column boundaries (CORRECTION 4) | ✅ 1500 samples | | `interim` | truncated trailing chunk (§1) | ✅ 251 samples | | Double columns (CORRECTION 1) | present in all three | ✅ 23 double columns; NaN, ±Inf and ±2^63 seeds covered by `tests/doubleSeed.test.ts`, not by a fixture | | major-version upgrade | cross-version metric renames | ❌ needs a second mongod version | The drift in `busy-replset` arises naturally: `replSetGetStatus` holds 4 columns before `rs.initiate()` and 59 after, so the reference document reshapes mid-file and the schema grows from 1,685 to 2,571 columns. That exercises merge-by-path, though not cross-version renames. ### Observed shape of a real capture From `busy-replset` chunk 0 (mongod 6.0.26, 1,685 columns): | | count | share | |---|---|---| | `int64` | 1,228 | 72.9% | | `int32` | 407 | 24.2% | | `double` | 23 | **1.4%** | | `bool` | 16 | 0.9% | | `datetime` | 11 | 0.7% | Sections: `serverStatus` 1,263 · `systemMetrics` 413 · `replSetGetStatus` 4 (pre-initiate) · `local` 3 · `start`/`end` 2. **Doubles are 1.4% of columns**, and since mongod stores them as int64 (CORRECTION 1) they need no path of their own. Every column, whatever its type, accumulates as an exact int64 in two 32-bit halves (CORRECTION 3). --- ## 8. Units FTDC carries no unit metadata. Every value is a bare number, so a viewer either knows what mongod meant or renders something authoritative-looking and wrong — which is worse than rendering nothing. These are taken from mongod's own collectors rather than inferred from metric names. File references are to `mongodb/mongo` at `v8.0`. | Metric | Actual unit | Source | |---|---|---| | `serverStatus.mem.{resident,virtual}` | **MiB** | `util/processinfo.h` — `getResidentSize()` / `getVirtualMemorySize()` are both documented `@return mbytes` | | `systemMetrics.memory.*_kb` | **kB** | `util/procparser.cpp` — `parseProcMemInfoFile` appends `_kb` *only* when /proc/meminfo reports the kB token, so the suffix is a reliable marker | | `systemMetrics.cpu.*_ms` | **ms**, already normalised | `util/procparser.cpp` — `convertTicksToMilliSeconds` divides USER_HZ (`sysconf(_SC_CLK_TCK)`) before FTDC sees it, so no further scaling is needed | | `systemMetrics.disks.*_sectors` | **512-byte sectors** | `util/procparser.cpp` — `kDiskFields` names /proc/diskstats columns verbatim with no conversion; Linux always reports those in 512-byte units regardless of physical block size | | `systemMetrics.disks.*_time_ms`, `io_time_ms`, `io_queued_ms` | **ms** | same table | | `serverStatus.opLatencies.*.latency` | **µs** | cumulative; pair with `.ops` for a per-operation average | | `serverStatus.uptime` | **seconds** | | | `replSetGetStatus.members.*.pingMs` | **ms** | integer, so sub-millisecond links read as 0 | ### Dimensional rules Two derived forms recur often enough to be worth stating: - **A rate over a rate cancels the per-second.** `rate(write_time_ms) / rate(writes)` is milliseconds *per write* — iostat's `await`. Same shape gives average operation latency from `opLatencies`. Treating the result as a bare count loses the unit entirely. - **Time accumulated per unit time is dimensionless.** 1000 ms/s is one core, or one device, fully busy — so `× 0.1` expresses it as a percentage. That is how CPU usage and iostat's `%util` are conventionally read, and it is why the templates carry an explicit `scale(..., 0.1)`. ### Counters vs gauges A gauge is an instantaneous reading; differencing it is meaningless. This matters because the upstream Grafana dashboard applies `derivative()` per *panel*, so a gauge sharing a panel with counters gets differenced too — which is how `connections.current` came to read `0.5/s`. Gauges include: `.current`, `.available`, `.active`, `.out`, `.totalTickets`, `.queueLength`, `mem.*`, the WiredTiger cache size and dirty-bytes readings, `io_in_progress`, `cursor.open.*`, `.health`, `.state`, `pingMs`, `uptime`, and everything from /proc/meminfo. Verify with `npm run units -- `, which prints every dashboard series with its unit and a formatted median and peak against real data. ### Stale collectors produce real rate spikes A counter can go flat for minutes and then jump by the whole interval in one sample. Observed on a production 8.0 capture: `systemMetrics.cpu.idle_ms` sat unchanged for ~231 s and then advanced 2,309,002 ms in a single second, giving an apparent 230,900% CPU. This is not a decode error — the Go reference produces byte-identical values — and not a unit error. mongod collects `systemMetrics` on a separate path from the sample clock, so when that collector stalls the values repeat while `start` keeps ticking at 1 Hz, then catch up. Do **not** "fix" it by smoothing the rate. The staleness is itself diagnostic: a system-metrics collector blocked for four minutes on a host at 92% disk utilisation is evidence of IO starvation, and flattening it would erase the finding. A future insights rule should surface it explicitly ("collector stalled for N s") rather than hide it. Note that the default chart view is unaffected: downsampling plots bucket means, so a single outlier sample in a 760-sample bucket barely moves the line. The spike is only visible with the min/max range band enabled — which is exactly the tradeoff that band exists to expose.