企业官网建设流程全解析

Wazuh Logging 模块配置详解：log_format 参数与 daemon 日志 plain/JSON 双输出实现

【免费下载链接】wazuhWazuh - The Open Source Security Platform. Unified XDR and SIEM protection for endpoints and cloud workloads.项目地址: https://gitcode.com/GitHub_Trending/wa/wazuh

Wazuh 的 Logging 模块通过一个顶层<logging>XML 配置块控制 Manager 与 Agent 上所有 daemon的内部日志格式，支持纯文本（plain）、结构化 JSON 以及两者同时输出（plain,json）三种模式。本文基于配置参考文档 configuration.md，结合仓库中的默认配置文件与 C 语言源码实现（debug_op.c），完整讲解log_format参数的取值与校验规则、双输出机制、两种格式的真实输出样例，以及日志写入底层的锁、文件截断与权限处理等实现细节。

一、Logging 模块的定位与作用范围

Logging 模块决定 Wazuh daemon 日志的格式与输出位置，同时适用于 manager 和 agent 两端。其核心特性如下（见 Logging 模块 README）：

• plain 文本格式：人类可读，便于排障与手工查看；
• JSON 格式：结构化输出，便于接入日志聚合工具（Elasticsearch、Splunk 等）；
• 双输出：同时产生两种格式，兼顾支持排障与 SIEM 接入；
• 全局作用域：从源码结构看，所有 daemon（remoted、analysisd、logcollector 等）共用同一套日志实现，因此该配置一次生效、全局生效。

关键定位信息汇总：

日志文件名的定义可以直接在 debug_op.h 中确认：manager 端LOGFILE为logs/wazuh-manager.log、LOGJSONFILE为logs/wazuh-manager.json；agent 端分别为logs/ossec.log与logs/ossec.json（Windows agent 则为相对路径ossec.log/ossec.json）。这与文档中"JSON 日志与 plain 日志同目录、仅扩展名不同"的说明完全一致。

二、核心参数：log_format

<logging>块中当前唯一的参数是log_format：

• 默认值：plain（源码中当配置缺失时显式置为log_plain = 1; log_json = 0）；
• 允许取值：plain、json、plain,json（逗号分隔，表示同时输出两种格式）；
• 语义说明：
  • plain— 人类可读文本格式（默认）；
  • json— 结构化 JSON 格式，面向日志聚合工具；
  • plain,json— 同时输出两种格式；
• 非法值行为：触发mlerror_exit，daemon 直接启动失败（详见第三节源码分析）。

仓库中的 Manager 默认配置 wazuh-manager.conf 就包含了该配置块，默认使用plain：

<!-- Choose between plain or json format (or both) for internal logs --> <logging> <log_format>plain</log_format> </logging>

各发行版模板 logging.template 中也内置了同样的默认块：

<!-- Choose between "plain", "json", or "plain,json" for the format of internal logs --> <logging> <log_format>plain</log_format> </logging>

三、完整配置示例（三种模式）

以下示例继承自配置参考文档，覆盖全部三种合法取值。注意 manager 默认配置文件的根元素为<wazuh_config>（见 wazuh-manager.conf），agent 侧根元素为<ossec_config>，修改时请保持与既有文件一致。

1. 默认配置（纯文本）

标准 plain 文本日志，面向人工排障：

<ossec_config> <logging> <log_format>plain</log_format> </logging> </ossec_config>

2. 仅 JSON 输出

为接入日志聚合系统（Elasticsearch、Splunk 等）提供结构化日志：

<ossec_config> <logging> <log_format>json</log_format> </logging> </ossec_config>

3. 双输出（Plain + JSON）

同时输出 plain 与 JSON 日志：

<ossec_config> <logging> <log_format>plain,json</log_format> </logging> </ossec_config>

典型使用场景：既保留人类可读日志用于故障排查与支持工单，又将结构化 JSON 持续喂给 SIEM / 日志聚合平台。

四、两种格式的实际输出样例

Plain 格式

2026/07/06 12:34:56 wazuh-remoted: INFO: (1409): Reading authentication keys file. 2026/07/06 12:34:56 wazuh-analysisd: INFO: Started (pid: 12345). 2026/07/06 12:34:57 wazuh-remoted: INFO: Listening on port 1514 (TCP).

格式为：时间戳 标签: 级别: 消息。

JSON 格式

{"timestamp":"2026-07-06T12:34:56+0000","tag":"wazuh-remoted","level":"info","description":"Reading authentication keys file."} {"timestamp":"2026-07-06T12:34:56+0000","tag":"wazuh-analysisd","level":"info","description":"Started (pid: 12345)."} {"timestamp":"2026-07-06T12:34:57+0000","tag":"wazuh-remoted","level":"info","description":"Listening on port 1514 (TCP)."}

对照 _log_function 的 JSON 构造代码，可以确认 JSON 行由cJSON生成，字段包括：

另外从源码结构看，当以调试模式（dbg_flag > 0）运行时，JSON 输出会额外附带pid、file、line、routine四个诊断字段；plain 输出也会相应变为tag[pid] file:line at func():的前缀形式。这对定位多进程环境下的日志来源非常有用。

五、源码级实现剖析

1. 配置解析与校验：os_logging_config()

配置解析入口是 debug_op.c 中的 os_logging_config()。其处理逻辑可以归纳为一条清晰的分支链：

1. 读取主配置：通过OS_ReadXML(WAZUHCONF, &xml)读取主配置文件，并以{"<config 根元素>", "logging", "log_format"}的元素路径提取log_format的内容；
2. 元素缺失：若<log_format>不存在或为空，回退默认值（log_plain = 1, log_json = 0）并打印 debug 级别提示，不报错；
3. 按逗号拆分：使用OS_StrBreak(',', logformat, 2)将取值拆成最多两个部分，逐段w_strtrim去空白后匹配——
   • plain→flags.log_plain = 1
   • json→flags.log_json = 1
   • 其他任何值 → 先复位为默认（plain），随后调用mlerror_exit(LOGLEVEL_ERROR, XML_VALUEERR, "log_format", part)，终止进程、阻止 daemon 启动；
4. 状态暴露：getLoggingConfig() 会把两个标志导出为{"logging":{"plain":"yes","json":"no"}}形式的 JSON，可供控制/查询命令读取当前生效的日志模式。

log_plain与log_json是 debug_op.c 顶部的位域标志（unsigned int log_plain:1; unsigned int log_json:1;）。这也解释了为什么"双输出"是两种格式标志独立置位的自然结果——两者互不排斥，因此plain,json无需特殊处理。

2. 日志写入路径：_log_function()

真正写日志的函数是 _log_function()，每条日志的处理顺序为：

1. 惰性初始化：若模块尚未初始化，首次日志调用会自动触发w_logging_init()→os_logging_config()，即"首次写日志时才解析配置"。若调用方带plain_only标记（用于避免在早期阶段再回调 XML 解析与 cJSON 等外部库），则只置 plain 标志；
2. JSON 输出（!plain_only && flags.log_json时）：写入LOGJSONFILE，用cJSON_PrintUnformatted生成单行 JSON，fflush落盘。Linux 端有一个值得注意的实现细节：文件已存在时以w模式（截断）重开并umask(0006)，且在 root 运行时通过Privsep_GetGroup将文件属组修正为 Wazuh 运行组（ossec全局组）；Windows 端则始终以追加（a）模式打开。从源码结构看，这一"存在即截断"的行为意味着每次 daemon 重启时主日志会被重新建立，实际滚动/归档由 monitord 模块负责；
3. Plain 输出（flags.log_plain时）：写入LOGFILE，先按dbg_flag决定是否附带file:line at func()调试前缀，再输出级别与消息；
4. 并发安全：两个文件的写入都用同一个logging_mutex串行化（w_mutex_lock/unlock），避免多进程/多线程并发写文件造成的行交错；
5. 前台模式回显：daemon_flag == 0（前台运行）时，日志额外通过print_stderr_msg打印到 stderr，方便直接观察启动过程。

代码中一处注释印证了plain_only设计意图："The plain_only flag allows to bypass the JSON output even when it's enabled to avoid the call to external libraries like cJSON"——即在初始化早期路径中刻意绕过 JSON 输出，防止日志函数自身引发递归依赖。

3. 与文档结论的对应关系

六、实操建议与相关文档

• 排障优先：日常运维保持默认plain即可；需要向 SIEM 采集 Wazuh 自身运行日志时，切换为json或plain,json；
• 变更生效方式：该配置在 daemon 初始化阶段读取一次，修改<logging>块后需要重启对应的 Wazuh 服务才能生效；
• 校验预检：由于非法取值会导致进程直接退出，修改配置后建议先在前台或以调试参数启动验证，确认无XML_VALUEERR后再转为常驻服务；
• 与 monitord 配合：日志轮转（rotate）策略由 Monitord 模块管理，与本模块的格式控制互补，可参考 Monitord Configuration；
• 完整的 manager / agent 配置总览分别见 Manager 配置参考 与 Agent 配置参考，本模块的原始参考文档位于 docs/ref/modules/logging/configuration.md。

【免费下载链接】wazuhWazuh - The Open Source Security Platform. Unified XDR and SIEM protection for endpoints and cloud workloads.项目地址: https://gitcode.com/GitHub_Trending/wa/wazuh