Mobius.Data (Mobius v0.8.0)

Copy Markdown View Source

Programmatic access to Mobius's raw, unprocessed metric data.

Most callers want Mobius.Charts: it runs the common transforms — sorted histogram bars, a line per quantile over time, the latest value per metric — and hands back chart-ready shapes. Reach for Mobius.Data when you need the underlying data itself, unprocessed, to do something Charts doesn't: feed an alerting rule, an SLO check, a report, or any further computation of your own.

Mobius.Data returns plain, flat maps — no plotting envelope — with absolute second-resolution timestamps and raw numeric values:

Every function accepts the same window options as Mobius.Charts (:last, :from/:to, :mobius_instance); they resolve identically.

Built for unattended use: every function returns an :ok/:error tuple and never raises or exits on a stored-data or availability problem. When the Mobius instance is down or too busy to answer (for example while it is restarting), the result is {:error, :unavailable} rather than a caller crash.

Summary

Types

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 window's summary statistics.

Functions

Count of observations strictly above threshold in the window.

Count of observations strictly below threshold in the window.

Reconstruct a Mobius.DDSketch histogram for a metric over a window.

The raw, un-delta'd metric rows for a metric over a window.

Estimate the value at quantile q for a histogram metric over a window.

Batch quantile estimates: %{q => value}.

Per-window summary statistics for a summary metric, ascending by timestamp.

Types

metric_type()

@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}.

opt()

@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 last x, where x is an integer number of seconds or {integer(), Mobius.time_unit()}
  • :from / :to - explicit unix-second window bounds; each may be given alone — :from defaults to 0 (the beginning of stored history) and :to defaults to now

With no window option the last 3 minutes are used.

summary_window()

@type summary_window() :: %{
  timestamp: integer(),
  average: float(),
  std_dev: float(),
  reports: non_neg_integer()
}

One window's summary statistics.

  • :timestamp - the absolute unix-second timestamp the window ends on
  • :average - the mean of the observations in the window
  • :std_dev - the standard deviation of the observations in the window
  • :reports - the number of observations that fell into the window

Functions

count_above(metric_name, threshold, tags \\ %{}, opts \\ [])

@spec count_above(Mobius.metric_name(), number(), map(), [opt()]) ::
  {:ok, non_neg_integer()} | {:error, term()}

Count of observations strictly above threshold in the window.

count_below(metric_name, threshold, tags \\ %{}, opts \\ [])

@spec count_below(Mobius.metric_name(), number(), map(), [opt()]) ::
  {:ok, non_neg_integer()} | {:error, term()}

Count of observations strictly below threshold in the window.

For SLO-style queries, e.g. "how many requests met our 200 ms budget?"

histogram(metric_name, tags \\ %{}, opts \\ [])

@spec histogram(Mobius.metric_name(), map(), [opt()]) ::
  {:ok, Mobius.DDSketch.t()} | {:error, term()}

Reconstruct a Mobius.DDSketch histogram for a metric over a window.

The metric must have been registered with histograms enabled (reporter_options: [histogram: ...]). Returns {:ok, sketch} where the sketch reflects the observations attributable to the window only, or {:error, reason} when the metric is not histogram-enabled.

{:ok, sketch} = Mobius.Data.histogram("http.request.duration", %{}, last: {1, :hour})
p95 = Mobius.DDSketch.quantile(sketch, 0.95)

metrics(metric_name, type, tags \\ %{}, opts \\ [])

@spec metrics(Mobius.metric_name(), metric_type(), map(), [opt()]) ::
  {:ok, [Mobius.metric()]} | {:error, :unavailable}

The raw, un-delta'd metric rows for a metric over a window.

Returns {:ok, rows} where rows is a list of Mobius.metric/0 maps (%{timestamp:, name:, type:, value:, tags:}) — the stored data as captured at each scrape, with no windowing or delta arithmetic applied. Filtered by metric name, type, and tags.

For the :summary type each row's :value is the cumulative t:Mobius.Summary.t/0 map; for {:summary, field} it is that single field.

Mobius.Data.metrics("vm.memory.total", :last_value, %{}, last: 30)
# => {:ok, [%{timestamp: ..., name: "vm.memory.total", type: :last_value, value: 51_200_000, tags: %{}}, ...]}

quantile(metric_name, q, tags \\ %{}, opts \\ [])

@spec quantile(Mobius.metric_name(), float(), map(), [opt()]) ::
  {:ok, float() | nil} | {:error, term()}

Estimate the value at quantile q for a histogram metric over a window.

q is in [0.0, 1.0]. Returns {:ok, nil} when the window contains no observations. See histogram/3 for the metric requirements and window options.

quantiles(metric_name, qs, tags \\ %{}, opts \\ [])

@spec quantiles(Mobius.metric_name(), [float()], map(), [opt()]) ::
  {:ok, %{required(float()) => float() | nil}} | {:error, term()}

Batch quantile estimates: %{q => value}.

{:ok, %{0.5 => p50, 0.95 => p95, 0.99 => p99}} =
  Mobius.Data.quantiles("http.request.duration", [0.5, 0.95, 0.99])

summary_windows(metric_name, tags \\ %{}, opts \\ [])

@spec summary_windows(Mobius.metric_name(), map(), [opt()]) ::
  {:ok, [summary_window()]} | {:error, :unavailable}

Per-window summary statistics for a summary metric, ascending by timestamp.

The stored summary record is a cumulative accumulator (sum / sum-of-squares / report count since the metric started), so the statistics for any one window are the delta between consecutive stored snapshots — the same idea Mobius.DDSketch.delta/2 applies to histograms. Each returned map carries the average, std_dev, and reports (the subgroup size n) for just that window.

A snapshot interval with no new reports contributes no entry, and an interval across which the cumulative counters reset (e.g. after a reboot) is skipped, so every entry reflects real observations rather than artifacts of a reset.

Mobius.Data.summary_windows("http.request.duration", %{}, last: {1, :hour})
# => {:ok, [%{timestamp: 1_700_000_001, average: 12.4, std_dev: 3.1, reports: 18}, ...]}