Sys.Mon.Sampler behaviour (Hyper v0.1.0)

Copy Markdown View Source

Behaviour for a single soft-metric probe.

A sampler is the I/O-bearing source of instantaneous readings driven by Sys.Mon.Server. It may carry private state between samples (e.g. the previous /proc/stat snapshot needed to turn cumulative counters into a rate).

The sampler module fully describes its monitor: alongside the readings it declares its own schedule (period/0, tau/0), so Sys.Mon.Server.start_link(SamplerModule) needs nothing else.

A reading is whatever domain value the sampler chooses - a number or any Unit.Quantity (a Unit.Information for memory, a Unit.Bandwidth for throughput, a bare Float fraction for CPU) - so Sys.Mon.Server can low-pass-filter it and it flows out of the monitor unchanged, with no float-only bottleneck.

Summary

Types

private()

Sampler-private carry-over state.

reading()

An instantaneous reading: a number or any Unit.Quantity.

Callbacks

init()

Initialize sampler-private state.

period()

How often to sample.

sample(private)

Produce the next reading.

tau()

The low-pass filter time constant (the smoothing window, independent of period/0).

Types

private()

@type private() :: term()

Sampler-private carry-over state.

reading()

@type reading() :: number() | Unit.Quantity.t()

An instantaneous reading: a number or any Unit.Quantity.

Callbacks

init()

@callback init() :: {:ok, private()} | {:error, term()}

Initialize sampler-private state.

period()

@callback period() :: Unit.Time.t()

How often to sample.

sample(private)

@callback sample(private()) ::
  {:ok, reading(), private()} | {:skip, private()} | {:error, term()}

Produce the next reading.

:skip means a reading could not yet be formed (e.g. no baseline for a rate), and the filter is left untouched. :error is a transient failure to be logged.

tau()

@callback tau() :: Unit.Time.t()

The low-pass filter time constant (the smoothing window, independent of period/0).