Skip to content

Metrics

collectors

Statistic collectors and the metrics registry.

Tally 

Tally(name: str, *, keep_values: bool = True, bins: int | Sequence[float] | None = None)

Summary statistics for a stream of observations (e.g. waiting times).

Mean and variance use Welford's numerically stable update. When keep_values is true the raw observations are retained so quantiles and histograms can be computed exactly.

TimeWeighted 

TimeWeighted(name: str, clock: Clock, initial: float = 0.0, *, record_series: bool = True, start: float | None = None)

A piecewise-constant quantity integrated over simulation time.

Typical uses: queue length, number of busy servers, work in progress. mean is the time average (1/T) * integral of value dt. If record_series is set, every change is stored as (time, value) for plotting.

Metrics 

Metrics(clock: Clock, *, keep_values: bool = True, record_series: bool = True)

Registry of named collectors.

  • observe(name, x) - one observation of a quantity (Tally)
  • histogram(name, x) - same, and the summary includes a histogram
  • record(name, x) - set a time-weighted level, e.g. WIP (TimeWeighted)
  • increment(name) - count occurrences; summary includes rate per time unit
  • set(name, x) - a final scalar (e.g. computed cost)

gauge 

gauge(name: str, initial: float = 0.0) -> TimeWeighted

Get or create a time-weighted level. A new gauge is backdated to the start of the statistics window with value initial.

record 

record(name: str, value: float) -> None

Set a level. If the gauge is new, it counts as 0 before this first record.

reset 

reset() -> None

Discard statistics gathered so far (e.g. at the end of a warm-up period).