# `Mobius.Data`
[🔗](https://github.com/mobius-home/mobius/blob/v0.8.0/lib/mobius/data.ex#L1)

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:

  * `summary_windows/3` — per-window summary statistics, each window carrying
    `average`, `std_dev`, **and** `reports` (the number of observations that
    fell into that window).
  * `metrics/4` — the raw, un-delta'd rows of `t:Mobius.metric/0` for a metric
    over a window, filtered by name / type / tags.
  * `histogram/3` — the reconstructed `t:Mobius.DDSketch.t/0` for a histogram
    metric over a window, with `quantile/4`, `quantiles/4`, `count_below/4`,
    and `count_above/4` as ready-made queries on top of it.

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.

# `metric_type`

```elixir
@type metric_type() :: Mobius.metric_type() | {:summary, atom()}
```

A metric type to query: a plain `t:Mobius.metric_type/0` (`:counter`,
`:last_value`, `:sum`, `:summary`), or a summary field such as
`{:summary, :average}`.

# `opt`

```elixir
@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`

```elixir
@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

# `count_above`

```elixir
@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`

```elixir
@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`

```elixir
@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`

```elixir
@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 `t: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`

```elixir
@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`

```elixir
@spec quantiles(Mobius.metric_name(), [float()], map(), [opt()]) ::
  {:ok, %{required(float()) =&gt; 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`

```elixir
@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}, ...]}

---

*Consult [api-reference.md](api-reference.md) for complete listing*
