1# Cache Configuration of `wasmtime` 2 3The configuration file uses the [toml] format. 4You can create a configuration file at the default location with: 5```console 6wasmtime config new 7``` 8It will print the location regardless of the success. 9Please refer to the `--help` message for using a custom location. 10 11All settings, except `enabled`, are **optional**. 12If the setting is not specified, the **default** value is used. 13***Thus, if you don't know what values to use, don't specify them.*** 14The default values might be tuned in the future. 15 16Wasmtime assumes all the options are in the `cache` section. 17 18Example config: 19```toml 20[cache] 21directory = "/nfs-share/wasmtime-cache/" 22cleanup-interval = "30m" 23files-total-size-soft-limit = "1Gi" 24``` 25 26Please refer to the [cache system] section to learn how it works. 27 28If you think some default value should be tuned, some new settings 29should be introduced or some behavior should be changed, you are 30welcome to discuss it and contribute to [the Wasmtime repository]. 31 32[the Wasmtime repository]: https://github.com/bytecodealliance/wasmtime 33 34Setting `enabled` 35----------------- 36- **type**: boolean 37- **format**: `true | false` 38- **default**: `true` 39 40Specifies whether the cache system is used or not. 41 42This field is *mandatory*. 43The default value is used when configuration file is not specified 44and none exists at the default location. 45 46[`enabled`]: #setting-enabled 47 48Setting `directory` 49----------------- 50- **type**: string (path) 51- **default**: look up `cache_dir` in [directories] crate 52 53Specifies where the cache directory is. Must be an absolute path. 54 55[`directory`]: #setting-directory 56 57Setting `worker-event-queue-size` 58----------------- 59- **type**: string (SI prefix) 60- **format**: `"{integer}(K | M | G | T | P)?"` 61- **default**: `"16"` 62 63Size of [cache worker] event queue. 64If the queue is full, incoming cache usage events will be dropped. 65 66[`worker-event-queue-size`]: #setting-worker-event-queue-size 67 68Setting `baseline-compression-level` 69------------------ 70- **type**: integer 71- **default**: `3`, the default zstd compression level 72 73Compression level used when a new cache file is being written by the [cache system]. 74Wasmtime uses [zstd] compression. 75 76[`baseline-compression-level`]: #setting-baseline-compression-level 77 78Setting `optimized-compression-level` 79------------------ 80- **type**: integer 81- **default**: `20` 82 83Compression level used when the [cache worker] decides to recompress a cache file. 84Wasmtime uses [zstd] compression. 85 86[`optimized-compression-level`]: #setting-optimized-compression-level 87 88Setting `optimized-compression-usage-counter-threshold` 89------------------ 90- **type**: string (SI prefix) 91- **format**: `"{integer}(K | M | G | T | P)?"` 92- **default**: `"256"` 93 94One of the conditions for the [cache worker] to recompress a cache file 95is to have usage count of the file exceeding this threshold. 96 97[`optimized-compression-usage-counter-threshold`]: #setting-optimized-compression-usage-counter-threshold 98 99Setting `cleanup-interval` 100------------------ 101- **type**: string (duration) 102- **format**: `"{integer}(s | m | h | d)"` 103- **default**: `"1h"` 104 105When the [cache worker] is notified about a cache file being updated by the [cache system] 106and this interval has already passed since last cleaning up, 107the worker will attempt a new cleanup. 108 109Please also refer to [`allowed-clock-drift-for-files-from-future`]. 110 111[`cleanup-interval`]: #setting-cleanup-interval 112 113Setting `optimizing-compression-task-timeout` 114------------------ 115- **type**: string (duration) 116- **format**: `"{integer}(s | m | h | d)"` 117- **default**: `"30m"` 118 119When the [cache worker] decides to recompress a cache file, it makes sure that 120no other worker has started the task for this file within the last 121[`optimizing-compression-task-timeout`] interval. 122If some worker has started working on it, other workers are skipping this task. 123 124Please also refer to the [`allowed-clock-drift-for-files-from-future`] section. 125 126[`optimizing-compression-task-timeout`]: #setting-optimizing-compression-task-timeout 127 128Setting `allowed-clock-drift-for-files-from-future` 129------------------ 130- **type**: string (duration) 131- **format**: `"{integer}(s | m | h | d)"` 132- **default**: `"1d"` 133 134### Locks 135When the [cache worker] attempts acquiring a lock for some task, 136it checks if some other worker has already acquired such a lock. 137To be fault tolerant and eventually execute every task, 138the locks expire after some interval. 139However, because of clock drifts and different timezones, 140it would happen that some lock was created in the future. 141This setting defines a tolerance limit for these locks. 142If the time has been changed in the system (i.e. two years backwards), 143the [cache system] should still work properly. 144Thus, these locks will be treated as expired 145(assuming the tolerance is not too big). 146 147### Cache files 148Similarly to the locks, the cache files or their metadata might 149have modification time in distant future. 150The cache system tries to keep these files as long as possible. 151If the limits are not reached, the cache files will not be deleted. 152Otherwise, they will be treated as the oldest files, so they might survive. 153If the user actually uses the cache file, the modification time will be updated. 154 155[`allowed-clock-drift-for-files-from-future`]: #setting-allowed-clock-drift-for-files-from-future 156 157Setting `file-count-soft-limit` 158------------------ 159- **type**: string (SI prefix) 160- **format**: `"{integer}(K | M | G | T | P)?"` 161- **default**: `"65536"` 162 163Soft limit for the file count in the cache directory. 164 165This doesn't include files with metadata. 166To learn more, please refer to the [cache system] section. 167 168[`file-count-soft-limit`]: #setting-file-count-soft-limit 169 170Setting `files-total-size-soft-limit` 171------------------ 172- **type**: string (disk space) 173- **format**: `"{integer}(K | Ki | M | Mi | G | Gi | T | Ti | P | Pi)?"` 174- **default**: `"512Mi"` 175 176Soft limit for the total size* of files in the cache directory. 177 178This doesn't include files with metadata. 179To learn more, please refer to the [cache system] section. 180 181*this is the file size, not the space physically occupied on the disk. 182 183[`files-total-size-soft-limit`]: #setting-files-total-size-soft-limit 184 185Setting `file-count-limit-percent-if-deleting` 186------------------ 187- **type**: string (percent) 188- **format**: `"{integer}%"` 189- **default**: `"70%"` 190 191If [`file-count-soft-limit`] is exceeded and the [cache worker] performs the cleanup task, 192then the worker will delete some cache files, so after the task, 193the file count should not exceed 194[`file-count-soft-limit`] * [`file-count-limit-percent-if-deleting`]. 195 196This doesn't include files with metadata. 197To learn more, please refer to the [cache system] section. 198 199[`file-count-limit-percent-if-deleting`]: #setting-file-count-limit-percent-if-deleting 200 201Setting `files-total-size-limit-percent-if-deleting` 202------------------ 203- **type**: string (percent) 204- **format**: `"{integer}%"` 205- **default**: `"70%"` 206 207If [`files-total-size-soft-limit`] is exceeded and [cache worker] performs the cleanup task, 208then the worker will delete some cache files, so after the task, 209the files total size should not exceed 210[`files-total-size-soft-limit`] * [`files-total-size-limit-percent-if-deleting`]. 211 212This doesn't include files with metadata. 213To learn more, please refer to the [cache system] section. 214 215[`files-total-size-limit-percent-if-deleting`]: #setting-files-total-size-limit-percent-if-deleting 216 217[toml]: https://github.com/toml-lang/toml 218[directories]: https://crates.io/crates/directories 219[cache system]: #how-does-the-cache-work 220[cache worker]: #how-does-the-cache-work 221[zstd]: https://facebook.github.io/zstd/ 222[Least Recently Used (LRU)]: https://en.wikipedia.org/wiki/Cache_replacement_policies#Least_recently_used_(LRU) 223 224How does the cache work? 225======================== 226 227**This is an implementation detail and might change in the future.** 228Information provided here is meant to help understanding the big picture 229and configuring the cache. 230 231There are two main components - the *cache system* and the *cache worker*. 232 233Cache system 234------------ 235 236Handles GET and UPDATE cache requests. 237- **GET request** - simply loads the cache from disk if it is there. 238- **UPDATE request** - compresses received data with [zstd] and [`baseline-compression-level`], then writes the data to the disk. 239 240In case of successful handling of a request, it notifies the *cache worker* about this 241event using the queue. 242The queue has a limited size of [`worker-event-queue-size`]. If it is full, it will drop 243new events until the *cache worker* pops some event from the queue. 244 245Cache worker 246------------ 247 248The cache worker runs in a single thread with lower priority and pops events from the queue 249in a loop handling them one by one. 250 251### On GET request 2521. Read the statistics file for the cache file, 253 increase the usage counter and write it back to the disk. 2542. Attempt recompressing the cache file if all of the following conditions are met: 255 - usage counter exceeds [`optimized-compression-usage-counter-threshold`], 256 - the file is compressed with compression level lower than [`optimized-compression-level`], 257 - no other worker has started working on this particular task within the last 258 [`optimizing-compression-task-timeout`] interval. 259 260 When recompressing, [`optimized-compression-level`] is used as a compression level. 261 262### On UPDATE request 2631. Write a fresh statistics file for the cache file. 2642. Clean up the cache if no worker has attempted to do this within the last [`cleanup-interval`]. 265 During this task: 266 - all unrecognized files and expired task locks in cache directory will be deleted 267 - if [`file-count-soft-limit`] or [`files-total-size-soft-limit`] is exceeded, 268 then recognized files will be deleted according to 269 [`file-count-limit-percent-if-deleting`] and [`files-total-size-limit-percent-if-deleting`]. 270 Wasmtime uses [Least Recently Used (LRU)] cache replacement policy and requires that 271 the filesystem maintains proper mtime (modification time) of the files. 272 Files with future mtimes are treated specially - more details 273 in [`allowed-clock-drift-for-files-from-future`]. 274 275### Metadata files 276- every cached WebAssembly module has its own statistics file 277- every lock is a file 278