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