# `SuperCache.Cluster.Metrics`
[🔗](https://github.com/ohhi-vn/super_cache/blob/main/lib/cluster/metrics.ex#L1)

Low-overhead counter and latency-sample store for SuperCache observability.

All state is held in a single `:public` ETS table owned by this GenServer.
Writes use `update_counter/3` (atomic) and are safe to call from any
process without coordination overhead.

## Counter keys

Counters are stored as `{namespace, field}` tuples:

    {:tpc, :committed}
    {:tpc, :aborted}
    {:api, :put}, :calls}          # note: nested via get_all/1
    {{:api, :put}, :errors}

## Latency samples

Latency ring buffers are stored as `{:latency, key}` records holding a
list of the most recent `@max_samples` microsecond values.  The list is
bounded so memory usage is constant regardless of call volume.

## Usage

    # In Router / Replicator — after an operation completes:
    Metrics.increment({:api, :put}, :calls)
    Metrics.push_latency({:api_latency_us, :put}, elapsed_us)

    # Reading back:
    Metrics.get_all({:api, :put})
    # => %{calls: 1_200, errors: 2}

    Metrics.get_latency_samples({:api_latency_us, :put})
    # => [45, 110, 88, ...]

# `child_spec`

Returns a specification to start this module under a supervisor.

See `Supervisor`.

# `get_all`

```elixir
@spec get_all(term()) :: map()
```

Return all counters for `namespace` as `%{field => count}`.

# `get_latency_samples`

```elixir
@spec get_latency_samples(term()) :: [non_neg_integer()]
```

Return all latency samples for `key` (unordered).

# `increment`

```elixir
@spec increment(term(), atom()) :: integer()
```

Atomically increment counter `field` under `namespace` by 1.

# `push_latency`

```elixir
@spec push_latency(term(), non_neg_integer()) :: :ok
```

Push a latency sample (microseconds) into the ring buffer for `key`.

The buffer is capped at 256 entries; oldest samples are
dropped when the cap is reached.

# `reset`

```elixir
@spec reset(term()) :: :ok
```

Reset all counters and latency samples for `namespace`.

# `start_link`

---

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