Log Destination

The destination category under the runtime.log category provides keys that allow you to control where Antora writes log messages. You can configure Antora to write messages to a standard stream or a file. You can also control when and how Antora writes those log messages.

Default destination

The default destination file is correlated with the log format. If the log format is pretty, the default destination is the standard error stream (stderr). If the log format is json, the default destination is the standard output stream (stdout). In either case, the messages will appear in the output of your terminal.

The file key allows you to control which standard stream Antora selects or to configure Antora to route the log messages to a local file.

file key

The file key is configured under the destination category key of the log category key in a playbook. The file key is optional. The value of this key can be a path to a local file, the value stdout (or 1) for the standard output stream, or the value stderr (or 2) for the standard error stream.

Example 1. antora-playbook.yml
runtime:
  log:
    destination:
      file: ./antora.log

If this key is set, the specified destination is used instead of the default destination, regardless of the log format.

The resolution rules for file are the same as for any path in the playbook. A relative path is expanded to an absolute path using the following rules:

  • If the first path segment is a tilde (~), the remaining path is resolved relative to the user’s home directory.

  • If the first path segment is a dot (.), the remaining path is resolved relative to the location of the playbook file.

  • If the first path segment is a tilde directly followed by a plus sign (~+), or does not begin with an aforementioned prefix, the remaining path is resolved relative to the current working directory.

If the value of the file key is the path of a local file rather than a standard stream, and the log format is pretty, the messages are not colorized. Keep in mind that if you route log messages to a file, you will not see those messages in your terminal anymore. You will have to check the log file to see if Antora wrote any log messages to it.

By default, Antora truncates the file before writing to it. You can alter this behavior using the append key.

append key

The append key is configured under the destination category key of the log category key in a playbook. The append key is optional. The value of this key can either be true or false. By default, the value is false. If you set the value to true, Antora will not truncate (i.e., clear) the file before writing to it. That means the log messages from a previous run of Antora will be preserved.

Example 2. antora-playbook.yml
runtime:
  log:
    destination:
      file: ./antora.log
      append: true

This key is only relevant if the file key is specified as the path of a local file.

By default, Antora will write log messages to the destination immediately. You can control this behavior using the buffer_size and sync keys.

buffer_size key

The buffer_size key is configured under the destination category key of the log category key in a playbook. The buffer_size key is optional. The value of this key can be 0 or a positive integer. The value represents the number of bytes to buffer (e.g., 4096 is 4K).

By default, the value is 0, which means Antora does not buffer log messages. If the value is greater than 0, then Antora will batch log messages until they reach the specified size in bytes. Once the resident size of the buffered log messages meet or exceed this value, Antora will flush the buffer to the destination.

Example 3. antora-playbook.yml
runtime:
  log:
    destination:
      buffer_size: 4096

If you’re routing log messages to a file, the buffer_size key provides a way to avoid an excessive number of writes. You usually only need to use this key if you are encountering a resource problem when running Antora.

The sync key offers an additional way to control writes.

sync key

The sync key is configured under the destination category key of the log category key in a playbook. The sync key is optional. The value of this key can either be true or false. By default, the value is true, which means Antora writes to the destination using a synchronous operation. If you set the value to false, Antora will switch to writing to the destination using an asynchronous operation. This means log messages will be written the next time the Node.js process can perform an I/O operation.

Example 4. antora-playbook.yml
runtime:
  log:
    destination:
      file: ./antora.log
      sync: false

Setting the sync key to false prevents a log event from pausing the program to complete the write. Instead, those writes are put onto a queue and performed the next time the Node.js process is idle, such as when it’s performing a network operation. In other words, the writes are naturally batched. If generating your site produces a lot of log messages, this can help Antora perform more optimally.

You can combine the sync key with the buffer_size key to maximize how much log message writes are deferred.