This module defines the supported built-in stats.

By default, each adapter is responsible for providing stats support. However, Nebulex suggests supporting the built-in stats described in this module, which are also supported by the built-in adapters.

Usage

First of all, we define a cache:

defmodule MyApp.Cache do
  use Nebulex.Cache,
    otp_app: :nebulex,
    adapter: Nebulex.Adapters.Local
end

Then we configure it enabling the stats, like so:

config :my_app, MyApp.Cache,
  stats: true,
  gc_interval: 86_400_000, #=> 1 day
  max_size: 200_000,
  gc_cleanup_min_timeout: 10_000,
  gc_cleanup_max_timeout: 900_000

Remember to add the cache on your application's supervision tree.

Since we are using a built-in adapter and the stats have been enabled (stats: true), the stat counters will be automatically fed by the adapter.

You can ask for the current stats values at any time by calling:

Nebulex.Cache.Stats.info(MyApp.Cache)

Using stats helpers

You can inject the stats helpers in the cache like this:

defmodule MyApp.Cache do
  use Nebulex.Cache,
    otp_app: :nebulex,
    adapter: Nebulex.Adapters.Local

  # Use stats helpers
  use Nebulex.Cache.Stats
end

Retrieving stats info

MyApp.Cache.stats_info()

By calling this injected helper, the function Nebulex.Cache.Stats.info/1 is called under-the-hood, but the cache name is resolved automatically.

Dispatching telemetry events

MyApp.Cache.dispatch_stats()

MyApp.Cache.dispatch_stats(event_prefix: [:my_cache, :stats])

By calling this injected helper, the function Nebulex.Cache.Stats.dispatch/2 is called under-the-hood, but the cache name is resolved automatically.

Telemetry events

Integrating telemetry is very easy since with the helper function MyApp.Cache.dispatch_stats/1 (via the __using__ macro) described previously you can emit telemetry events with the current stats at any time. What we need to resolve is, how to make it in such a way that every X period of time the stats are emitted automatically.

To do so, we can use :telemetry_poller and define a custom measurement:

:telemetry_poller.start_link(
  measurements: [
    {MyApp.Cache, :dispatch_stats, []},
  ],
  # configure sampling period - default is :timer.seconds(5)
  period: :timer.seconds(10),
  name: :my_cache_stats_poller
)

Or you can also start the :telemetry_poller process along with your application supervision tree, like so:

def start(_type, _args) do
  my_cache_stats_poller_opts = [
    measurements: [
      {MyApp.Cache, :dispatch_stats, []},
    ],
    period: :timer.seconds(10),
    name: :my_cache_stats_poller
  ]

  children = [
    {MyApp.Cache, []},
    {:telemetry_poller, my_cache_stats_poller_opts}
  ]

  opts = [strategy: :one_for_one, name: MyApp.Supervisor]
  Supervisor.start_link(children, opts)
end

See Nebulex Telemetry Guide.