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 entry points where MW_ENTRY_POINT is 'cli'.
  11
  12 #### `wanobjectcache.{kClass}.{cache_action_and_result}`
  13
  14 Upon cache access via `WANObjectCache::getWithSetCallback()`, this measures the total time spent
  15 in this method from start to end for all cases, except process-cache hits.
  16
  17 See also `wanobjectcache.{kClass}.regen_walltime`, which, during misses/renews, measures just the
  18 portion of time spent in the callback to regenerate the value.
  19
  20 * Type: Measure (in milliseconds).
  21 * Variable `kClass`: The first part of your cache key.
  22 * Variable `result`: One of:
  23   * `"hit.good"`: A non-expired value was returned (and call did not get chosen
  24     for pre-emptive refresh).
  25   * `"hit.refresh"`: A non-expired value was returned (and call was chosen for
  26     a pre-emptive refresh, and an async refresh was scheduled).
  27   * `"hit.volatile"`: A value was found that was generated and stored less than 0.1s ago,
  28     and returned as-is despite appearing to also be expired already. This amount of time is
  29     considered negligible in terms of clock accuracy, and by random chance we usually decide
  30     to treat these as a cache hit (see `RECENT_SET_HIGH_MS`).
  31   * `"hit.stale"`: An expired value was found, but we are within the allowed stale period
  32     specified by a `lockTSE` option, and the current request did not get the regeneration lock.
  33     The stale value is returned as-is.
  34   * `"miss.compute"`: A new value was computed by the callback and returned.
  35     No non-expired value was found, and if this key needed a regeneration lock, we got the lock.
  36   * `"miss.busy"`: A busy value was produced by a `busyValue` callback and returned.
  37     No non-expired value was found, and we tried to use a regeneration lock (per the `busyValue`
  38     option), but the current request did not get the lock.
  39   * `"renew.compute"`: Artificial demand from an async refresh, led to a new value being
  40     computed by the callback. These are like `"miss.compute"`, but in response to `"hit.refresh"`.
  41   * `"renew.busy"`: Artificial demand from an async refresh failed to produce a value.
  42     The key used the `busyValue` option, and could not get a regeneration lock.
  43
  44 #### `wanobjectcache.{kClass}.regen_walltime`
  45
  46 Upon cache update due to a cache miss or async refresh, this measures the time spent in
  47 the regeneration callback when computing a new value.
  48
  49 * Type: Measure (in milliseconds).
  50 * Variable `kClass`: The first part of your cache key.
  51
  52 #### `wanobjectcache.{kClass}.ck_touch.{result}`
  53
  54 Call counter from `WANObjectCache::touchCheckKey()`.
  55
  56 * Type: Counter.
  57 * Variable `kClass`: The first part of your cache key.
  58 * Variable `result`: One of `"ok"` or `"error"`.
  59
  60 #### `wanobjectcache.{kClass}.ck_reset.{result}`
  61
  62 Call counter from `WANObjectCache::resetCheckKey()`.
  63
  64 * Type: Counter.
  65 * Variable `kClass`: The first part of your cache key.
  66 * Variable `result`: One of `"ok"` or `"error"`.
  67
  68 #### `wanobjectcache.{kClass}.delete.{result}`
  69
  70 Call counter from `WANObjectCache::delete()`.
  71
  72 * Type: Counter.
  73 * Variable `kClass`: The first part of your cache key.
  74 * Variable `result`: One of `"ok"` or `"error"`.