Runtime Keys

The playbook keys configured under the runtime key manage Antora’s logger, as well as its console output, caching, and remote repository update behavior.

runtime key

The global log, console output, fetch, and cache directory properties are defined under the runtime key in a playbook file. These settings are applied to the Antora pipeline when it starts.

Example 1. antora-playbook.yml

runtime: (1)
  cache_dir: ./.cache/antora (2)
  fetch: true (3)
  log: (4)
    level: error (5)

1	Optional `runtime` key
2	Optional `cache_dir` key
3	Optional `fetch` key
4	Optional `log` key
5	Optional `level` key

The runtime key and the key-value pairs it accepts are optional. If runtime isn’t set in the playbook, Antora uses the default cache directory, fetch, and log settings. Alternatively, these keys can be assigned from the CLI or, except for fetch, using environment variables.

log key

The log key is optional. If you do set it in a playbook, you must nest it under the runtime key. The log key accepts a list of built-in key-value pairs that configure the log level (level), failure level (failure_level), and display format (format).

Example 2. antora-playbook.yml

runtime:
  log: (1)
    format: json (2)
    failure_level: warn (3)
    level: all (4)
    level_format: number (5)
    destination: (6)
      file: ./antora.log (7)
      append: true (8)
      buffer_size: 4096 (9)
      sync: false (10)

1	The optional `log` category key is nested under the `runtime` category key.
2	The optional `format` key is nested under the `log` category key.
3	The optional `failure_level` key is nested under the `log` category key.
4	The optional `level` key is nested under the `log` category key.
5	The optional `level_format` key is nested under the `log` category key.
6	The optional `destination` category key is nested under the `log` category key.
7	The optional `file` key is nested under the `destination` category key.
8	The optional `append` key is nested under the `destination` category key.
9	The optional `buffer_size` key is nested under the `destination` category key.
10	The optional `sync` key is nested under the `destination` category key.

If level, failure_level, format, or level_format are set in the playbook, they must be nested under the log category key. The level, failure_level, format, and level_format keys have default values that are automatically applied when Antora runs if they’re not explicitly defined in the playbook or using the corresponding the command line options or environment variables.

If file, append, buffer_size, or sync are set in the playbook, they must be nested under the destination category key.

The log settings are not honored if a fatal error is thrown before Antora fully configures the playbook. In such cases, the error message is only printed directly to standard error (stderr) using a preconfigured logger.

Available runtime keys

Runtime Keys Description Required

Runtime Keys	Description	Required
cache_dir	Specifies the directory where the remote content sources git repositories and UI bundles are cached.	No
fetch	When set to `true`, the `fetch` key refreshes the files in the cache each time Antora runs.	No
log.failure_level	Sets the log level tolerance that, when met or exceeded, causes Antora to fail on exit with a non-zero exit code. Accepts the values `warn`, `error`, `fatal`, and `none`. The default value is `fatal`. The value `none` causes Antora to always exit with a zero exit code.	No
log.format	Sets the format of log messages. Accepts the values `pretty` and `json`. The default value is `json` in a CI environment and `pretty` in all other environments.	No
log.level	Sets the minimum severity threshold level that must be met for a message to be logged. Accepts the values `all`, `debug`, `info`, `warn`, `error`, `fatal`, and `silent`. The default value is `warn`. The value `silent` turns the logger off.	No
log.level_format	Sets the format of how the log levels are expressed. Only applies when `log.format` is `json`. Accepts the values `label` and `number`. The default value is `label`.	No
log.destination.file	Sets the destination file or stream where log messages are written. The default value (either `stdout` or `stderr`) depends on the log format.	No
log.destination.append	Configures whether to truncate (i.e., clear) the file before writing to it. The default value is `false`, which means to truncate the file.	No
log.destination.buffer_size	Sets the amount of memory to use to buffer log messages. Once the buffer reaches this size, the buffered messages are written to the destination in a batch. The default value is `0`, which turns off this behavior.	No
log.destination.sync	Configures whether to use a sync or async operation to write log messages to the destination. The default value is `true`, which means log messages are written synchronously (blocking).	No

cache_dir

Specifies the directory where the remote content sources git repositories and UI bundles are cached.

fetch

When set to true, the fetch key refreshes the files in the cache each time Antora runs.

log.failure_level

Sets the log level tolerance that, when met or exceeded, causes Antora to fail on exit with a non-zero exit code. Accepts the values warn, error, fatal, and none. The default value is fatal. The value none causes Antora to always exit with a zero exit code.

log.format

Sets the format of log messages. Accepts the values pretty and json. The default value is json in a CI environment and pretty in all other environments.

log.level

Sets the minimum severity threshold level that must be met for a message to be logged. Accepts the values all, debug, info, warn, error, fatal, and silent. The default value is warn. The value silent turns the logger off.

log.level_format

Sets the format of how the log levels are expressed. Only applies when log.format is json. Accepts the values label and number. The default value is label.

log.destination.file

Sets the destination file or stream where log messages are written. The default value (either stdout or stderr) depends on the log format.

log.destination.append

Configures whether to truncate (i.e., clear) the file before writing to it. The default value is false, which means to truncate the file.

log.destination.buffer_size

Sets the amount of memory to use to buffer log messages. Once the buffer reaches this size, the buffered messages are written to the destination in a batch. The default value is 0, which turns off this behavior.

log.destination.sync

Configures whether to use a sync or async operation to write log messages to the destination. The default value is true, which means log messages are written synchronously (blocking).