# `Nebulex.Adapter.Stats`
[🔗](https://github.com/elixir-nebulex/nebulex/blob/v2.6.6/lib/nebulex/adapter/stats.ex#L1)

Specifies the stats API required from adapters.

Each adapter is responsible for providing support for stats by implementing
this behaviour. However, this module brings with a default implementation
using [Erlang counters][https://erlang.org/doc/man/counters.html], with all
callbacks overridable, which is supported by the built-in adapters.

See `Nebulex.Adapters.Local` for more information about how this can be used
from the adapter, and also [Nebulex Telemetry Guide][telemetry_guide] to learn
how to use the Cache with Telemetry.

[telemetry_guide]: http://hexdocs.pm/nebulex/telemetry.html

# `stats`

```elixir
@callback stats(Nebulex.Adapter.adapter_meta()) :: Nebulex.Stats.t() | nil
```

Returns `Nebulex.Stats.t()` with the current stats values.

If the stats are disabled for the cache, then `nil` is returned.

The adapter may also include additional custom measurements,
as well as metadata.

See `c:Nebulex.Cache.stats/0`.

# `incr`

```elixir
@spec incr(:counters.counters_ref() | nil, atom(), integer()) :: :ok
```

Increments the `counter`'s `stat_name` by the given `incr` value.

## Examples

    Nebulex.Adapter.Stats.incr(stats_counter, :hits)

    Nebulex.Adapter.Stats.incr(stats_counter, :writes, 10)

> **NOTE:** This function is usually called by the adapter in case it uses
  the default implementation; the adapter should feed `Nebulex.Stats.t()`
  counters.

See adapters documentation for more information about stats implementation.

# `init`

```elixir
@spec init(Keyword.t()) :: :counters.counters_ref() | nil
```

Initializes the Erlang's counter to be used by the adapter. See the module
documentation for more information about the stats default implementation.

Returns `nil` is the option `:stats` is set to `false` or it is not set at
all; the stats will be skipped.

## Example

    Nebulex.Adapter.Stats.init(opts)

> **NOTE:** This function is usually called by the adapter in case it uses
  the default implementation; the adapter should feed `Nebulex.Stats.t()`
  counters.

See adapters documentation for more information about stats implementation.

---

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