Nebulex.Adapters.Common.Info.Stats (Nebulex v3.0.0-rc.1)

View Source

Stats implementation using Erlang 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.

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.

Summary

Types

Type for the counter

The stat type

Stats type

Functions

Returns a map with all counters/stats count.

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

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

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.

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

Types

counter()

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

Type for the counter

stat()

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

The stat type

stats()

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

Stats type

Functions

count(ref)

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

Returns a map with all counters/stats count.

Examples

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

count(ref, stat)

@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(counter, stats, incr \\ 1)

@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(telemetry_prefix)

@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 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()

@spec new() :: stats()

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