# `ExDataSketch.Telemetry.Metrics`
[🔗](https://github.com/thanos/ex_data_sketch/blob/main/lib/ex_data_sketch/telemetry/metrics.ex#L1)

Ready-made `Telemetry.Metrics` definitions for every ExDataSketch
telemetry event.

Pass `all/1`'s result straight to a `Telemetry.Metrics` reporter (the
`Telemetry.Metrics.ConsoleReporter` built into the `:telemetry_metrics`
package, `TelemetryMetricsPrometheus`, `TelemetryMetricsStatsd`, or
Phoenix LiveDashboard's own metrics page) instead of hand-writing a
metric per event.

## Usage

    # In a Phoenix application's telemetry.ex:
    def metrics do
      ExDataSketch.Telemetry.Metrics.all() ++ [
        # ... your application's own metrics
      ]
    end

See `ExDataSketch.Telemetry`'s moduledoc for the full event/measurement/
metadata table this module's metric list is derived from.

## Coverage

Every event `ExDataSketch.Telemetry.all_event_names/0` returns has at
least one metric here: a `summary` for each numeric measurement it
carries, or a `counter` (an event-occurrence count) when it carries
none. `[:ex_data_sketch, :stream, :reduce]` is the only event with no
measurements at all, so it is the only event that gets a counter purely
for coverage; `[:ex_data_sketch, :sketch, :ingest]` additionally gets a
counter alongside its duration/size_bytes summaries as a call-volume
metric for the library's most common operation.

## What is deliberately not a metric here

- `pipeline.accumulate`'s `batch_size` metadata is not a tag on any
  metric -- it is a per-call variable integer, and tagging by it would
  explode cardinality in a real reporter (StatsD, Prometheus). Build a
  custom metric with `Telemetry.Metrics.summary/2` directly if you need
  it.
- `window.roll`'s `oldest_age_ms` is metadata describing the dropped
  slot's age, not a measurement in the `:telemetry.execute/3`
  measurements map, so no `Telemetry.Metrics` definition can read it.
- `persistence.delete` has no `sketch_type` tag: the sketch struct is
  already discarded by the time that event fires (see
  `ExDataSketch.Telemetry`'s moduledoc).

# `opts`

```elixir
@type opts() :: [{:prefix, String.t()}]
```

Options accepted by `all/1`.

# `all`

```elixir
@spec all(opts()) :: [Telemetry.Metrics.t()]
```

Returns a `Telemetry.Metrics` definition for every event
`ExDataSketch.Telemetry.all_event_names/0` returns.

## Options

- `:prefix` -- the dot-separated namespace prepended to every metric
  name (default: `"ex_data_sketch"`). Useful when running more than one
  ExDataSketch-backed component that needs distinct metric namespaces in
  a shared reporter. Only the metric's display name changes -- the
  underlying `:telemetry` event listened to is always the real,
  unprefixed `[:ex_data_sketch, ...]` event name, so metrics still fire
  regardless of this option.

## Examples

    iex> metrics = ExDataSketch.Telemetry.Metrics.all()
    iex> length(metrics) > 0
    true
    iex> Enum.all?(metrics, fn m -> match?(%Telemetry.Metrics.Summary{}, m) or match?(%Telemetry.Metrics.Counter{}, m) end)
    true

    iex> metrics = ExDataSketch.Telemetry.Metrics.all(prefix: "my_app")
    iex> [metric | _] = metrics
    iex> String.starts_with?(metric.name |> Enum.join("."), "my_app.")
    true

---

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