monitor.rollup

def rollup(samples: Sequence[MetricSample], from_: int, to: int, bucket_seconds: int) -> List[Bucket]

@dataclass(frozen=True)
class Bucket:
    """The samples with start <= at < end, aggregated."""

    #: Unix seconds, included
    start: int
    #: Unix seconds, excluded
    end: int
    count: int
    #: null when the bucket is empty
    min: Optional[int]
    #: null when the bucket is empty
    max: Optional[int]
    #: sum / count, half-up (halves away from zero); null when empty
    avg: Optional[int]
    #: 0 when empty
    sum: int
    #: value of the latest sample; null when empty
    last: Optional[int]

from fune.monitor.rollup import rollup  # monitor.rollup@^1

from typing import List, Optional, Sequence

from .math_round_div import round_div  ← from math.round-div ^1.0.0 · built alongside by fune
from .monitor_series_window import MetricSample, series_window  ← from monitor.series-window ^1.0.0 · built alongside by fune
from .monitor_rollup_types import Bucket

_MAX_BUCKETS = 10000


def rollup(samples: Sequence[MetricSample], from_: int, to: int, bucket_seconds: int) -> List[Bucket]:
    """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`."""
    if not isinstance(bucket_seconds, int) or isinstance(bucket_seconds, bool):
        raise ValueError("bucketSeconds must be a whole number of seconds")
    if bucket_seconds < 1:
        raise ValueError("bucketSeconds must be at least 1, received %d" % bucket_seconds)
    inside = series_window(samples, from_, to)
    n = -((from_ - to) // bucket_seconds)
    if n > _MAX_BUCKETS:
        raise ValueError("too many buckets: %d, at most %d" % (n, _MAX_BUCKETS))
    out: List[Bucket] = []
    j = 0
    for i in range(n):
        start = from_ + i * bucket_seconds
        end = min(start + bucket_seconds, to)
        count = 0
        total = 0
        lo: Optional[int] = None
        hi: Optional[int] = None
        last: Optional[int] = None
        while j < len(inside) and inside[j].at < end:
            v = inside[j].value
            count += 1
            total += v
            lo = v if lo is None or v < lo else lo
            hi = v if hi is None or v > hi else hi
            last = v
            j += 1
        avg = None if count == 0 else round_div(total, count, "half-up")
        out.append(Bucket(start=start, end=end, count=count, min=lo, max=hi, avg=avg, sum=total, last=last))
    return out

Install

fune build

With that line in your source, in a Python project (language python in fune.project), fune build resolves it and its 2 dependencies, pins them in fune.lock, downloads only the Python 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 Python implementation. Install it without the registry with fune add ./monitor.rollup-1.0.0-python.fune, or fetch it from a terminal with fune pull monitor.rollup@1.0.0:python.

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