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