跳转至

监控和诊断配置

本文引用的文件 - src/logging/runtime_logger.v - src/http_stats.v - src/config/v2_config.v - src/config/v2_plan_compiler.v - src/engine_runtime.v - src/admin/context.v - admin/ui/app.js - README.md - articles/11-observability.md - src/ws/types.v - src/upstream/types.v - src/codex/rpc.v - src/upstream/provider/codex/rpc.v

目录

  1. 简介
  2. 项目结构
  3. 核心组件
  4. 架构总览
  5. 详细组件分析
  6. 依赖关系分析
  7. 性能考量
  8. 故障排查指南
  9. 结论
  10. 附录

简介

本文件面向生产环境的可观测性与运维，系统化说明 vhttpd 的监控与诊断配置方法，覆盖以下方面： - 性能指标采集与导出（请求延迟、吞吐量、错误率） - 日志记录配置（级别、输出格式、轮转策略） - 调试信息输出（堆栈跟踪、变量快照、性能分析数据） - 健康检查端点（服务状态、依赖可用性、资源使用） - 告警规则（阈值、通知渠道、升级策略） - 分布式追踪（Trace ID 传播、Span 收集、链路分析） - 监控仪表板与可视化展示方案

项目结构

vhttpd 的可观测性由“运行时统计 + Admin Plane 暴露 + 事件日志 + 可选追踪”构成。关键位置如下： - 运行时计数器与统计：HTTP 层计数、引擎队列与池状态 - Admin Plane 接口：/health、/admin/stats、/admin/workers、/admin/runtime 等 - 事件日志：NDJSON 事件流，便于外部采集与分析 - 追踪配置：V2 配置模型中的 tracing 子项 - 管理界面：Admin UI 聚合展示运行态与拓扑

graph TB
subgraph "运行时"
HTTP["HTTP 统计<br/>HttpStats"]
Engine["引擎运行时<br/>EngineRuntime.metrics()"]
Logger["日志器<br/>RuntimeLogger.configure()"]
TracingCfg["追踪配置<br/>V2TracingSpec"]
end
subgraph "管理平面"
Health["/health"]
Stats["/admin/stats"]
Workers["/admin/workers"]
Runtime["/admin/runtime"]
UI["Admin UI<br/>app.js"]
end
subgraph "外部系统"
Prometheus["Prometheus 抓取"]
LogAgg["日志聚合(NDJSON)"]
TraceExporter["追踪导出器"]
end
HTTP --> Stats
Engine --> Runtime
Logger --> LogAgg
TracingCfg --> TraceExporter
Stats --> UI
Workers --> UI
Runtime --> UI
Stats --> Prometheus
Runtime --> Prometheus

图表来源 - src/http_stats.v:1-32 - src/engine_runtime.v:234-271 - src/logging/runtime_logger.v:1-42 - src/config/v2_config.v:59-72 - README.md:1147-1346 - admin/ui/app.js:265-290

章节来源 - src/http_stats.v:1-32 - src/engine_runtime.v:234-271 - src/logging/runtime_logger.v:1-42 - src/config/v2_config.v:59-72 - README.md:1147-1346 - admin/ui/app.js:265-290

核心组件

  • 运行时计数器
  • HTTP 层计数器：请求总数、错误数、超时数、流式响应数、管理动作数
  • 引擎层指标：队列等待/拒绝/超时、当前队列深度、池大小、后端模式、容量与超时
  • Admin Plane 端点
  • /health：存活探针
  • /admin/stats：进程级统计（含队列相关累计值）
  • /admin/workers：工作池快照
  • /admin/runtime：能力与活跃连接/会话计数，内嵌 stats
  • 事件日志
  • NDJSON 事件流，包含 http.request、worker.、upstream.、error 等类型
  • 追踪配置
  • V2 配置中 observability.tracing 支持启用、导出器、端点与采样率
  • 管理界面
  • Admin UI 聚合展示应用、监听器、流水线、Relay、运行态与健康状态

章节来源 - src/http_stats.v:1-32 - src/engine_runtime.v:234-271 - README.md:1147-1346 - articles/11-observability.md:313-371 - src/config/v2_config.v:59-72 - admin/ui/app.js:265-290

架构总览

下图展示了从请求进入、统计计数、到对外暴露与外部采集的整体流程。

sequenceDiagram
participant Client as "客户端"
participant Server as "HTTP 服务器"
participant Stats as "HttpStats"
participant Engine as "EngineRuntime"
participant Admin as "Admin Plane"
participant UI as "Admin UI"
participant Prom as "Prometheus"
participant Log as "日志聚合"
Client->>Server : "HTTP 请求"
Server->>Stats : "inc_requests()/inc_errors()/inc_timeouts()"
Server->>Engine : "request_started()/request_finished()"
Engine-->>Admin : "metrics() 返回队列/池状态"
Admin-->>UI : "GET /admin/stats, /admin/runtime"
Admin-->>Prom : "抓取 /admin/metrics"
Server-->>Log : "写入 NDJSON 事件"

图表来源 - src/http_stats.v:1-32 - src/engine_runtime.v:234-271 - README.md:1147-1346 - articles/11-observability.md:406-433

详细组件分析

性能指标采集与导出

  • 指标定义与更新
  • HTTP 层通过 HttpStats 维护请求、错误、超时、流式与管理动作计数
  • 引擎层通过 EngineRuntime.metrics() 暴露队列等待/拒绝/超时、当前深度、池大小、后端模式、容量与超时等
  • 对外暴露
  • /admin/stats 提供进程级统计（含 worker_queue_* 累计值）
  • /admin/runtime 提供能力与活跃连接/会话计数，并内嵌 stats
  • Admin UI 聚合展示这些指标
  • 外部采集
  • 文档示例给出 Prometheus 抓取路径与自定义 Metrics 注入方式（在 Worker 侧）
classDiagram
class HttpStats {
+requests_total i64
+errors_total i64
+timeouts_total i64
+streams_total i64
+admin_actions_total i64
+inc_requests()
+inc_errors()
+inc_timeouts()
+inc_streams()
+inc_admin_actions()
}
class EngineRuntime {
+metrics() EngineRuntimeMetrics
+request_started(socket_path)
+request_finished(port, socket_path)
}
class AdminEndpoints {
+"/admin/stats"
+"/admin/runtime"
+"/admin/workers"
}
HttpStats <.. AdminEndpoints : "读取计数"
EngineRuntime <.. AdminEndpoints : "读取队列/池指标"

图表来源 - src/http_stats.v:1-32 - src/engine_runtime.v:234-271 - README.md:1147-1346

章节来源 - src/http_stats.v:1-32 - src/engine_runtime.v:234-271 - README.md:1147-1346 - admin/ui/app.js:265-290 - articles/11-observability.md:406-433

日志记录配置

  • 日志级别
  • 默认级别按构建模式决定；可通过环境变量 VHTTPD_LOG_LEVEL 动态设置（debug/info/warn/error/fatal）
  • 初始化时调用 configure() 设置全局 logger 级别与本地时间
  • 输出格式与事件日志
  • 事件日志以 NDJSON 形式输出，包含多种 kind（http.request、worker.、upstream.、error 等）
  • 建议配合 logrotate 进行轮转，并通过信号通知进程重新打开文件句柄
  • 归档策略
  • 实时日志、压缩日志、统计摘要分别采用不同保留期
flowchart TD
Start(["启动"]) --> ReadEnv["读取 VHTTPD_LOG_LEVEL"]
ReadEnv --> Parse{"解析成功?"}
Parse --> |是| SetLevel["设置日志级别"]
Parse --> |否| DefaultLevel["使用默认级别(prod=warn, dev=info)"]
SetLevel --> Configure["configure(): set_local_time(true)"]
DefaultLevel --> Configure
Configure --> Emit["写入 NDJSON 事件日志"]
Emit --> Rotate["logrotate 轮转并发送 USR1 重开文件"]

图表来源 - src/logging/runtime_logger.v:1-42 - articles/11-observability.md:436-467 - articles/11-observability.md:313-371

章节来源 - src/logging/runtime_logger.v:1-42 - articles/11-observability.md:313-371 - articles/11-observability.md:436-467

调试信息输出配置

  • 调试开关
  • 非 prod 模式下启用 debug_log 输出带标签的调试片段（限制长度），用于 RPC/协议调试
  • 堆栈与变量快照
  • 上游活动快照包含 trace_id、worker_error、error_class、commands 等字段，便于定位问题
  • 示例 PHP Profiler 捕获外部请求调用栈与耗时
  • 性能分析数据
  • 引擎运行时 metrics 提供队列与池维度指标，辅助性能分析
sequenceDiagram
participant Upstream as "上游事件"
participant WS as "WebSocket 处理"
participant Snap as "UpstreamActivitySnapshot"
participant Admin as "/admin/runtime/websockets"
Upstream->>WS : "事件到达"
WS->>Snap : "填充 trace_id/worker_error/error_class/commands"
Admin-->>Snap : "分页查询最近活动"

图表来源 - src/ws/types.v:311-359 - src/upstream/types.v:223-265 - src/codex/rpc.v:291-317 - src/upstream/provider/codex/rpc.v:259-281

章节来源 - src/codex/rpc.v:291-317 - src/upstream/provider/codex/rpc.v:259-281 - src/ws/types.v:311-359 - src/upstream/types.v:223-265

健康检查端点配置

  • 内置端点
  • GET /health：管理平面存活检查，返回 200 OK
  • GET /admin/stats：进程级统计（含 uptime_seconds、各类累计计数）
  • GET /admin/runtime：能力与活跃连接/会话计数，内嵌 stats
  • GET /admin/workers：工作池快照（含 alive、inflight_requests、served_requests 等）
  • 访问控制
  • 当未设置 token 时，管理端口开放；否则需携带 x-vhttpd-admin-token 或 admin_token 查询参数
  • 端口暴露模型
  • admin-port=0：/admin/* 在服务数据面端口提供
  • admin-port>0：/admin/* 仅在服务管理面端口提供
flowchart TD
Probe["健康探针"] --> Health["GET /health"]
Probe --> Stats["GET /admin/stats"]
Probe --> Runtime["GET /admin/runtime"]
Probe --> Workers["GET /admin/workers"]
Auth{"是否配置 token?"}
Auth --> |否| Open["管理端口直接访问"]
Auth --> |是| Header["校验 x-vhttpd-admin-token"]

图表来源 - README.md:1147-1346

章节来源 - README.md:1147-1346

告警规则配置

  • 推荐规则（基于文档示例）
  • Worker 池耗尽：无空闲 Worker 持续一定时间
  • Worker 队列积压：队列长度超过阈值持续一段时间
  • 高错误率：单位时间内错误率超阈
  • 上游连接断开：上游连接数为 0
  • MCP 会话接近上限：会话数接近配置上限
  • 通知渠道与升级策略
  • 通过 Prometheus Alertmanager 将告警路由至邮件、IM、电话等渠道
  • 根据 severity 标签进行升级（warning -> critical）

章节来源 - articles/11-observability.md:469-526

分布式追踪配置

  • 配置项
  • observability.tracing.enabled：是否启用
  • observability.tracing.exporter：导出器名称
  • observability.tracing.endpoint：导出端点
  • observability.tracing.sample_rate：采样率
  • Trace ID 传播
  • 上游活动与运行时会话均包含 trace_id 字段，便于跨组件关联
  • Span 收集与链路分析
  • 结合外部追踪后端（如 Jaeger/Zipkin/OpenTelemetry Collector）进行收集与可视化
classDiagram
class V2ObservabilitySpec {
+event_log string
+log_level string
+tracing V2TracingSpec
}
class V2TracingSpec {
+enabled bool
+exporter string
+endpoint string
+sample_rate f64
}
class UpstreamActivitySnapshot {
+trace_id string
+worker_handled bool
+worker_error string
+error_class string
+commands []
}
class UpstreamRuntimeSession {
+trace_id string
+started_at_unix i64
}
V2ObservabilitySpec --> V2TracingSpec
UpstreamActivitySnapshot --> V2TracingSpec : "使用 trace_id"
UpstreamRuntimeSession --> V2TracingSpec : "使用 trace_id"

图表来源 - src/config/v2_config.v:59-72 - src/config/v2_plan_compiler.v:182-203 - src/ws/types.v:311-359 - src/upstream/types.v:223-265

章节来源 - src/config/v2_config.v:59-72 - src/config/v2_plan_compiler.v:182-203 - src/ws/types.v:311-359 - src/upstream/types.v:223-265

监控仪表板与可视化

  • Admin UI
  • 聚合显示应用数量、监听器、流水线、Relay、运行态指标、健康状态等
  • Prometheus + Grafana
  • 抓取 /admin/metrics（参考文档示例），在 Grafana 中创建面板展示 QPS、错误率、延迟分位、队列深度、池大小等
  • 事件日志分析
  • 使用 jq 对 NDJSON 进行过滤、聚合与导出，快速定位异常与趋势

章节来源 - admin/ui/app.js:265-290 - admin/ui/app.js:289-295 - admin/ui/app.js:656-675 - articles/11-observability.md:406-433 - articles/11-observability.md:313-371

依赖关系分析

  • 组件耦合
  • Admin Plane 依赖运行时统计与引擎指标，向 UI 与外部采集器暴露
  • 事件日志与追踪配置独立于业务逻辑，便于扩展
  • 外部依赖
  • Prometheus 抓取管理端点
  • 日志聚合系统消费 NDJSON
  • 追踪导出器接收 Span/Trace 数据
graph LR
Admin["Admin Plane"] --> UI["Admin UI"]
Admin --> Prom["Prometheus"]
Runtime["运行时统计"] --> Admin
Engine["引擎指标"] --> Admin
Logger["日志器"] --> LogAgg["日志聚合"]
Tracing["追踪配置"] --> Exporter["追踪导出器"]

图表来源 - README.md:1147-1346 - src/engine_runtime.v:234-271 - src/logging/runtime_logger.v:1-42 - src/config/v2_config.v:59-72

章节来源 - README.md:1147-1346 - src/engine_runtime.v:234-271 - src/logging/runtime_logger.v:1-42 - src/config/v2_config.v:59-72

性能考量

  • 指标粒度与开销
  • 计数器为原子累加，开销低；建议在热点路径避免频繁字符串拼接
  • 队列与池
  • 关注 worker_queue_depth、pool_size、queue_capacity、queue_timeout_ms，合理调优以避免拥塞
  • 日志与追踪
  • 在高吞吐场景下，谨慎开启高详细度日志与高采样率追踪，避免 I/O 与序列化瓶颈

[本节为通用指导，不直接分析具体文件]

故障排查指南

  • Worker 无响应
  • 查看 /admin/workers 与 /admin/stats，确认 inflight_requests 与累计错误
  • 重启单个或全部 Worker（POST /admin/workers/restart）
  • 上游连接频繁断开
  • 查看 /admin/runtime/upstreams 与事件日志，定位 provider/instance 状态
  • MCP 会话无法创建
  • 查看 /admin/runtime/mcp 与事件日志，检查 max_sessions 与 pending 丢弃计数
  • 内存持续增长
  • 监控 memory_mb 与 per-worker 指标，考虑设置 max_requests 定期重启

章节来源 - README.md:1147-1346 - articles/11-observability.md:530-619

结论

vhttpd 提供了完善的监控与诊断能力：通过运行时计数器与引擎指标、Admin Plane 端点、NDJSON 事件日志以及可选的分布式追踪，形成从采集、存储到可视化的完整闭环。结合合理的告警规则与日志轮转策略，可在生产环境中实现高效的问题定位与稳定性保障。

[本节为总结性内容，不直接分析具体文件]

附录

  • 常用命令与示例
  • 查看运行时统计与 Worker 状态
  • 抓取 Prometheus 指标
  • 分析 NDJSON 事件日志
  • 配置参考
  • observability.event_log、observability.log_level、observability.tracing.*
  • 管理平面端口与认证模型

章节来源 - README.md:1147-1346 - articles/11-observability.md:406-433 - articles/11-observability.md:313-371 - src/config/v2_config.v:59-72