Vector apache_metrics 源：基于 mod_status 抓取 Apache HTTPD 服务器指标
【免费下载链接】vector A high-performance observability data pipeline. 
项目地址: https://gitcode.com/GitHub_Trending/vect/vector
Vector 的 apache_metrics 源用于周期性地从 Apache HTTP Server（HTTPD）的 mod_status 端点抓取纯文本状态页，并将其解析为结构化指标（请求量、CPU 时间、连接数、worker 状态、scoreboard 分布等）输出到下游管道。读完本文，你可以掌握该源的完整配置参数、mod_status 字段与 Vector 指标名之间的映射关系、ExtendedStatus On/Off 对指标可用性的影响，以及源码层面 up 指标在成功、非 200 响应和连接失败三种场景下的不同取值逻辑。
组件概览与运行模型
从组件元数据（website/cue/reference/components/sources/apache_metrics.cue）可以确认该源的关键属性：
- 交付语义：at_least_once（至少一次）；
- 部署角色：适用于 daemon（独立守护进程）和 sidecar（边车）两种部署形态；
- 开发状态：stable（稳定）；
- 出站方式：batch（批量），且组件为无状态（stateful: false）；
- 能力特征：不支持端到端确认（acknowledgements）、不支持 checkpoint，但支持代理（proxy）配置，即抓取请求可走全局 proxy 设置；
- 前置要求：Apache 服务端必须启用 Apache Status module（mod_status），并在 Apache 配置中开放 /server-status 路径。
官方文档页 website/content/en/docs/reference/configuration/sources/apache_metrics.md 正是由该 CUE 元数据经 layouts/docs/component.html 模板渲染生成，因此 CUE 文件中的字段说明与配置生成文件是理解本组件最权威的依据。
一个典型的 Apache 侧前提配置如下（需按部署环境调整访问控制）：
<IfModule mod_status.c>
<Location /server-status>
SetHandler server-status
Require local
</Location>
ExtendedStatus On
</IfModule>
其中 ExtendedStatus On 决定了状态页中是否包含 CPU 与流量类字段（下文会说明它对指标输出的具体影响）。
配置参数详解
apache_metrics 源由 src/sources/apache_metrics/mod.rs 中的 ApacheMetricsConfig 结构体定义，配置元数据见 website/cue/reference/components/sources/generated/apache_metrics.cue：
| endpoints | string 数组 | 是 | 无 | 要抓取指标的全部 mod_status 端点 URL 列表，例如 http://localhost:8080/server-status/?auto |
| scrape_interval_secs | 无符号整数（秒） | 否 | 15 | 两次抓取之间的间隔 |
| namespace | 字符串 | 否 | "apache" | 输出指标的命名空间；置为空字符串时禁用命名空间 |
完整配置示例如下，各字段均与源码 GenerateConfig 默认值（mod.rs#L59-L68）保持一致，可直接复制修改：
sources:
apache:
type: apache_metrics
endpoints:
– "http://localhost:8080/server-status/?auto"
scrape_interval_secs: 15
namespace: "apache"
几点实现细节值得注意：
- endpoints 支持任意多个 URL，每个端点独立抓取，指标上通过 endpoint 与 host 标签区分来源（见下文输出部分）；
- scrape_interval_secs 在源码中经 serde_with::DurationSeconds<u64> 序列化为秒数（mod.rs#L38-L42），默认值由 default_scrape_interval_secs() 返回 15 秒；
- namespace 的默认值函数为 default_namespace() -> "apache"（mod.rs#L55-L57），在 build 时若为空串会被过滤为 None，即所有指标不带命名空间（mod.rs#L81）；
- 该源仅输出指标（metrics）一类事件：outputs() 返回 SourceOutput::new_metrics()，且 can_acknowledge() 恒为 false（mod.rs#L93-L99）。
工作原理：从定时抓取到指标输出
核心抓取逻辑位于 src/sources/apache_metrics/mod.rs 的 apache_metrics() 函数，其调用链可以概括为：
- 返回 200 OK：完整收集响应体，交给 parser::parse() 解析，并在解析结果链尾追加一条 up = 1.0（Gauge）指标；
- 返回其他 HTTP 状态码（如 404）：不解析响应体，但仍然发布 up = 1.0——源码注释明确说明这是沿用 Prometheus 社区 apache_exporter 的语义（测试文件中的注释引用了该模式，见 mod.rs#L439-L441），即"端点可达、服务在响应"仍视为 up；
- 连接级错误（网络不可达、超时等）：发布 up = 0.0 指标，方便基于 up == 0 配置告警。
此外，抓取过程还会发出若干内部遥测事件（定义于 src/internal_events/apache_metrics.rs）：
- ApacheMetricsEventsReceived：记录成功接收的事件数与字节数，计入 component_received_events_total / component_received_event_bytes_total；
- ApacheMetricsParseError：某字段解析失败时记录，计入 component_errors_total（stage=processing、error_type=parser_failed）；
- 另配合通用 HTTP 客户端事件 EndpointBytesReceived、HttpClientHttpError、HttpClientHttpResponseError、StreamClosedError。
文档元数据中还声明了两个标准遥测指标可供监控本源自身：http_client_responses_total 与 http_client_response_rtt_seconds。
输出指标与 mod_status 字段映射
解析器实现见 src/sources/apache_metrics/parser.rs。parse() 函数将状态页按行切分为 key: value 对（注意使用 HashMap 聚合，因为某些 Apache 版本会把 BusyWorkers/IdleWorkers 重复输出两行），再逐字段映射为 Vector 指标。映射关系与 CUE 输出定义 对应如下（默认命名空间 apache）：
| Total Accesses | access_total | counter | — | 需 ExtendedStatus On |
| ConnsTotal / ConnsAsyncWriting / ConnsAsyncKeepAlive / ConnsAsyncClosing | connections | gauge | state: total / writing / keepalive / closing | 无 |
| CPULoad | cpu_load | gauge | — | 需 ExtendedStatus On |
| CPUUser / CPUSystem / CPUChildrenUser / CPUChildrenSystem | cpu_seconds_total | gauge（counter 语义，见注） | type: user / system / children_user / children_system | 需 ExtendedStatus On |
| Total Duration | duration_seconds_total | counter | — | 需 ExtendedStatus On |
| Scoreboard | scoreboard | gauge | state: 见字符映射表 | 无 |
| Total kBytes | sent_bytes_total | counter | — | 需 ExtendedStatus On，值按 KB×1024 换算为字节 |
| —（由响应状态合成） | up | gauge | — | 200 或非 200 时为 1，连接失败为 0 |
| ServerUptimeSeconds | uptime_seconds_total | counter | — | 无 |
| BusyWorkers / IdleWorkers | workers | gauge | state: busy / idle | 无 |
所有指标统一携带两个基础标签：endpoint（抓取来源的绝对 URL）与 host（Apache 服务器主机名）。
有两处实现细节值得在查询时留意：
Scoreboard 字符映射
Scoreboard 一行是 MPM worker 状态的字符画，每个字符代表一个 worker 所处阶段。解析器内置的字符→状态映射表（parser.rs#L7-L23）为：
| _ | waiting | 尚未服务过请求 |
| S | starting | 正在启动 |
| R | reading | 读取请求头 |
| W | sending | 发送响应头 |
| K | keepalive | 等待下一请求 |
| D | dnslookup | 正在进行 DNS 解析 |
| C | closing | 关闭连接 |
| L | logging | 写日志 |
| G | finishing | 完成请求 |
| I | idle_cleanup | 空闲清理 |
| . | open | 已打开连接但尚未开始服务 |
解析器对字符串做计数后，为全部 11 种状态各输出一条 scoreboard gauge 指标（不存在时计数为 0），因此可用于监控请求在 MPM 各阶段的堆积分布。
解析失败行为与测试依据
单个字段数值非法（例如 ServerUptimeSeconds: not a number）不会中断整次抓取：parse() 返回的是 Result<Metric, ParseError> 迭代器，主流程在 mod.rs#L206-L217 中对每个 Err 发出 ApacheMetricsParseError 事件并跳过该指标，其余指标正常输出。parser.rs 的 test_parse_failure 用例即验证了这一"部分失败、部分成功"的行为。
组件级集成测试位于 mod.rs 末尾：
- test_apache_up：用本地 hyper 服务器返回真实 mod_status 文本，断言 up = 1.0 且 endpoint/host 标签已脱敏（配置中使用 http://foo:bar@{addr}/metrics，期望标签里不含凭证）；
- test_apache_error：端点返回 404 时仍断言 up = 1.0，与上文非 200 语义一致；
- test_apache_down：地址无人监听时断言 up = 0.0。
这些测试同时展示了 mod_status 文本的实际形态（含 ExtendedStatus On 时的 Total Accesses、CPUUser、Scoreboard 等行），可作为理解字段映射的原始样例。
小结
apache_metrics 是一个轻量、稳定的拉取式指标源：仅需三个参数即可指向任意多个开启 mod_status 的 HTTPD 实例，按默认 15 秒间隔输出访问计数、CPU 时间、字节量、连接状态、worker 与 scoreboard 分布共十余条指标，并以 up 指标天然支持存活告警。部署时的三个关键点是：服务端启用 mod_status（建议 ExtendedStatus On 以获得完整指标集）、endpoints 写 ?auto 形式的纯文本端点、需要代理时依赖 Vector 全局 proxy 配置即可。
【免费下载链接】vector A high-performance observability data pipeline. 项目地址: https://gitcode.com/GitHub_Trending/vect/vector
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
