Log Format

The log format key specifies the format of the log messages.

The log format, and all other log settings, are not honored if an error is thrown before the playbook is fully configured. Instead, the error message is printed directly to standard error (stderr).

Default log format

Explicitly assigning a value to the format key is optional. When format isn’t set, Antora assigns one of the key’s accepted values, either json or pretty, based on the environment it detects at runtime. Antora assigns the value json to the format key when it detects a continuous integration environment (CI=true). In all other cases, Antora uses the pretty value.

format key

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

Example 1. antora-playbook.yml
runtime:
  log:
    format: json

The format key accepts the following built-in values:

json

Default when CI=true. The structured log messages are emitted in JSON format to the standard out stream (STDOUT), one per line, so that they can be piped to other applications and processed. The messages adhere to the JSON Lines text format, also known as newline-delimited JSON.

pretty

Default in non-CI environments. The log messages are formatted for readability and emitted to the standard error stream (STDERR).

The format key can also be specified using the --log-format option or ANTORA_LOG_FORMAT variable.

CI environment variable

Continuous integration (CI) environments, such as Netlify, GitHub Actions, GitLab CI, and many others, typically set the continuous integration environment variable (CI) to true. Antora uses this environment variable to determine when it’s running in a CI environment and change its behavior accordingly.

Prettified

To emit formatted log messages, assign the pretty value to the format key in your playbook.

Example 2. Assign pretty value to format key
runtime:
  log:
    format: pretty

When Antora runs, any log messages are emitted to STDERR. If you run Antora from your terminal, the formatted log messages are displayed there. Example 3 shows a prettified log message about an xref error.

Example 3. Log message output using pretty format
[16:03:00.691] ERROR (asciidoctor): target of xref not found: a-page.adoc
    file: /home/computer/my-projects/project/docs/modules/module-name/pages/index.adoc:54 (1)
    source: /home/computer/my-projects/project (refname: my-branch <worktree>, start path: docs)
1 To display the line number where an error occurs, set the sourcemap key.

JSON

To emit structured log messages in JSON format, assign the json value to the format key in your playbook.

Example 4. Assign json value to format key
runtime:
  log:
    format: json

When Antora runs, any log messages are emitted to STDOUT. Example 5 shows a structured log message about an xref error.

Example 5. Log message output in JSON
{"level":"error","time":1627682525543,"name":"asciidoctor","file":{"path":"/home/computer/my-projects/project/docs/modules/module-name/pages/index.adoc","line":54},"source":{"url":"https://gitlab.com/org/project.git","worktree":"/home/computer/my-projects/project","refname":"my-branch","startPath":"docs"},"msg":"target of xref not found: a-page.adoc"}

A structured log message is made up of a series of key-value pairs. Each key indicates a log message field, such as level, and each value records the logging information for that field, such as error. JSON formatted messages can be sent to separate applications or log ingestion services for parsing, search, and analysis. Example 6 shows a structured log message about an xref error that’s been piped to jq, a command line JSON processor, for pretty printing.

Example 6. Log message output piped to jq
{
  "level": "error",
  "time": 1627683497637,
  "name": "asciidoctor",
  "file": {
    "path": "/home/computer/my-projects/project/docs/modules/module-name/pages/index.adoc",
    "line": 54
  },
  "source": {
    "url": "https://gitlab.com/org/project.git",
    "worktree": "/home/computer/my-projects/project",
    "refname": "my-branch",
    "startPath": "docs"
  },
  "msg": "target of xref not found: a-page.adoc"
}

Log format option

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

$ antora --log-format=json antora-playbook.yml

The --log-format option overrides the value assigned to the format key or to the ANTORA_LOG_FORMAT environment variable.