# `Nebulex.Adapters.Common.Info.Stats`
[🔗](https://github.com/elixir-nebulex/nebulex/blob/v3.0.3/lib/nebulex/adapters/common/info/stats.ex#L1)

Stats implementation using [Erlang counters][erl_counters].

Adapters are directly responsible for implementing the `Nebulex.Adapter.Info`
behaviour and adding an info spec for stats. However, this module provides a
simple implementation for stats using [Erlang counters][erl_counters].

An info specification `stats` is added to the info data, which is a map
with the following keys or measurements:

  * `:hits` - The requested data is successfully retrieved from the cache.

  * `:misses` - When a system or application makes a request to retrieve
    data from a cache, but that specific data is not currently in cache
    memory. A cache miss occurs either because the data was never placed
    in the cache, or because the data was removed (“evicted”) from the
    cache by either the caching system itself or an external application
    that specifically made that eviction request.

  * `:evictions` - Eviction by the caching system itself occurs when
    space needs to be freed up to add new data to the cache, or if
    the time-to-live policy on the data expired.

  * `:expirations` - When the time-to-live policy on the data expired.

  * `:updates` - When existing data is successfully updated.

  * `:writes` - When data is inserted or overwritten.

  * `:deletions` - The data was intentionally removed by either the
    caching system or an external application that specifically made
    that deletion request.

See the `Nebulex.Adapters.Local` adapter and `Nebulex.Adapters.Common.Info`
for more information about the usage.

[erl_counters]: https://erlang.org/doc/man/counters.html

# `counter`

```elixir
@type counter() :: :counters.counters_ref()
```

Type for the counter

# `stat`

```elixir
@type stat() ::
  :hits | :misses | :evictions | :expirations | :writes | :updates | :deletions
```

The stat type

# `stats`

```elixir
@type stats() :: %{required(stat()) => integer()}
```

Stats type

# `count`

```elixir
@spec count(counter()) :: stats()
```

Returns a map with all counters/stats count.

## Examples

    Nebulex.Adapters.Common.Info.Stats.count(stats_counter)

# `count`

```elixir
@spec count(counter(), stat()) :: integer()
```

Returns the current count for the stats counter given by `stat`.

## Examples

    Nebulex.Adapters.Common.Info.Stats.count(stats_counter, :hits)

# `incr`

```elixir
@spec incr(counter(), atom() | [atom()], integer()) :: :ok
```

Increments counter(s) for the given stat(s) by `incr`.

## Examples

    Nebulex.Adapters.Common.Info.Stats.incr(stats_counter, :hits)

    Nebulex.Adapters.Common.Info.Stats.incr(stats_counter, :writes, 10)

    Nebulex.Adapters.Common.Info.Stats.incr(stats_counter, [:misses, :deletions])

# `init`

```elixir
@spec init(telemetry_prefix :: [atom()]) :: counter()
```

Returns the Erlang's counter to be used by the adapter for keeping the cache
stats. It also initiates the Telemetry handler for handling and/or updating
the cache stats in runtime under the hood.

Any adapter using `Nebulex.Adapters.Common.Info` implementation must call
this init function in the `c:Nebulex.Adapter.init/1` callback and include
the returned counter within the adapter metadata under the key
`:stats_counter`. See the `Nebulex.Adapters.Nil` for example.

## Example

    Nebulex.Adapters.Common.Info.Stats.init([:telemetry, :prefix])

# `new`

```elixir
@spec new() :: stats()
```

Convenience function for returning a map with all stats set to `0`.

---

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