Log Format :: Antora Docs

默认日志格式

显式地为format键分配一个值是可选的。当未设置format时，Antora会根据运行时检测到的环境，将键的接受值之一（json或pretty）分配给它。当Antora在持续集成环境（CI=true）中运行时，环境变量IS_TTY为true，或终端是交互式（TTY）且环境变量IS_TTY不是false时，Antora将值pretty分配给format键。在所有其他情况下，Antora使用json值。

格式键

在playbook中，format键配置在运行时和日志键下。

示例1. antora-playbook.yml

runtime:
  log:
    format: json

format键接受以下内置值：

json: 如果未设置CI环境变量（不在CI环境中运行），IS_TTY=false，或终端不是交互式的，则默认为此值。 结构化的日志消息以JSON格式发出到标准输出流（STDOUT），因此可以将其传输到其他应用程序并进行处理。输出符合JSON Lines（jsonl）文本格式（也称为Newline delimited JSON或ndjson）。每条消息都以自己的行输出，使用UTF-8编码，每行都是有效的JSON值。消息的级别以标签表示，默认为error，info等。可以通过将log.level_format键设置为number来将级别格式更改为数字。
pretty: 如果CI=true，IS_TTY=true，或终端是交互式的，则默认为此值。 日志消息被格式化以便阅读，并发出到标准错误流（STDERR）。

format键也可以使用--log-format选项或ANTORA_LOG_FORMAT变量来指定。

CI环境变量

持续集成（CI）环境，如Netlify、GitHub Actions、GitLab CI等，通常将持续集成环境变量（CI）设置为true。 Antora使用此环境变量来确定何时在CI环境中运行并相应地更改其行为。

美化

要发出格式化的日志消息，请在playbook中的format键中分配pretty值。

示例2. 将pretty值分配给format键

runtime:
  log:
    format: pretty

现在当您运行Antora时，它将将日志消息发出到STDERR。 Antora会智能地使用颜色。当Antora将日志消息写入标准流（如STDERR）时，如果终端支持颜色，它将为美化的日志消息着色。

如果您从终端运行Antora，则格式化的日志消息将显示在那里。示例3显示了一个美化的日志消息（不带颜色），用于xref错误。

示例3. 使用pretty格式输出的日志消息

[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	要显示发生错误的行号，请设置sourcemap键。

您可以通过在运行Antora时设置NO_COLOR环境变量来阻止Antora对美化的日志消息着色。

$ NO_COLOR=1 antora antora-playbook.yml

如果设置了NO_COLOR环境变量，则Antora永远不会对日志消息应用颜色，而不管终端的功能如何。如果要强制Antora应用颜色，即使它在终端中检测不到颜色支持，请设置FORCE_COLOR环境变量（例如，FORCE_COLOR=1）。

JSON

要以JSON格式发出结构化的日志消息，请在playbook中的format键中分配json值。

示例4. 将json值分配给format键

runtime:
  log:
    format: json

当Antora运行时，任何日志消息都会发出到STDOUT。示例5显示了有关xref错误的结构化日志消息。

示例5. 以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"}

结构化的日志消息由一系列键值对组成。每个键表示一个日志消息字段，如level，每个值记录该字段的日志信息，如error。

处理JSON消息

JSON格式的消息可以定向到另一个应用程序或发送到日志摄取服务进行解析、搜索和分析。用于处理JSON消息的流行工具是jq。 jq是一个JSON处理器；一个用于选择、过滤和重塑JSON消息的命令行工具。

以下是一个示例，显示了如何将Antora生成的JSON格式化日志消息通过管道传输到jq。

$ antora antora-playbook.yml | jq

示例6显示了已通过管道传输到jq的结构化日志消息的结果，以便更容易阅读。

示例6. 通过管道传输到jq的日志消息输出

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

您还可以使用jq来过滤消息。例如，如果您只想看到来自Asciidoctor的xref错误，而忽略所有其他错误，可以向jq命令添加一个select过滤器。

$ antora --log-level=error antora-playbook.yml | \
  jq 'select(.name == "asciidoctor" and (.msg | contains(" not found:")))'

如果您只构建站点的一部分，并且要过滤掉“外部”页面的警告，可以向jq命令添加一个ignore过滤器。

$ antora antora-playbook.yml | \
  jq 'select(.msg | contains(" not found: missing-component-name:") | not)'

您可以多次将结果传输到jq以选择或忽略其他消息。请参阅select函数的参考文档，了解如何使用它。

如果希望jq的结果集以美化的格式显示，可以将该结果传输到pino-pretty。由于pino-pretty是Antora的依赖项，因此可以使用npx来调用它。

$ antora antora-playbook.yml | jq -cM | npx pino-pretty

-c选项告诉jq保持JSON行格式的输出，-M选项关闭传递给pino-pretty的数据中的颜色。美化的消息不像Antora生成的输出那样漂亮，尽管可以自定义pino-pretty以实现类似的结果。

日志格式选项

您无需直接修改playbook文件即可设置format键。您可以使用CLI中的--log-format选项。

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

--log-format选项会覆盖分配给format键或ANTORA_LOG_FORMAT环境变量的值。

但是，请注意，如果将输出传输到另一个程序，并且未指定日志格式，则Antora将自动切换到JSON格式。

level_format 键

当日志格式为 JSON（json）时，每个日志级别都与一个标签和一个数字相关联。 JSON 格式默认将级别表示为标签，例如 error 或 info。但是，某些工具要求级别为数字。可以使用 level_format 键配置级别的格式。 level_format 键配置在 playbook 的运行时和日志键下。

示例 7. 为 level_format 键分配数字值

runtime:
  log:
    format: json
    level_format: number

level_format 键接受内置值 label 和 number。默认值为 label。如果日志格式为 pretty，则忽略分配给 level_format 键的值，级别始终表示为标签。

级别格式选项

您无需直接修改 playbook 文件即可设置 level_format 键。您可以使用来自 CLI 的 --log-level-format 选项。

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

--log-level-format 选项会覆盖分配给 level_format 键或 ANTORA_LOG_LEVEL_FORMAT 环境变量的值。