FunctionalScaffold/docs/monitoring.md

监控指南

本文档介绍 FunctionalScaffold 的监控体系，包括指标收集、可视化和告警配置。

监控架构

┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
│   应用实例 1    │     │   应用实例 2    │     │   应用实例 N    │
│  /metrics 端点  │     │  /metrics 端点  │     │  /metrics 端点  │
└────────┬────────┘     └────────┬────────┘     └────────┬────────┘
         │                       │                       │
         │    写入指标到 Redis   │                       │
         └───────────────────────┼───────────────────────┘
                                 │
                                 ▼
                    ┌─────────────────────────┐
                    │         Redis           │
                    │    (指标聚合存储)        │
                    └────────────┬────────────┘
                                 │
                                 │ 读取并导出
                                 ▼
                    ┌─────────────────────────┐
                    │      Prometheus         │
                    │    (抓取 /metrics)      │
                    └────────────┬────────────┘
                                 │
                                 │ 查询
                                 ▼
                    ┌─────────────────────────┐
                    │        Grafana          │
                    │      (可视化展示)        │
                    └─────────────────────────┘

快速开始

启动监控服务

cd deployment
docker-compose up -d redis prometheus grafana

访问地址

服务	地址	默认账号
应用 Metrics	http://localhost:8000/metrics	-
Prometheus	http://localhost:9090	-
Grafana	http://localhost:3000	admin/admin

指标说明

HTTP 请求指标

指标	类型	标签	描述
http_requests_total	Counter	method, endpoint, status	HTTP 请求总数
http_request_duration_seconds	Histogram	method, endpoint	HTTP 请求延迟分布
http_requests_in_progress	Gauge	-	当前进行中的请求数

注意事项：

1. 跳过的端点：以下端点不会被记录到指标中，以减少噪音：

   • /metrics - 指标端点本身
   • /healthz - 存活检查
   • /readyz - 就绪检查

2. 路径规范化：带有路径参数的端点会被规范化为模板形式：

   • GET /jobs/a1b2c3d4e5f6 → GET /jobs/{job_id}
   • GET /jobs/xyz123456789 → GET /jobs/{job_id}

   这样可以避免因为不同的路径参数值产生过多的指标标签，导致指标基数爆炸。

算法执行指标

指标	类型	标签	描述
algorithm_executions_total	Counter	algorithm, status	算法执行总数
algorithm_execution_duration_seconds	Histogram	algorithm	算法执行延迟分布

异步任务指标

指标	类型	标签	描述
jobs_created_total	Counter	algorithm	创建的任务总数
jobs_completed_total	Counter	algorithm, status	完成的任务总数
job_execution_duration_seconds	Histogram	algorithm	任务执行时间分布
webhook_deliveries_total	Counter	status	Webhook 发送总数

Prometheus 查询示例

基础查询

# 每秒请求数 (QPS)
rate(http_requests_total[5m])

# 按端点分组的 QPS
sum(rate(http_requests_total[5m])) by (endpoint)

# 请求成功率
sum(rate(http_requests_total{status="success"}[5m]))
/ sum(rate(http_requests_total[5m]))

# 当前并发请求数
http_requests_in_progress

延迟分析

# P50 延迟
histogram_quantile(0.50, rate(http_request_duration_seconds_bucket[5m]))

# P95 延迟
histogram_quantile(0.95, rate(http_request_duration_seconds_bucket[5m]))

# P99 延迟
histogram_quantile(0.99, rate(http_request_duration_seconds_bucket[5m]))

# 平均延迟
rate(http_request_duration_seconds_sum[5m])
/ rate(http_request_duration_seconds_count[5m])

算法分析

# 算法执行速率
sum(rate(algorithm_executions_total[5m])) by (algorithm)

# 算法失败率
sum(rate(algorithm_executions_total{status="error"}[5m]))
/ sum(rate(algorithm_executions_total[5m]))

# 算法 P95 延迟
histogram_quantile(0.95,
  sum(rate(algorithm_execution_duration_seconds_bucket[5m])) by (le, algorithm)
)

异步任务分析

# 任务创建速率
sum(rate(jobs_created_total[5m])) by (algorithm)

# 任务成功率
sum(rate(jobs_completed_total{status="completed"}[5m]))
/ sum(rate(jobs_completed_total[5m]))

# 任务积压（创建速率 - 完成速率）
sum(rate(jobs_created_total[5m])) - sum(rate(jobs_completed_total[5m]))

# Webhook 成功率
sum(rate(webhook_deliveries_total{status="success"}[5m]))
/ sum(rate(webhook_deliveries_total[5m]))

Grafana 仪表板

导入仪表板

1. 打开 Grafana: http://localhost:3000
2. 登录（admin/admin）
3. 进入 Dashboards → Import
4. 上传文件：monitoring/grafana/dashboard.json
5. 选择 Prometheus 数据源
6. 点击 Import

仪表板面板

HTTP 监控区域

• HTTP 请求速率 (QPS) - 每秒请求数趋势
• HTTP 请求延迟 - P50/P95/P99 延迟趋势
• 请求成功率 - 成功率仪表盘
• 当前并发请求数 - 实时并发数
• HTTP 请求总数 - 累计请求数
• 请求分布 - 按端点/状态的饼图

算法监控区域

• 算法执行速率 - 每秒执行次数
• 算法执行延迟 - P50/P95/P99 延迟
• 算法执行总数 - 累计执行数

异步任务监控区域

• 任务创建总数 - 累计创建的任务数
• 任务完成总数 - 累计完成的任务数
• 任务失败总数 - 累计失败的任务数
• 任务成功率 - 成功率仪表盘
• 异步任务速率 - 创建和完成速率趋势
• 异步任务执行延迟 - P50/P95/P99 延迟
• 任务状态分布 - 按状态的饼图
• Webhook 发送状态 - 成功/失败分布

告警配置

告警规则

告警规则定义在 monitoring/alerts/rules.yaml：

groups:
  - name: functional_scaffold_alerts
    interval: 30s
    rules:
      # 高错误率告警
      - alert: HighErrorRate
        expr: rate(http_requests_total{status="error"}[5m]) > 0.05
        for: 5m
        labels:
          severity: warning
        annotations:
          summary: "检测到高错误率"
          description: "端点 {{ $labels.endpoint }} 的错误率为 {{ $value }} 请求/秒"

      # 高延迟告警
      - alert: HighLatency
        expr: histogram_quantile(0.95, rate(http_request_duration_seconds_bucket[5m])) > 1
        for: 5m
        labels:
          severity: warning
        annotations:
          summary: "检测到高延迟"
          description: "端点 {{ $labels.endpoint }} 的 P95 延迟为 {{ $value }}s"

      # 服务不可用告警
      - alert: ServiceDown
        expr: up{job="functional-scaffold"} == 0
        for: 1m
        labels:
          severity: critical
        annotations:
          summary: "服务不可用"
          description: "FunctionalScaffold 服务已停止超过 1 分钟"

      # 异步任务失败率告警
      - alert: HighJobFailureRate
        expr: rate(jobs_completed_total{status="failed"}[5m]) / rate(jobs_completed_total[5m]) > 0.1
        for: 5m
        labels:
          severity: warning
        annotations:
          summary: "异步任务失败率过高"
          description: "算法 {{ $labels.algorithm }} 的异步任务失败率超过 10%"

      # 任务积压告警
      - alert: JobBacklog
        expr: sum(rate(jobs_created_total[5m])) - sum(rate(jobs_completed_total[5m])) > 10
        for: 10m
        labels:
          severity: warning
        annotations:
          summary: "异步任务积压"
          description: "任务创建速率超过完成速率，可能存在积压"

告警级别

级别	描述	响应时间
critical	严重告警，服务不可用	立即响应
warning	警告，性能下降或异常	1 小时内响应
info	信息，需要关注	工作时间内响应

自定义指标

添加新指标

1. 在 config/metrics.yaml 中定义：

custom_metrics:
  my_custom_counter:
    name: "my_custom_counter"
    type: counter
    description: "我的自定义计数器"
    labels: [label1, label2]

  my_custom_histogram:
    name: "my_custom_histogram"
    type: histogram
    description: "我的自定义直方图"
    labels: [label1]
    buckets: [0.1, 0.5, 1, 5, 10]

2. 在代码中使用：

from functional_scaffold.core.metrics_unified import incr, observe

# 增加计数器
incr("my_custom_counter", {"label1": "value1", "label2": "value2"})

# 记录直方图
observe("my_custom_histogram", {"label1": "value1"}, 0.5)

故障排查

指标不显示

1. 检查应用 metrics 端点：

   curl http://localhost:8000/metrics
   

2. 检查 Redis 连接：

   redis-cli ping
   

3. 检查 Prometheus 抓取状态：

   • 访问 http://localhost:9090/targets
   • 确认 functional-scaffold 目标状态为 UP

Grafana 无数据

1. 检查数据源配置：

   • URL 应为 http://prometheus:9090（容器内部）
   • 不是 http://localhost:9090

2. 检查时间范围：

   • 确保选择了正确的时间范围
   • 尝试 "Last 5 minutes"

3. 生成测试流量：

   ./scripts/generate_traffic.sh
   

告警不触发

1. 检查 Prometheus 规则加载：

   • 访问 http://localhost:9090/rules
   • 确认规则已加载

2. 检查告警状态：

   • 访问 http://localhost:9090/alerts
   • 查看告警是否处于 pending 或 firing 状态

参考资料

• Prometheus 文档
• Grafana 文档
• PromQL 查询语言