includes/libs/objectcache/README.md

   1 # wikimedia/objectcache
   2
   3 ## Statistics
   4
   5 Sent to StatsD under MediaWiki's namespace.
   6
   7 ### WANObjectCache
   8
   9 The default WANObjectCache provided by MediaWikiServices disables these
  10 statistics in processes where `$wgCommandLineMode` is true.
  11
  12 #### `wanobjectcache.{kClass}.{cache_action_and_result}`
  13
  14 Call counter from `WANObjectCache::getWithSetCallback()`.
  15
  16 * Type: Counter.
  17 * Variable `kClass`: The first part of your cache key.
  18 * Variable `result`: One of:
  19   * `"hit.good"`,
  20   * `"hit.refresh"`,
  21   * `"hit.volatile"`,
  22   * `"hit.stale"`,
  23   * `"miss.busy"` (or `"renew.busy"`, if the `minAsOf` is used),
  24   * `"miss.compute"` (or `"renew.busy"`, if the `minAsOf` is used).
  25
  26 #### `wanobjectcache.{kClass}.regen_set_delay`
  27
  28 Upon cache miss, this measures the time spent in `WANObjectCache::getWithSetCallback()`,
  29 from the start of the method to right after the new value has been computed by the callback.
  30
  31 This essentially measures the whole method (including retrieval of any old value,
  32 validation, any locks for `lockTSE`, and the callbacks), except for the time spent
  33 in sending the value to the backend server.
  34
  35 * Type: Measure (in milliseconds).
  36 * Variable `kClass`: The first part of your cache key.
  37
  38 #### `wanobjectcache.{kClass}.regen_walltime`
  39
  40 Upon cache miss, this measures the time spent in `WANObjectCache::getWithSetCallback()`
  41 from the start of the callback to right after the new value has been computed.
  42
  43 * Type: Measure (in milliseconds).
  44 * Variable `kClass`: The first part of your cache key.
  45
  46 #### `wanobjectcache.{kClass}.ck_touch.{result}`
  47
  48 Call counter from `WANObjectCache::touchCheckKey()`.
  49
  50 * Type: Counter.
  51 * Variable `kClass`: The first part of your cache key.
  52 * Variable `result`: One of `"ok"` or `"error"`.
  53
  54 #### `wanobjectcache.{kClass}.ck_reset.{result}`
  55
  56 Call counter from `WANObjectCache::resetCheckKey()`.
  57
  58 * Type: Counter.
  59 * Variable `kClass`: The first part of your cache key.
  60 * Variable `result`: One of `"ok"` or `"error"`.
  61
  62 #### `wanobjectcache.{kClass}.delete.{result}`
  63
  64 Call counter from `WANObjectCache::delete()`.
  65
  66 * Type: Counter.
  67 * Variable `kClass`: The first part of your cache key.
  68 * Variable `result`: One of `"ok"` or `"error"`.
  69
  70 #### `wanobjectcache.{kClass}.cooloff_bounce`
  71
  72 Upon a cache miss, the `WANObjectCache::getWithSetCallback()` method generally
  73 recomputes the value from the callback, and stores it for re-use.
  74
  75 If regenerating the value costs more than a certain threshold of time (e.g. 50ms),
  76 then for popular keys it is likely that many web servers will generate and store
  77 the value simultaneously when the key is entirely absent from the cache. In this case,
  78 the cool-off feature can be used to protect backend cache servers against network
  79 congestion. This protection is implemented with a lock and subsequent cool-off period.
  80 The winner stores their value, while other web server return their value directly.
  81
  82 This counter is incremented whenever a new value was regenerated but not stored.
  83
  84 * Type: Counter.
  85 * Variable `kClass`: The first part of your cache key.
  86
  87 When the regeneration callback is slow, these scenarios may use the cool-off feature:
  88
  89 * Storing the first interim value for tombstoned keys.
  90
  91   If a key is currently tombstoned due to a recent `delete()` action, and thus in "hold-off", then
  92   the key may not be written to. A mutex lock will let one web server generate the new value and
  93   (until the hold-off is over) the generated value will be considered an interim (temporary) value
  94   only. Requests that cannot get the lock will use the last stored interim value.
  95   If there is no interim value yet, then requests that cannot get the lock may still generate their
  96   own value. Here, the cool-off feature is used to decide which requests stores their interim value.
  97
  98 * Storing the first interim value for stale keys.
  99
 100   If a key is currently in "hold-off" due to a recent `touchCheckKey()` action, then the key may
 101   not be written to. A mutex lock will let one web request generate the new value and (until the
 102   hold-off is over) such value will be considered an interim (temporary) value only. Requests that
 103   lose the lock, will instead return the last stored interim value, or (if it remained in cache) the
 104   stale value preserved from before `touchCheckKey()` was called.
 105   If there is no stale value and no interim value yet, then multiple requests may need to
 106   generate the value simultaneously. In this case, the cool-off feature is used to decide
 107   which requests store their interim value.
 108
 109   The same logic applies when the callback passed to getWithSetCallback() in the "touchedCallback"
 110   parameter starts returning an updated timestamp due to a dependency change.
 111
 112 * Storing the first value when `lockTSE` is used.
 113
 114   When `lockTSE` is in use, and no stale value is found on the backend, and no `busyValue`
 115   callback is provided, then multiple requests may generate the value simultaneously;
 116   the cool-off is used to decide which requests store their interim value.