如何用Prometheus和FastAPI打造任务监控的“火眼金睛”？

1. 生产级任务系统任务性能监控

在现代 Web 应用中，任务性能监控是保障系统稳定性的关键环节。FastAPI 提供了强大的工具来实现对后台任务、异步任务和定时任务的性能监控。

1.1 性能监控架构原理

任务性能监控的本质是通过收集关键指标来评估系统健康状况：

graph TD A[任务启动] --> B[指标收集] B --> C{指标类型} C --> D[时间指标
如任务执行时长] C --> E[资源指标
如CPU/内存使用] C --> F[业务指标
如处理数据量] D --> G[监控系统] E --> G F --> G G --> H[可视化仪表盘]

核心监控指标包括：

1. 任务执行时长：从任务启动到完成的耗时
2. 任务吞吐量：单位时间内处理的任务数量
3. 错误率：失败任务占总任务的比例
4. 资源利用率：CPU、内存、网络等资源消耗

1.2 集成 Prometheus 监控方案

以下是使用 Prometheus 进行任务监控的实现：

# requirements.txt
fastapi==0.95.2
prometheus_client==0.17.0
uvicorn==0.22.0

from fastapi import FastAPI, BackgroundTasks
from prometheus_client import Counter, Summary, generate_latest, REGISTRY
import time

app = FastAPI()

# 定义监控指标
TASK_DURATION = Summary(
    'task_processing_seconds', 
    'Time spent processing task',
    ['task_type']
)

TASK_COUNT = Counter(
    'tasks_processed_total',
    'Total number of processed tasks',
    ['task_type', 'status']
)

@app.get("/metrics")
async def metrics():
    return generate_latest(REGISTRY)

def background_task(task_id: int):
    """后台任务示例"""
    start_time = time.time()
    task_type = "background"
    
    try:
        # 模拟任务处理
        time.sleep(0.5)
        # 业务逻辑...
        
        # 记录成功指标
        TASK_COUNT.labels(task_type=task_type, status="success").inc()
    except Exception:
        # 记录失败指标
        TASK_COUNT.labels(task_type=task_type, status="fail").inc()
    finally:
        # 记录执行时间
        duration = time.time() - start_time
        TASK_DURATION.labels(task_type=task_type).observe(duration)

@app.post("/start-task")
async def start_task(background_tasks: BackgroundTasks):
    """启动后台任务"""
    task_id = 42  # 实际应用中应生成唯一ID
    background_tasks.add_task(background_task, task_id)
    return {"message": "Task started", "task_id": task_id}

1.3 关键实现解析

1. 指标定义：

   • Summary：用于统计任务执行时间的分布
   • Counter：用于统计任务成功/失败次数
   • 标签系统（label）允许按任务类型分类

2. 监控端点：

   • /metrics 端点暴露 Prometheus 格式的指标数据
   • Prometheus 服务器定时拉取这些数据进行存储

3. 任务监控：

   • start_time 精确记录任务开始时间
   • try/finally 确保异常情况下仍能记录指标
   • 标签系统区分不同任务类型的指标

1.4 可视化方案

配置 Grafana 仪表板可以直观展示监控数据：

graph LR A[FastAPI应用] -->|暴露/metrics| B(Prometheus) B --> C[存储时间序列数据] C --> D{Grafana} D --> E[任务延迟仪表盘] D --> F[错误率仪表盘] D --> G[资源利用率仪表盘]

典型仪表盘应包含：

1. 任务延迟的 95 百分位线
2. 每分钟任务吞吐量
3. 错误率的趋势变化
4. 资源使用热力图

1.5 应用场景

电商订单处理系统案例：

ORDER_PROCESS_TIME = Summary('order_processing_seconds', 'Order processing time')

def process_order(order: OrderSchema):
    with ORDER_PROCESS_TIME.time():
        validate_order(order)          # 验证订单
        process_payment(order)         # 处理支付
        update_inventory(order)        # 更新库存
        send_confirmation(order)       # 发送确认

通过监控可以：

1. 识别支付处理的性能瓶颈
2. 发现库存更新时的异常延迟
3. 预警邮件服务失败率的升高
4. 优化整个订单处理流水线

---

课后 Quiz

1. 当任务执行时间监控显示 P99 延迟显著增加时，首先应该检查什么？

   • A) 增加服务器数量
   • B) 检查下游依赖服务
   • C) 降低日志级别
   • D) 忽略短期波动

2. 如何实现对特定类型任务（如"email_send"）的错误率监控？

   • A) 增加全局计数器
   • B) 使用带标签的指标
   • C) 修改日志格式
   • D) 单独部署监控服务

3. 为什么在 finally 块中记录任务持续时间？

   • A) 确保异常情况下也能记录
   • B) 提高代码可读性
   • C) 减少指标采集开销
   • D) 避免竞争条件

4. Prometheus 的 Summary 类型指标最适合监控什么？

   • A) 简单计数
   • B) 固定阈值告警
   • C) 时间分布统计
   • D) 资源消耗总量

答案解析

1. 正确答案：B

   P99 延迟增长通常是下游服务性能下降导致的，应优先检查数据库、第三方API等依赖服务。

2. 正确答案：B

   使用带标签的计数器：Counter('tasks_failed', 'Failed tasks', ['task_type'])

   然后通过 labels(task_type="email_send") 进行标记。

3. 正确答案：A

   finally 块保证无论任务是否成功完成，都能准确记录任务持续时间。

4. 正确答案：C

   Summary 类型会自动计算分位数（quantiles），非常适合监控响应时间的分布情况。

---

常见报错解决方案

报错：[500] PrometheusRegistryError: Duplicate metrics collector registration

原因分析：

• 应用重启时尝试重复注册同名的指标收集器
• 在开发模式下热重载导致多次初始化

解决方案：

1. 单次初始化保证：

if not hasattr(app.state, 'metrics_registered'):
    setup_metrics()
    app.state.metrics_registered = True

2. 使用显式重置（测试环境）：

from prometheus_client import REGISTRY
REGISTRY.unregister(REGISTRY._names_to_collectors['your_metric'])

3. 指标命名空间隔离：

from prometheus_client import CollectorRegistry
custom_registry = CollectorRegistry()

预防建议：

• 应用启动时单次初始化监控组件
• 使用单独的注册表管理自定义指标
• 避免在路由处理函数内部创建指标实例

报错：[422] ValidationError: Invalid label value

原因分析：

• 指标标签包含 Prometheus 不允许的字符（如-、空格等）
• 标签值类型不符合要求（必须为字符串）

解决方案：

1. 清理标签值：

safe_label = original_label.replace(' ', '_').replace('-', '')

2. 使用固定标签集合：

allowed_labels = ['success', 'fail', 'timeout']
if status not in allowed_labels:
    status = 'unknown'

3. 添加类型转换：

TASK_COUNT.labels(status=str(task_status)).inc()

最佳实践：

1. 提前定义所有可能的标签值
2. 对用户输入进行严格校验
3. 日志记录无效标签案例
4. 使用 enum 管理状态标签