Cache Promote Plugin

The cache_promote plugin provides a means to control when an object should be allowed to enter the cache. This is orthogonal from normal Cache-Control directives, providing a different set of policies to apply. The typical use case for this plugin is when you have a very large data set, where you want to avoid churning the ATS cache for the long tail content.

All configuration is done via remap.config, and the following options are available:

--policy

The promotion policy. The values lru and chance are supported.

--sample

The sampling rate for the request to be considered

If --policy is set to lru the following options are also available:

--label

An optional label for this LRU, to allow sharing an LRU across multiple remap rules. Note: In order for an LRU to be used by multiple remap rules, not only must the label match, both the --hits and --buckets options must be identical.

--hits

The minimum number of requests before promotion.

--bytes

In addition to requests, also count bytes that are cache misses. If specified, default is 0, whichever triggers first of bytes and requests (hits) will cause promotion.

--buckets

The size (number of entries) of the LRU.

--stats-enable-with-id

Enables collecting statistics. The option requires an argument, the remap-identifier. The remap-identifier is a string that is concatenated to the stat name. The following stats are collected.

  • plugin.cache_promote.${remap-identifier}.cache_hits - Cache hit total, available for all policies.

  • plugin.cache_promote.${remap-identifier}.freelist_size - Size of the freelist when using the LRU policy.

  • plugin.cache_promote.${remap-identifier}.lru_size - Size of the LRU when using the LRU policy.

  • plugin.cache_promote.${remap-identifier}.lru_hit - LRU hit count when using the LRU policy.

  • plugin.cache_promote.${remap-identifier}.lru_miss - LRU miss count when using the LRU policy.

  • plugin.cache_promote.${remap-identifier}.lru_vacated - count of LRU entries removed to make room for a new request.

  • plugin.cache_promote.${remap-identifier}.promoted - count requests promoted, available in all policies.

  • plugin.cache_promote.${remap-identifier}.total_requests - count of all requests.

--internal-enabled

Allow cache promote to operate on internal (plugin-initiated) requests.

These options combined with your usage patterns will control how likely a URL is to become promoted to enter the cache.

Examples

These two examples shows how to use the chance and LRU policies, respectively:

map http://cdn.example.com/ http://some-server.example.com \
  @plugin=cache_promote.so @pparam=--policy=chance @pparam=--sample=10%

map http://cdn.example.com/ http://some-server.example.com \
  @plugin=cache_promote.so @pparam=--policy=lru \
  @pparam=--hits=10 @pparam=--buckets=10000

Note --sample is available for all policies and can be used to reduce pressure under heavy load.