Skip to content

KAZOO Support Channels

This documentation is curated by 2600Hz as part of the KAZOO open source project. Join our community forums here for peer support. Only features in the space are included as part of our 2600Hz Support Services plan.

Kazoo Caches#

The kz_cache interface exposes an LRU cache for storing Erlang terms in an ETS table.

This is heavily used to cache document lookups from CouchDB but is generally useful.

Features of the cache#

Expiring entries#

When stored with {'expires', timeout()} where timeout() is in seconds or 'infinity', the cache entry will stay in the cache until after timeout() seconds have elapsed.


The cache will check for expired entries, by default, based on the EXPIRE_PERIOD_MS macro in the header. Caches can be started with alternate expiration timeouts. Lower timeouts mean more work being done to expire caches but entries are evicted closer to the expected timeout; higher timeouts mean less work but an expired cache entry may exist after expiration.


The cache has a gen_listener process that can subscribe for document-change notices via AMQP (like when a document is successfully saved/deleted from CouchDB). This allows the cache to be programmatically flushed for entries that are no longer valid.


Cache entries can have associated callbacks for various stages in the cache entry's lifecycle.

Include a callback function when storing a key/value pair:

kz_cache:store_local(CacheName, <<"key">>, <<"value">>, [{'callback', fun some_callback/3}]).

The callback function will receive three arguments:

some_callback(Key, Value, CallbackReason).

CallbackReason can be one of 'expire', 'erase', 'flush', 'timeout', or 'store'.


Monitor timer expires. Currently this isn't possible to be reached as the only monitor keys are for the wait_for_ functions.


Cache entries that have expired


Cache entries are erased


Cache entries are flushed


A cache entry is stored

Code layout#


API module


Enforces the expiration of cache entries


ETS table manipulations


Callbacks executed on various events in the cache


AMQP listener for document changes, if configured


kz_nodes listener for new/expiring nodes


Callbacks processor module


If a cache entry is stored with {'monitor', 'true'} or {'monitor', [pid()]}, kz_cache_process will monitor the PID(s) and remove cache entries if the PID(s) die.

ETS architecture#

Main ETS table#

Tracks the cache entry, expiration time, etc

Monitor ETS table#

Certain situations where processes can monitor a cache key (wait_for_* functions).

Pointer ETS table#

Tracks the AMQP bindings associated with the key for automatic flushing.

Cache Strategies#

See what strategy a node is using:

sup kazoo_data_maintenance cache_strategy
             strategy: none
  stampede mitigation: false
          async store: false


This strategy does not use stampede mitigation and uses a blocking store operation.

sup kazoo_data_maintenance set_cache_strategy none


This strategy does not use stampede mitigation and uses a non-blocking store operation.

sup kazoo_data_maintenance set_cache_strategy async


This strategy uses stampede mitigation and uses a blocking store operation

sup kazoo_data_maintenance set_cache_strategy stampede

Stampede Async#

When the cache entry is missing, the database operation will proceed. However, when it comes time to cache the value, the key is locked until the store operation is successful. When a competing process tries to cache its value and sees the locked key, it will noop the store and continue on with life.

Essentially, the winning process will lock-then-async-store the cache value. All other processes will noop-store and continue, thus avoiding messages to the cache process mailbox.

sup kazoo_data_maintenance set_cache_strategy stampede_async


[ ] Move callback processing to alternative module [ ] Monitor kz_cache mailbox during load tests (maybe dbg?)