Query-ready data structures for graphing Mobius metrics.
Mobius.Data returns the raw building blocks — a reconstructed
Mobius.DDSketch, a flat list of metric points, a per-quantile map. Turning
those into the shapes a chart actually wants (sorted histogram bars, a line
per quantile over time, the latest value per metric) is the same handful of
transforms re-written at every call site. This module does those transforms
once and hands back plain, well-typed maps.
Nothing here is tied to a particular renderer. Every function returns plain
maps and lists with absolute second-resolution timestamps and raw numeric
values; mapping those onto VegaLite, an ASCII chart, JSON, or anything else
is the caller's job and is a trivial Enum.map/2.
Four shapes, one per common query:
distribution/3— a histogram's bins as sorted{value, count}bars (distribution/0).quantiles_over_time/4— one line of{timestamp, value}points per requested quantile (quantiles_over_time/0).series/4— a single metric's values over time as{timestamp, value}points (series/0). Works for any metric type, including{:summary, :average}for an average-over-time line.latest/2— the most recent value for a set of metrics (latest_value/0).
All four accept the same window options (:last, :from/:to,
:mobius_instance; see opt/0) and report the resolved absolute window
back in the result so a caller can label axes without re-deriving it.
Summary
Types
One histogram bar: the bin's representative value and its observation count.
A metric's distribution over a window: the histogram bars plus context.
The most recent stored value for one metric.
One entry in the list of metrics available to chart.
A metric to request a latest value for: {name, type, tags}.
A metric type to query: a plain Mobius.metric_type/0 (:counter,
:last_value, :sum, :summary), or a summary field such as
{:summary, :average}.
Options shared by every query.
One point on a time line: a value at an absolute second-resolution timestamp.
One quantile's line over time.
Quantiles of a histogram metric tracked over a window.
A single metric's values over time.
The absolute window a result covers, as resolved unix-second bounds.
Functions
Project a histogram metric's distribution over a window into sorted bars.
The most recent stored value for each of several metrics.
List the metrics an instance is configured to track.
Track quantiles of a histogram metric across a window, one line per quantile.
A single metric's values over time as {timestamp, value} points.
Types
@type bin() :: %{value: float(), count: pos_integer()}
One histogram bar: the bin's representative value and its observation count.
value is the DDSketch bin estimator — the same value Mobius.DDSketch.quantile/2
reports for a value that lands in the bin. Bins are spaced geometrically, so
treat value as an ordered category rather than a linear coordinate when
plotting.
@type distribution() :: %{ metric: Mobius.metric_name(), tags: map(), window: window(), total_count: non_neg_integer(), bins: [bin()] }
A metric's distribution over a window: the histogram bars plus context.
:metric/:tags- what was queried:window- the resolved time window:total_count- total observations across all bins:bins- bars sorted ascending byvalue; empty when nothing was observed
@type latest_value() :: %{ metric: Mobius.metric_name(), type: metric_type(), tags: map(), value: number() | map(), timestamp: integer() }
The most recent stored value for one metric.
value is a number for plain types and summary fields; for the plain
:summary type it is the calculated %{average:, std_dev:, reports:} map.
@type metric_listing() :: %{ metric: Mobius.metric_name(), type: metric_type(), tags: [atom()], histogram?: boolean() }
One entry in the list of metrics available to chart.
:metric/:type/:tags- identity, ready to pass to the other queries (tagsis the list of configured tag keys):histogram?- whether adistribution/0is available for this metric (true only for summary metrics registered with histograms enabled)
@type metric_ref() :: {Mobius.metric_name(), metric_type()} | {Mobius.metric_name(), metric_type(), map()}
A metric to request a latest value for: {name, type, tags}.
@type metric_type() :: Mobius.metric_type() | {:summary, atom()}
A metric type to query: a plain Mobius.metric_type/0 (:counter,
:last_value, :sum, :summary), or a summary field such as
{:summary, :average}.
@type opt() :: {:mobius_instance, Mobius.instance()} | {:from, integer()} | {:to, integer()} | {:last, integer() | {integer(), Mobius.time_unit()}}
Options shared by every query.
:mobius_instance- the instance to query (default:mobius):last- window covering the lastx, wherexis an integer number of seconds or{integer(), Mobius.time_unit()}:from/:to- explicit unix-second window bounds; each may be given alone —:fromdefaults to 0 (the beginning of stored history) and:todefaults to now
With no window option the last 180 seconds are used.
One point on a time line: a value at an absolute second-resolution timestamp.
One quantile's line over time.
quantile is the requested fraction in [0.0, 1.0]; points are sorted
ascending by timestamp. Windows with no observations contribute no point, so
a sparse metric yields a shorter line rather than gaps of nil.
@type quantiles_over_time() :: %{ metric: Mobius.metric_name(), tags: map(), window: window(), lines: [quantile_line()] }
Quantiles of a histogram metric tracked over a window.
Each requested quantile becomes its own quantile_line/0, in the order the
quantiles were requested — ready to draw as one line per series. The window is
divided at the resolution Mobius actually stored (one point per stored
snapshot interval).
@type series() :: %{ metric: Mobius.metric_name(), type: metric_type(), tags: map(), window: window(), points: [point()] }
A single metric's values over time.
The absolute window a result covers, as resolved unix-second bounds.
Functions
@spec distribution(Mobius.metric_name(), map(), [opt()]) :: {:ok, distribution()} | {:error, term()}
Project a histogram metric's distribution over a window into sorted bars.
The metric must have been registered with histograms enabled
(reporter_options: [histogram: ...]). Returns {:error, reason} from
Mobius.Data.histogram/3 when it is not.
{:ok, dist} = Mobius.Charts.distribution("http.request.duration", %{}, last: {1, :hour})
# dist.bins => [%{value: 9.8, count: 412}, %{value: 11.0, count: 380}, ...]Plotting then needs no math — map :value/:count straight onto x/y.
@spec latest([metric_ref()], [opt()]) :: [latest_value()]
The most recent stored value for each of several metrics.
Each entry is {name, type} or {name, type, tags}. Metrics with no data in
the window are omitted, so the result is ready to render directly. Order
follows the input.
Mobius.Charts.latest(
[
{"vm.memory.total", :last_value},
{"vm.memory.processes", :last_value}
],
last: {5, :minute}
)
# => [%{metric: "vm.memory.total", value: 51_200_000, timestamp: ...}, ...]
@spec list_metrics(Mobius.instance()) :: [metric_listing()]
List the metrics an instance is configured to track.
Each entry carries the metric/type/tags needed to call the other
queries, plus histogram? so a caller knows whether distribution/3 is
available. Sourced from the configured Telemetry.Metrics definitions, so
metrics that have not reported a value yet are still listed.
Mobius.Charts.list_metrics()
# => [%{metric: "vm.memory.total", type: :last_value, tags: [], histogram?: false}, ...]
@spec quantiles_over_time(Mobius.metric_name(), [float()], map(), [opt()]) :: {:ok, quantiles_over_time()} | {:error, term()}
Track quantiles of a histogram metric across a window, one line per quantile.
quantiles is a list of fractions in [0.0, 1.0]. The window is split at the
resolution Mobius stored — each stored snapshot interval becomes one point,
carrying only the observations attributable to that interval. Windows with no
observations are skipped, so a quiet stretch shortens the line rather than
drawing a zero.
{:ok, qot} =
Mobius.Charts.quantiles_over_time("http.request.duration", [0.5, 0.95, 0.99], %{},
last: {1, :hour}
)
for line <- qot.lines do
# line.quantile => 0.95, line.points => [%{timestamp: ..., value: ...}, ...]
end
@spec series(Mobius.metric_name(), metric_type(), map(), [opt()]) :: {:ok, series()} | {:error, term()}
A single metric's values over time as {timestamp, value} points.
Accepts any metric_type/0. Use a plain type
(:last_value, :counter, :sum) for a gauge or counter line, or
{:summary, :average} / {:summary, :std_dev} / {:summary, :reports}
for a summary metric (plain :summary gives the full per-interval
%{average:, std_dev:, reports:} map, where reports is the subgroup
size n for that interval).
Summary statistics are per interval: the stored summary is a cumulative
accumulator (sum / sum-of-squares / count since the metric started), so each
point is computed from the delta between consecutive stored snapshots —
the same idea DDSketch.delta/2 applies to histograms. A snapshot interval
with no new reports contributes no point.
Returns {:error, :unavailable} when the instance is down or too busy to
answer (see Mobius.Data), and {:error, {:invalid_summary_field, field}}
for a summary field other than :average, :std_dev, or :reports.
{:ok, avg} = Mobius.Charts.series("http.request.duration", {:summary, :average}, %{}, last: {1, :hour})
# avg.points => [%{timestamp: ..., value: 12.4}, ...]