Log Severity Level

The log level key specifies a severity threshold, such as debug or error, that must be met for a message to be logged.

Default log level

Explicitly assigning a value to the level key is optional. If it isn’t set in your playbook or specified using the --log-level option or ANTORA_LOG_LEVEL variable, Antora assigns the value warn to the key at runtime. When the default value is applied, all messages that meet or exceed the warn threshold are logged.

level key

The level key is configured under the runtime and log keys in a playbook.

Example 1. antora-playbook.yml

runtime:
  log:
    level: error

The level key accepts the following built-in values:

fatal

Catastrophic errors that force Antora to shut down abruptly. Your site was not generated.

If a fatal error is thrown before Antora configures the playbook, Antora only prints the message to standard error (STERR). The error message isn’t routed through the logger as configured by the user.

error

Serious issues that indicate an important operation failed to occur or wasn’t completed successfully. An error may not cause Antora to shut down, but your site probably wasn’t generated or published as expected.

warn

Default value. Incorrect AsciiDoc syntax such as missing AsciiDoc attributes, playbook or component configurations, and other problematic or unusual situations that are likely to affect the usability, performance, or appearance of the generated site.

info

Informational messages that highlight Antora’s normal operations and milestones.

debug

Diagnostic messages that provide detailed context about Antora’s activities, events, warnings, and errors as they occurred. This level is useful when you need additional information about a warning or error.

all

All of the information and details about Antora’s operations and the results of those operations are logged.

silent

The logger is turned off and no messages are logged.

Messages that meet or exceed the severity threshold are logged. Messages that don’t meet the severity threshold are not reported.

Specify a log level

Let’s assign the value info to the level key in the playbook shown in Example 2.

Example 2. Assign info severity threshold to level key

runtime: (1)
  log: (2)
    level: info (3)

1	In your playbook file, type the parent key `runtime`, followed by a colon (`:`), and press `Enter`.
2	The `log` key is a child of `runtime`. Type the key’s name, `log`, followed by a colon (`:`), and press `Enter`.
3	The `level` key is a child of `log`. Type `level`, followed by a colon and a blank space (`:` ), then type the value `info`.

When Antora runs and level is assigned info, messages that meet or exceed the info threshold are logged. Messages that don’t meet the info severity level aren’t reported.

Log level option

You don’t have to modify the playbook file directly to set the level key. You can use the --log-level option from the CLI.

$ antora --log-level=debug antora-playbook.yml

The --log-level option overrides the value assigned to the level key or to the ANTORA_LOG_LEVEL environment variable.