11. 日志记录和聚合

日志记录是一种功能，它能够将详细的日志发送到多种类型的第三方外部日志聚合服务。连接到此数据源的服务作为一种有用的方式，可以深入了解 AWX 使用情况或技术趋势。该数据可用于分析基础设施中的事件、监控异常以及将来自一项服务的事件与另一项服务中的事件相关联。对 AWX 最有用的数据类型是作业事实数据、作业事件/作业运行、活动流数据和日志消息。数据以 JSON 格式通过 HTTP 连接发送，使用自定义处理程序中设计的最小服务特定调整或通过导入的库。

安装 AWX 将安装更新版本的 rsyslog，它将替换 RHEL 基础中附带的版本。AWX 安装的 rsyslog 版本不包括以下 rsyslog 模块

  • rsyslog-udpspoof.x86_64

  • rsyslog-libdbi.x86_64

安装 AWX 后，仅将 AWX 提供的 rsyslog 包用于 AWX 之外的任何日志记录，这些日志记录可能以前使用 RHEL 提供的 rsyslog 包进行。如果您已经在 AWX 实例上使用 rsyslog 记录系统日志，则可以通过运行单独的 rsyslog 进程（使用与 AWX 相同版本的 rsyslog），并将该进程指向单独的 /etc/rsyslog.conf，继续使用 rsyslog 处理 AWX 之外的日志。

注意

对于在 AWX 之外使用 rsyslog 的系统，请考虑与使用 AWX 附带的 rsyslog 新版本可能出现的任何冲突。

您可以从 /api/v2/settings/logging/ 终端配置 AWX rsyslog 进程如何处理在外部日志记录器脱机的情况下尚未发送的消息

  • LOG_AGGREGATOR_MAX_DISK_USAGE_GB: 指定在外部日志聚合器中断期间存储的数据量（以 GB 为单位）（默认为 1）。等效于 rsyslogd queue.maxdiskspace 设置。

  • LOG_AGGREGATOR_MAX_DISK_USAGE_PATH: 指定在外部日志聚合器中断后应重试的日志的持久化位置（默认为 /var/lib/awx）。等效于 rsyslogd queue.spoolDirectory 设置。

例如，如果 Splunk 离线，rsyslogd 会在磁盘上存储一个队列，直到 Splunk 重新联机。默认情况下，它将存储高达 1GB 的事件（在 Splunk 离线期间），但如果需要，您可以将其设为超过 1GB，或者更改保存队列的路径。

11.1. 日志记录器

以下是一些特殊的日志记录器（除了 awx，它构成通用服务器日志），它们以可预测的结构化或半结构化格式提供大量信息，遵循与从 API 获取数据时预期相同的结构

  • job_events: 提供从 Ansible 回调模块返回的数据

  • activity_stream: 显示 AWX 应用程序中对象更改的记录

  • system_tracking: 提供通过 Ansible setup 模块收集的事实数据（即 gather_facts: True）当作业模板使用 启用事实缓存 选项运行时

  • awx: 提供通用服务器日志，其中包括通常写入文件的日志。它包含所有日志具有的标准元数据，但它只包含来自日志语句的消息。

这些日志记录器只使用 INFO 级别，除了 awx 日志记录器，它可以使用任何给定的级别。

此外，标准 AWX 日志可以通过这种机制交付。很明显，如何在不操作本地设置文件中的复杂字典的情况下启用或禁用这五个数据源中的每一个，以及调整从标准 AWX 日志中使用的日志级别。

要在 AWX 中配置各种日志记录组件，请从左侧导航栏中单击 设置，然后从系统选项列表中选择 日志记录设置。

11.1.1. 日志消息模式

所有日志记录器的通用模式

  • cluster_host_id: AWX 集群中主机内的唯一标识符

  • level: 标准 python 日志级别，大致反映事件的重要程度。所有作为此功能一部分的数据日志记录器都使用 INFO 级别，但其他 AWX 日志将根据需要使用不同的级别

  • logger_name: 我们在设置中使用的日志记录器名称，例如，“activity_stream”

  • @timestamp: 日志时间

  • path: 生成日志的代码中的文件路径

11.1.2. 活动流模式

  • (通用): 这使用上面列出的所有日志记录器共有的所有字段

  • actor: 执行日志中记录的操作的用户用户名

  • changes: 更改了哪些字段及其旧值/新值的 JSON 摘要。

  • operation: 活动流中记录的更改的基本类别，例如，“关联”。

  • object1: 有关正在操作的主要对象的信息，与我们在活动流中显示的信息一致

  • object2: 如果适用，参与操作的第二个对象

11.1.3. 作业事件模式

此日志记录器反映保存到作业事件中的数据，除非它们与日志记录器预期标准字段冲突，在这种情况下，这些字段将被嵌套。值得注意的是，job_event 模型上的字段 host 被赋予为 event_host。在有效负载中还有一个子字典字段 event_data，它包含根据 Ansible 事件的具体情况而不同的不同字段。

此日志记录器还包括通用字段。

11.1.4. 扫描/事实/系统跟踪数据模式

这些包含详细的字典类型字段，这些字段是服务、包或文件。

  • (通用): 这使用上面列出的所有日志记录器共有的所有字段

  • services: 对于服务扫描，此字段被包含在内，并且具有基于服务名称的键。注意: Elastic search 在名称中不允许使用句号，并且由我们的日志格式化程序替换为“_”

  • package: 包含在来自包扫描的日志消息中

  • files: 包含在来自文件扫描的日志消息中

  • host: 扫描适用的主机名称

  • inventory_id: 主机所在的清单 ID

11.1.5. 作业状态变更

这旨在成为一个低容量的作业状态变更信息来源，与作业事件相比，它还旨在捕获对非基于作业模板的统一作业类型的变更。

除了通用字段外，这些日志还包括作业模型中存在的字段。

11.1.6. AWX 日志

除了通用字段外，它还包含一个 msg 字段，其中包含日志消息。错误包含一个单独的 traceback 字段。这些日志可以通过日志设置页面中的 ENABLE EXTERNAL LOGGING 选项启用或禁用。

11.1.7. 日志聚合器服务

日志聚合器服务与以下监控和数据分析系统一起使用

11.1.7.1. Logstash

这些说明描述了如何使用 logstash 容器。

  1. 在 docker-compose.yml 文件中取消以下行的注释

#- logstash
...

#logstash:
#  build:
#    context: ./docker-compose
#    dockerfile: Dockerfile-logstash

  1. 将以下内容 POST 到 1`/api/v2/settings/logging/1`（这使用在 logstash 配置文件中设置的身份验证）。

{
    "LOG_AGGREGATOR_HOST": "http://logstash",
    "LOG_AGGREGATOR_PORT": 8085,
    "LOG_AGGREGATOR_TYPE": "logstash",
    "LOG_AGGREGATOR_USERNAME": "awx_logger",
    "LOG_AGGREGATOR_PASSWORD": "workflows",
    "LOG_AGGREGATOR_LOGGERS": [
        "awx",
        "activity_stream",
        "job_events",
        "system_tracking"
    ],
    "LOG_AGGREGATOR_INDIVIDUAL_FACTS": false,
    "LOG_AGGREGATOR_TOWER_UUID": "991ac7e9-6d68-48c8-bbde-7ca1096653c6",
    "LOG_AGGREGATOR_ENABLED": true
}

注意

如果您使用的是 docker 开发环境，则必须在 LOG_AGGREGATOR_HOST 中指定 HTTP。

  1. 要查看容器中最新的日志

docker exec -i -t $(docker ps -aqf "name=tools_logstash_1") tail -n 50 /logstash.log

  1. 要添加 logstash 插件，您可以在运行容器之前在 tools/elastic/logstash/Dockerfile 中添加所需的任何插件。

11.1.7.2. Splunk

AWX 的 Splunk 日志集成使用 Splunk HTTP 收集器。在配置 SPLUNK 日志聚合器时，请添加 HTTP 事件收集器主机的完整 URL，如下例所示

https://example.com/api/v2/settings/logging

{
    "LOG_AGGREGATOR_HOST": "https://splunk_host:8088/services/collector/event",
    "LOG_AGGREGATOR_PORT": null,
    "LOG_AGGREGATOR_TYPE": "splunk",
    "LOG_AGGREGATOR_USERNAME": "",
    "LOG_AGGREGATOR_PASSWORD": "$encrypted$",
    "LOG_AGGREGATOR_LOGGERS": [
        "awx",
        "activity_stream",
        "job_events",
        "system_tracking"
    ],
    "LOG_AGGREGATOR_INDIVIDUAL_FACTS": false,
    "LOG_AGGREGATOR_ENABLED": true,
    "LOG_AGGREGATOR_TOWER_UUID": ""
}

Splunk HTTP 事件收集器默认情况下监听 8088，因此需要提供完整的 HEC 事件 URL（带端口）才能成功处理传入请求。这些值在下面的示例中输入

../_images/logging-splunk-awx-example.png

有关配置 HTTP 事件收集器的更多说明，请参阅 Splunk 文档。

11.1.7.3. Loggly

要设置通过 Loggly 的 HTTP 端点发送日志，请参阅 https://www.loggly.com/docs/http-endpoint/。Loggly 使用在 http://logs-01.loggly.com/inputs/TOKEN/tag/http/ 中描述的 URL 约定，如以下示例中的 日志聚合器 字段所示

../_images/logging-loggly-awx-example.png

11.1.7.4. Sumologic

在 Sumologic 中，创建一个包含提供用于收集所需数据的参数的 json 文件的搜索条件。

../_images/logging_sumologic_main.png

11.1.7.5. Elastic stack（以前称为 ELK stack）

如果从头开始，建立您自己的 elastic stack 版本，您唯一需要做的更改是在 logstash logstash.conf 文件中添加以下几行

filter {
  json {
    source => "message"
  }
}

注意

Elastic 5.0.0 引入了向后不兼容的更改，并且根据您使用的版本，可能需要不同的配置。

11.2. 设置日志记录

11.2.1. 日志聚合

要将日志记录到任何聚合器类型，请执行以下操作

  1. 从左侧导航栏中单击 设置。

  2. 在系统选项列表下，单击以选择 日志记录设置。

  3. 在日志记录设置屏幕的底部，单击 编辑。

  4. 从提供的字段中设置可配置选项

  • 启用外部日志记录：如果您想将日志发送到外部日志聚合器，请单击切换按钮以将其设置为 ON。

  • 日志聚合器：输入要发送日志的主机名或 IP 地址。

  • 日志聚合器端口：如果聚合器需要端口，请指定端口。

注意

当连接类型为 HTTPS 时，您可以将主机名输入为带端口号的 URL，因此您无需再次输入端口。但 TCP 和 UDP 连接由主机名和端口号组合决定，而不是 URL。因此，在 TCP/UDP 连接的情况下，请在指定的字段中提供端口。如果主机字段（日志聚合器 字段）中输入了 URL，则会提取其主机名部分作为实际主机名。

  • 日志聚合器类型：从下拉菜单中单击以选择聚合器服务。

../_images/configure-awx-system-logging-types.png

  • 日志聚合器用户名：如果需要，请输入日志聚合器的用户名。

  • 日志聚合器密码/令牌：如果需要，请输入日志聚合器的密码。

  • 分别记录系统跟踪事实：单击工具提示 帮助 图标以获取有关是否要打开它或默认情况下将其关闭的更多信息。

  • 日志聚合器协议：单击以选择与日志聚合器通信的连接类型（协议）。后续选项因所选协议而异。

  • 日志聚合器级别阈值：选择您希望日志处理程序报告的严重性级别。

  • TCP 连接超时：以秒为单位指定连接超时。此选项仅适用于 HTTPS 和 TCP 日志聚合器协议。

  • 启用/禁用 HTTPS 证书验证：默认情况下，HTTPS 日志协议已启用证书验证。如果您不希望日志处理程序在建立连接之前验证外部日志聚合器发送的 HTTPS 证书，请单击切换按钮以将其设置为 OFF。

  • 要将数据发送到日志聚合器表单的日志记录器：默认情况下，所有四种数据类型都已预填充。单击字段旁边的工具提示 帮助 图标以获取有关每种数据类型的更多信息。删除您不希望使用的数据类型。

  • API 4XX 错误的日志格式：配置特定的错误消息。有关更多详细信息，请参阅 API 4XX 错误配置。

  1. 查看您为所选日志聚合输入的条目。以下是针对 Splunk 设置的一个示例

../_images/configure-awx-system-logging-splunk-example.png

  1. 完成后，单击 保存 以应用设置，或单击 取消 以放弃更改。

  2. 要验证您的配置是否已正确设置，请先单击 保存，然后单击 测试。这会使用 AWX 中当前的日志记录配置将测试日志消息发送到日志聚合器。您应该检查以确保您的外部日志聚合器收到了此测试消息。

注意

如果 测试 按钮被禁用，则表示字段与其初始值不同，因此请先保存您的更改，并确保 启用外部日志记录 切换设置为 ON。

11.2.2. API 4XX 错误配置

当 API 遇到请求问题时，通常会在 400 范围内返回 HTTP 错误代码以及错误。发生这种情况时，将在日志中生成一条错误消息，该消息遵循以下模式

` status {status_code} received by user {user_name} attempting to access {url_path} from {remote_addr} `

可以根据需要配置这些消息。要修改默认的 API 4XX 错误日志消息格式，请执行以下操作

  1. 从左侧导航栏中单击 设置。

  2. 在系统选项列表下，单击以选择 日志记录设置。

  3. 在日志记录设置屏幕的底部，单击 编辑。

  4. 修改 API 4XX 错误的日志格式 字段。

用 {} 括起来的项目将在生成日志错误时被替换。可以使用以下变量

  • status_code：API 返回的 HTTP 状态代码

  • user_name：在发出 API 请求时经过身份验证的用户的姓名

  • url_path：正在调用的 URL 的路径部分（即 API 端点）

  • remote_addr：AWX 收到的远程地址

  • error：API 返回的错误消息，或者如果没有指定错误，则为 HTTP 状态的文本

11.3. 排查日志记录问题

11.3.1. API 4XX 错误

您可以通过修改这些消息的日志格式来包括 4XX 错误的 API 错误消息。有关更多详细信息，请参阅 API 4XX 错误配置 部分。

11.3.2. LDAP

您可以启用 LDAP 适配器的日志消息。有关更多详细信息，请参阅 启用 LDAP 的日志记录 部分。

11.3.3. SAML

您可以像启用 LDAP 的日志记录一样启用 SAML 适配器的日志消息。有关更多详细信息，请参阅 启用 LDAP 的日志记录 部分。