Handling server warmup

Couchbase server warmup behavior can be modified by changing the access scanner and warmup threshold settings via the cbepctl tool.

In order to adjust warmup behavior, it is important to understand the access log and scanning process in Couchbase Server.

The server uses the access log to determine which documents are most frequently used, and therefore which documents to load first. It has a process that periodically scans every key in RAM and compiles them into a log named access.log. It also maintains a backup of this access log, named access.old.

The server can use this backup file during warmup if the most recent access log has been corrupted during warmup or node failure. By default, this process runs initially at 2:00 GMT and then again each 24 hour time periods. You can configure this process to run at a different initial time and at a different fixed interval.

If a client tries to contact Couchbase Server during warmup, the server produces a ENGINE_TMPFAIL (0x0d) error code. This error indicates that data access is still not available because warmup has not yet finished.

Note: If you are creating your own Couchbase SDK, you need to handle this error in your library. This may mean that the client waits and retries, performs a backoff of requests, or produces an error and does not retry the request.

Note: If you are building an application with a Couchbase SDK, be aware that delivery and handling of this error dependst on the individual SDKs.

These are the actions to take during Couchbase Server warmup:

Getting warmup information: The cbstats tool is used to get information about server warmup, including the warmup status and whether warmup is enabled.

Changing the warmup threshold: Modify warmup behavior by changing the cbepctl ep_warmup_min_items_threshold parameter. This indicates the percentage of items loaded in RAM that must be reached for Couchbase Server to begin serving data. The lower this number, the sooner your server can begin serving data. Be aware, however that if you set this value to be too low, once requests come in for items, the item may not be in memory and Couchbase Server will experience cache-miss errors.

Changing access scanner settings: The server runs a periodic scanner process which determines which keys are most frequently-used, and therefore, which documents should be loaded first during server warmup. The settings, cbepctl flush_param alog_sleep_ time and alog_task_ timeparameters are used to change the initial time and the interval for the process.