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
andchance
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.