企业官网建设流程全解析

Wazuh Logcollector 日志采集器详解：六种 log_format 的配置与底层实现

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

Logcollector 是 Wazuh Agent 侧的日志采集引擎，负责从受监控端点的不同日志源读取事件并转发给 Manager 进行分析。本文以 docs/ref/modules/logcollector/collectors.md 为核心，逐一对比syslog、json、eventchannel、eventlog、macos、journald六种日志采集器的适用平台、配置写法和行为差异，并结合src/logcollector/下的源码印证其实现机制，帮助你在跨平台部署时正确选型并排查采集问题。

日志采集器总览

每个日志源通过ossec.conf中的一个<localfile>块声明，其中<log_format>决定使用哪一个采集器。六种采集器的平台适用性如下：

从源码结构看，每种格式在 src/logcollector/src/ 下都有独立的读取实现：read_syslog.c、read_json.c、read_win_event_channel.c、read_win_el.c、read_macos.c、read_journald.c，它们在 src/logcollector/src/logcollector.c 中按log_format分发到对应的读取函数。例如在 src/logcollector/src/logcollector.c 中，当格式为eventchannel但当前 Windows 版本不支持该 API 时，Logcollector 会打印警告"eventchannel not available on this version of Windows"并跳过该采集器，这就是旧版 Windows 上必须回退到eventlog的原因。

完整的配置项参考（包括<socket>段与logcollector.*内部选项）见 配置参考。

syslog — 纯文本文件采集

syslog是最通用的格式，逐行读取纯文本日志文件，是大多数 Linux/macOS 日志文件的标准格式：

<localfile> <location>/var/log/auth.log</location> <log_format>syslog</log_format> </localfile>

<location>字段支持三类写法：

• 静态路径：如/var/log/auth.log；
• 基于日期的模式：使用strftime格式，如/var/log/application-%y-%m-%d.log（会匹配application-26-07-03.log这类按天滚动的文件）；
• 通配符模式：如/var/log/app*.log，可配合<exclude>（正则）与<age>（时间间隔，如7d）缩小扫描范围：

<localfile> <location>/var/log/app*.log</location> <log_format>syslog</log_format> <exclude>\.old$</exclude> <age>7d</age> </localfile>

Windows 平台还允许在路径中使用环境变量，例如%WINDIR%\System32\LogFiles\Firewall\pfirewall.log。

json — JSON 日志文件采集

json采集器同样逐行读取，但要求每一行都是一个合法的 JSON 对象；解析失败的行会被静默丢弃。若配置了<labels>，标签会在事件转发前被注入到每个 JSON 对象中：

<localfile> <location>/var/log/app.json</location> <log_format>json</log_format> <labels> <label key="app">myapp</label> <label key="environment">production</label> </labels> </localfile>

对非 JSON 格式，<labels>则以元数据方式附加到日志事件中。这一行为对应 src/logcollector/src/read_json.c 中对逐行 JSON 解析的实现，意味着生产环境中若混入非法 JSON 行不会导致采集中断，但那些行不会出现在告警数据中——排查"日志丢失"时应先确认该特性。

eventchannel — Windows 事件通道采集

eventchannel采集器使用 Windows EventChannel API（EvtSubscribe/EvtRender）订阅事件通道，适用于 Windows Vista 及以后版本。默认监控System、Application、Security三个通道；Windows 暴露的任何自定义通道都可以添加：

<localfile> <location>Security</location> <log_format>eventchannel</log_format> </localfile>

事件可以用 XPath 查询通过<query>元素过滤：

<localfile> <location>System</location> <log_format>eventchannel</log_format> <query>Event/System[EventID=7040]</query> </localfile>

也支持完整的 QueryList XML 格式，例如只采集错误与严重级别（Level ≤ 3）的事件：

<localfile> <location>System</location> <log_format>eventchannel</log_format> <query> <QueryList> <Query Id="0" Path="System"> <Select Path="System">*[System[(Level&lt;=3)]]</Select> </Query> </QueryList> </query> </localfile>

事件输出格式：Wazuh 5.0 的重大变更

Wazuh 4.x中，Agent 将每个事件包装为包含人类可读消息与原始 XML 的 JSON 对象：

{"Message": "Event description.", "Event": "<Event>...</Event>"}

Wazuh 5.0起，Agent 直接转发EvtRender()返回的原生 Windows 事件 XML，与 Windows 事件查看器的导出格式一致：

<Event xmlns='http://schemas.microsoft.com/win/2004/08/events/event'> <System> <Provider Name='Microsoft-Windows-Security-Auditing' Guid='{54849625-5478-4994-a5ba-3e3b0328c30d}'/> <EventID>4624</EventID> <Channel>Security</Channel> <Computer>HOST</Computer> <Security/> </System> <EventData> <Data Name='SubjectUserName'>SYSTEM</Data> <Data Name='LogonType'>5</Data> ... </EventData> </Event>

与旧格式的关键差异：

• 不再带有<?xml version="1.0" encoding="UTF-8"?>声明；
• 根元素直接是<Event>；
• 命名空间与属性由 EventChannel API 原样保留。

这一点在源码中可以得到印证：src/logcollector/src/read_win_event_channel.c 通过EvtRender(..., EvtRenderEventXml, ...)两次调用（先取缓冲区大小，再渲染）得到事件 XML 原文后直接下发，而 src/logcollector/src/read_win_event_channel.c 中通过EvtSubscribeToFutureEvents/EvtSubscribeStartAfterBookmark标志控制是否只订阅未来事件——这正对应配置项<only-future-events>（默认yes，设为no时处理通道中全部历史事件）。

注意：该输出格式变更仅影响 Windows Agent，<log_format>eventchannel</log_format>配置写法不变。若下游有依赖 4.x 包装格式的解码器或规则，需要在 5.0 上核对兼容性。

eventlog — Windows 传统事件日志采集

eventlog采集器使用传统的OpenEventLog/ReadEventLogAPI，兼容所有 Windows 版本，覆盖Application、Security、System三个日志：

<localfile> <location>Application</location> <log_format>eventlog</log_format> </localfile>

建议：在 Windows Vista 及以上系统上优先使用eventchannel，它能访问更多通道且事件元数据更丰富；eventlog主要作为旧系统的兜底方案。其实现位于 src/logcollector/src/read_win_el.c。

macos — macOS 统一日志系统（ULS）

macos采集器通过logCLI 从 macOS Unified Logging System 采集事件，每个 Agent 只允许一个log_format为macos的<localfile>块（这一点在 src/config/src/localfile-config.c 的 journald/macOS 配置校验中体现为严格的格式互斥检查）：

<localfile> <location>macos</location> <log_format>macos</log_format> <query type="log,trace" level="info">process == "sshd"</query> </localfile>

<query>元素说明：

• type属性：逗号分隔的日志条目类型列表，取值为activity、log、trace；
• level属性：最低日志级别，取值为default、info、debug；
• 查询主体为 predicate 表达式，可使用process、subsystem、category、message等字段。

采集 macOS 认证相关事件的完整示例：

<localfile> <location>macos</location> <log_format>macos</log_format> <query type="trace,log,activity" level="info"> (process == "sudo") or (process == "sessionlogoutd" and message contains "logout is complete.") or (process == "sshd") </query> </localfile>

按子系统过滤：

<localfile> <location>macos</location> <log_format>macos</log_format> <query type="log" level="info"> (subsystem == "com.apple.securityd") or (subsystem == "com.apple.opendirectoryd") </query> </localfile>

实现上，src/logcollector/src/read_macos.c 与 src/logcollector/src/macos_log.c 负责维护log show/log stream子进程流；type属性会在配置解析阶段被w_logcollector_get_macos_log_type()（见 src/config/src/localfile-config.c）翻译成对应的日志类型标志。macOS 下读取 ULS 还需要授予 Agent完整磁盘访问权限，否则采集会静默失败。

journald — systemd journal 采集

journald采集器读取 Linux 上的 systemd journal 条目，支持通过<filter>元素按 journal 字段过滤。过滤值按PCRE2 正则表达式编译，精确匹配需使用锚点^、$：

<localfile> <location>journald</location> <log_format>journald</log_format> <filter field="SYSLOG_IDENTIFIER">^sshd$</filter> </localfile>

可以用多个<filter>组合条件。从源码结构看，过滤条件在配置解析阶段由 src/config/src/localfile-config.c 的journald_add_condition_to_filter()逐个加入过滤器数组，而 src/logcollector/src/read_journald.c 维护全局 journal 上下文：它检测 journal 文件轮转（w_journal_rotation_detected）、按过滤器获取最新条目（w_journal_context_next_newest_filtered），并以 syslog 风格 dump 条目内容。此外 src/config/src/localfile-config.c 中的w_logreader_journald_merge()表明多个 journald 配置块会被合并处理，这与"每 Agent 仅一个 ULS/journal 数据源"的设计相呼应。

典型用法——监控 SSH 认证：

<localfile> <location>journald</location> <log_format>journald</log_format> <filter field="SYSLOG_IDENTIFIER">^sshd$</filter> </localfile>

监控 Docker 容器日志（按容器名）：

<localfile> <location>journald</location> <log_format>journald</log_format> <filter field="CONTAINER_NAME">^my-container$</filter> </localfile>

监控全部通过 journal 传输的 Docker 日志：

<localfile> <location>journald</location> <log_format>journald</log_format> <filter field="_TRANSPORT">^journal$</filter> </localfile>

关键行为差异与排查要点

1. Windows 通道订阅时机：<only-future-events>默认yes，即 Agent 启动后只采集新事件。需要回补历史事件时显式设置为no：

   <localfile> <location>Security</location> <log_format>eventchannel</log_format> <only-future-events>no</only-future-events> </localfile>

2. json 的静默丢行：非法 JSON 行不会报错、不会转发，排查事件缺失时先人工校验每行是否为合法 JSON 对象。

3. journald 过滤是正则而非子串匹配：过滤值按 PCRE2 编译，写sshd会匹配所有包含sshd的SYSLOG_IDENTIFIER；精确匹配请写^sshd$。

4. macOS 单实例限制与权限：只允许一个macos采集块；采集失败时先确认 Agent 拥有完整磁盘访问权限，并可用log show --predicate 'process == "sshd"' --info手动验证 predicate 语法。

5. 状态与调试：查看采集状态文件/var/ossec/var/run/wazuh-logcollector.state（Windows 下为C:\Program Files (x86)\ossec-agent\wazuh-logcollector.state）可了解当前活跃日志源；在/var/ossec/etc/local_internal_options.conf中临时加入logcollector.debug=2并重启 Agent 可获得完整调试输出，便于定位"事件未转发"类问题。

6. 性能与吞吐调优：高日志量场景可通过内部选项调优，如logcollector.input_threads=8、logcollector.queue_size=4096、logcollector.max_lines=50000；文件数量多时相应调大logcollector.max_files与logcollector.rlimit_nofile（后者必须高于前者）。全部logcollector.*选项的取值范围与默认值见 配置参考。

参考

• Log Collector 格式说明
• Logcollector 完整配置参考
• Logcollector 模块概述
• 源码：src/logcollector/src/logcollector.c、src/logcollector/src/read_win_event_channel.c、src/logcollector/src/read_journald.c、src/config/src/localfile-config.c

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