monitor.rollup

export function rollup(samples: readonly MetricSample[], from: number, to: number, bucketSeconds: number): readonly Bucket[]

/** The samples with start <= at < end, aggregated. */
export interface Bucket {
  /** Unix seconds, included */
  readonly start: number;
  /** Unix seconds, excluded */
  readonly end: number;
  readonly count: number;
  /** null when the bucket is empty */
  readonly min: number | null;
  /** null when the bucket is empty */
  readonly max: number | null;
  /** sum / count, half-up (halves away from zero); null when empty */
  readonly avg: number | null;
  /** 0 when empty */
  readonly sum: number;
  /** value of the latest sample; null when empty */
  readonly last: number | null;
}

import { rollup } from "#fune/monitor.rollup@^1";

import { roundDiv } from "./math_round_div.ts";  ← from math.round-div ^1.0.0 · built alongside by fune
import { seriesWindow, type MetricSample } from "./monitor_series_window.ts";  ← from monitor.series-window ^1.0.0 · built alongside by fune
import { type Bucket } from "./monitor_rollup_types.ts";

const MAX_BUCKETS = 10000;

/**
 * One row per bucket from `from` to `to`, empty buckets included so a chart
 * shows gaps as gaps. Buckets are aligned to `from`; the last is clipped to `to`.
 */
export function rollup(samples: readonly MetricSample[], from: number, to: number, bucketSeconds: number): readonly Bucket[] {
  if (!Number.isInteger(bucketSeconds)) throw new RangeError("bucketSeconds must be a whole number of seconds");
  if (bucketSeconds < 1) throw new RangeError(`bucketSeconds must be at least 1, received ${bucketSeconds}`);
  const inside = seriesWindow(samples, from, to);
  const n = Math.ceil((to - from) / bucketSeconds);
  if (n > MAX_BUCKETS) throw new RangeError(`too many buckets: ${n}, at most ${MAX_BUCKETS}`);
  const out: Bucket[] = [];
  let j = 0;
  for (let i = 0; i < n; i++) {
    const start = from + i * bucketSeconds;
    const end = Math.min(start + bucketSeconds, to);
    let count = 0;
    let sum = 0;
    let min: number | null = null;
    let max: number | null = null;
    let last: number | null = null;
    while (j < inside.length && inside[j].at < end) {
      const v = inside[j].value;
      count += 1;
      sum += v;
      min = min === null || v < min ? v : min;
      max = max === null || v > max ? v : max;
      last = v;
      j++;
    }
    const avg = count === 0 ? null : roundDiv(sum, count, "half-up");
    out.push({ start, end, count, min, max, avg, sum, last });
  }
  return out;
}

Install

fune build

With that line in your source, in a TypeScript project (language typescript in fune.project), fune build resolves it and its 2 dependencies, pins them in fune.lock, downloads only the TypeScript package of each, and builds the code above into your project’s .fune/build, one readable file per capability with a header linking back here. Or pin a range in fune.project and build in one step:

fune add monitor.rollup

The manifest, vectors and README with only the TypeScript implementation. Install it without the registry with fune add ./monitor.rollup-1.0.0-typescript.fune, or fetch it from a terminal with fune pull monitor.rollup@1.0.0:typescript.

The whole function, every language, is one file too: monitor.rollup-1.0.0.fune, 15,684 bytes, sha256 24f1815aeec79e93ba09881a92cd6a2eea649de96822ffbc1de2eda986c78e0c. It installs into a project of any language.

// fune: before monitor.rollup

// fune: after monitor.rollup

// fune: replace math.round-div in monitor.rollup
// fune: replace monitor.series-window in monitor.rollup

// fune: step monitor.rollup after <n|label>

More from the author

Buckets start at `from` and step by `bucketSeconds`, so they are aligned to `from`, not to the epoch: pass a `from` on a minute or hour boundary to get round buckets. Each is half-open, `start <= at < end`, like `monitor.series-window`, so no sample lands in two buckets. The last bucket is clipped at `to` when the window is not a whole number of buckets.

Empty buckets are returned too (count 0, sum 0, the rest null). A chart then shows a gap where data is missing instead of drawing a line straight across it, and every result for the same window has the same number of rows.

`from == to` gives no buckets. More than 10000 buckets is refused: that is almost always a bucket size in the wrong unit (seconds for minutes).

## Average

`avg` is `sum / count` rounded half up with `math.round-div`, whose half-up rounds halves away from zero: -1 and -2 average to -2, as 1 and 2 average to 2 (`Math.round(-1.5)` in JavaScript gives -1). Keep the `sum` and `count` if you need to combine buckets later: averaging averages is wrong when counts differ.

## Errors

- `bucketSeconds must be at least 1, received 0` - `bucketSeconds must be a whole number of seconds` - `too many buckets: 10001, at most 10000` - from `monitor.series-window`: `from must not be after to: 200 > 100`, `samples must be in strictly ascending time order: 5 follows 10`, `from and to must be whole seconds`

Files