可观测性指南

本章介绍 Thurgio 的三类可观测入口如何配合使用：Prometheus 指标（GET /metrics）、订阅健康度聚合（GET /app/read/health）与结构化日志。

概述

三者在 部署指南 的监控检查清单中均有对应项。

Prometheus 接入

认证说明

GET /metrics 归类为公开端点，与 GET /health、GET /ready 一致，无需 ?token= 或 Authorization: Bearer 头。反向代理层应对其做网络级访问控制，禁止公网直接暴露。详见 部署指南 的 Nginx/Caddy 示例——allow 10.0.0.0/8 / deny all 或 remote_ip 匹配。

scrape_config 示例

以下配置可直接放入 prometheus.yml 的 scrape_configs：

scrape_configs:
  - job_name: "thurgio"
    metrics_path: /metrics
    scrape_interval: 15s
    scrape_timeout: 10s
    static_configs:
      - targets: ["127.0.0.1:10100"]
        labels:
          instance: "thurgio-prod-01"

若 Prometheus 与 Thurgio 不在同一内网，经反向代理抓取时改用域名并按需添加 TLS 配置：

scrape_configs:
  - job_name: "thurgio"
    metrics_path: /metrics
    scheme: https
    static_configs:
      - targets: ["thurgio.example.com"]
    # 若反向代理对 /metrics 做了 IP 白名单，Prometheus 需部署在白名单网段内

验证抓取是否生效：

curl -fsS http://127.0.0.1:10100/metrics | head -n 40
# 应返回 Prometheus 文本暴露格式，首行为 # HELP http_requests_total

GET /metrics 的响应为纯文本 Prometheus 暴露格式，非 JSON；每次请求实时计算 process_memory_usage_mb（VmRSS）与熔断器快照并追加渲染线程池块（见 crates/thurgio-server/src/routes/public.rs:metrics 与 crates/thurgio-server/src/metrics.rs:render/render_renderer_metrics）。

OTLP 可选链路

thurgio-infra/src/metrics.rs 定义的 MetricsRecorder 在启用 otlp feature 时经 OtelMetrics 写入全局 OpenTelemetry Meter Provider（OTEL_EXPORTER_OTLP_ENDPOINT，默认 http://localhost:4317，gRPC）。MetricsCollector 对未映射的指标名会转发至 fallback recorder（set_fallback），未启用 otlp 时直接丢弃。因此下表标注为 OTLP 的指标仅在 cargo run -p thurgio-cli --features otlp 或对应 release 构建下可见；Prometheus 标注的指标无论是否启用 OTLP 均出现在 /metrics。

指标参考

名称与类型以源码为准。来源文件：

• crates/thurgio-infra/src/metrics.rs（names 模块，规范名称单一来源）
• crates/thurgio-server/src/metrics.rs（MetricsCollector::render 与 render_renderer_metrics 的 Prometheus 渲染）

1. HTTP 请求（MetricsCollector 直接渲染）

2. 构建与更新管线

3. 缓存

4. 熔断器（Circuit Breaker）

快照来源为 CircuitBreakerPool::snapshots()，与 GET /app/read/health 的 failure_count 同源；键格式 circuit_breaker:{identity} 由 thurgio-infra::circuit_breaker::SNAPSHOT_KEY_PREFIX 单一拥有。

5. 资源与内存

6. 渲染线程池（render_renderer_metrics）

由 AppState::renderer().pool_metrics() 在 /metrics 末尾追加，HELP/TYPE/value 三行一组：

池参数由环境变量 THURGIO_RENDERER_MIN_THREADS / THURGIO_RENDERER_MAX_THREADS 调整（默认 min 1 / max 64），见 部署指南。

告警建议

下列规则为 Prometheus groups YAML 片段，可直接加入 prometheus.yml 的 rule_files 或 Alertmanager 规则文件。阈值按需调整。

groups:
  - name: thurgio
    interval: 30s
    rules:
      # 1. 熔断器 Open 超过 10 分钟
      - alert: ThurgioBreakerOpen
        expr: circuit_breaker_state == 1
        for: 10m
        labels:
          severity: warning
        annotations:
          summary: "订阅 {{ $labels.name }} 熔断器持续 Open"
          description: "该 provider/snippet 已连续 10 分钟拒绝抓取，检查上游可用性与网络。"

      # 2. 任意订阅拉取失败率升高（5 分钟内失败 > 0）
      - alert: ThurgioProviderFailure
        expr: increase(build.provider.failure[5m]) > 0
        labels:
          severity: warning
        annotations:
          summary: "provider {{ $labels.name }} 拉取失败"
          description: "5 分钟内出现拉取失败，对照日志 trace_id 排查上游与解析错误。"

      # 3. 渲染线程池积压过高
      - alert: ThurgioRendererBacklogHigh
        expr: renderer_backlog_smoothed > 20
        for: 5m
        labels:
          severity: warning
        annotations:
          summary: "渲染线程池积压过高"
          description: "平滑积压 {{ $value }} 超过 20，考虑调大 THURGIO_RENDERER_MAX_THREADS 或降低并发渲染压力。"

      # 4. 限流误伤（正常流量下不应出现 429）
      - alert: ThurgioRateLimited
        expr: increase(http_rate_limited_total[5m]) > 0
        labels:
          severity: warning
        annotations:
          summary: "请求被限流"
          description: "5 分钟内出现 429，检查是否误伤正常客户端，必要时调整 THURGIO_RATE_LIMIT_* 或反向代理限流配置。"

      # 5. 配置热重载持续失败
      - alert: ThurgioConfigReloadFailed
        expr: increase(config_reload_failed_total[10m]) > 0
        labels:
          severity: critical
        annotations:
          summary: "配置热重载失败"
          description: "10 分钟内出现重解析失败，旧配置仍生效但新配置未生效，检查 YAML 语法与模板存在性。"

可选补充（按需启用）：

      # 6. 内存基线异常增长（按实例规格调整阈值）
      - alert: ThurgioMemoryHigh
        expr: process_memory_usage_mb > 800
        for: 10m
        labels:
          severity: warning
        annotations:
          summary: "内存占用过高"
          description: "RSS {{ $value }} MB 超过 800 MB，检查是否存在订阅膨胀或渲染泄漏。"

与 GET /app/read/health 的分工

使用建议：

• 告警走 /metrics（Prometheus 规则见上节）。
• 巡检/排障走 /app/read/health：overall == degraded 时检查 items 中 breaker == open 的条目，结合 failure_count 与 last_failure_at 判断故障时长；last_update_at == null 表示该订阅从未成功抓取。
• Dashboard 可同时消费两者：时序图用 /metrics，订阅列表用 /app/read/health（与内置 UI 的数据源一致，见 docs/src/dashboard.md）。

日志

Thurgio 经 tracing + tracing-subscriber 输出日志到 stdout/stderr，由 systemd 的 journald 或容器日志驱动收集。日志级别由 RUST_LOG 控制，格式由 RUST_LOG_FORMAT 控制（见 部署指南 与 thurgio-infra::init_logger）。

常用排障命令：

# 跟随日志
journalctl -u thurgio -f

# 仅看熔断器状态切换
journalctl -u thurgio | grep "circuit breaker"

# 仅看失败请求（结构化日志）
RUST_LOG_FORMAT=json thurgio serve | jq 'select(.fields.trace_id != null)'

# 提升更新管线的日志级别
RUST_LOG="thurgio_app_update=debug,thurgio_request=debug" thurgio serve

关键日志信号：

• 熔断器：circuit breaker opened after N failures、circuit breaker reopened after half-open failure、circuit breaker open for <name>。
• 配置热重载失败：config_reload_failed_total 递增时伴随 error! 日志，旧配置保持生效。
• 事件总线：domain event: provider '<name>' update failed 等（thurgio-app-build/src/event_handlers.rs）。

延伸阅读

• 部署指南 — 生产检查清单、反向代理与 systemd 配置
• API 参考 — GET /metrics 与 GET /app/read/health 的完整响应契约
• 架构 — 统一错误类型（ErrorKind）与熔断器设计
• design/debugging.md — RUST_LOG 过滤速查表
• design/specs/spec-circuit-breaker.md — 熔断器键格式与持久化契约