Prometheus + Grafana 监控系统实战教学

这是一个完整的Prometheus和Grafana监控系统教学项目，通过实际的Flask应用演示如何搭建企业级监控平台。您将学习指标收集、可视化面板创建以及完整的可观测性技术栈。

📋 目录

项目概述
系统要求
快速开始
监控特性
系统架构
实战练习
- 练习1：四大黄金信号监控与PromQL查询
- 练习2：Grafana仪表板创建
故障排除
学习目标

🎯 项目概述

本教学项目提供了Prometheus和Grafana监控的实际体验，包含：

Flask应用程序：集成Prometheus指标的Python Web应用
Prometheus：时间序列数据库，用于指标收集
Grafana：可视化和仪表板平台
容器监控：cAdvisor用于Docker容器指标
系统监控：Node exporter用于系统指标
StatsD集成：通过StatsD exporter自定义指标

💻 系统要求

软件需求

Docker 和 Docker Compose
curl（用于流量生成）
bc（基础计算器，用于shell脚本）

硬件需求

最少6GB内存（组件比其他模块多）
15GB可用磁盘空间
可用端口：3000（Grafana）、3001（应用）、8080（cAdvisor）、9090（Prometheus）

🚀 快速开始

启动所有服务：

cd prometheus/
docker-compose up -d
# 所有服务按正确顺序启动，包含健康检查（需要2-3分钟）

生成测试流量：
./generate_traffic.sh quick
访问监控界面：
- Prometheus：http://localhost:9090
- Grafana：http://localhost:3000（用户名：admin，密码：foobar）
- 应用指标：http://localhost:3001/metrics

📊 监控特性

四大黄金信号监控

本Flask应用演示了四大黄金信号的监控：

延迟（Latency）：/delay?seconds=X - 测试响应时间监控
流量（Traffic）：通过prometheus-flask-exporter自动HTTP请求计数
错误（Errors）：/error?rate=X - 生成400/404/500错误用于错误率监控
饱和度（Saturation）：/cpu-intensive和/memory-usage - 测试资源监控

自定义业务指标

应用包含自定义业务指标，演示如何跟踪业务特定事件：

webapp_custom_requests_total：按端点统计请求数
webapp_business_operations_total：按类型统计业务操作（用户登录、支付等）

Python装饰器如何工作

理解自定义指标的工作原理对实现您自己的业务指标至关重要。以下是Python装饰器如何实现自动指标收集：

装饰器基础

当您看到这样的代码：

@app.route("/business-metrics")
@request_counter
@business_operations
def business_metrics():
    request.operation_type = "payment"  # 设置标签值
    return {"status": "success"}

Python从下到上处理装饰器，包装您的函数：

# 等同于：
business_metrics = app.route("/business-metrics")(business_metrics)
business_metrics = request_counter(business_metrics)
business_metrics = business_operations(business_operations)

执行流程

当请求到达时，发生以下过程：

请求到达：GET /business-metrics?operation=payment
Flask路由到函数
装饰器包装器开始执行（以相反顺序）

您的函数运行：

operation = request.args.get("operation", "payment")
request.operation_type = operation  # ← 关键：设置标签值

装饰器包装器完成（prometheus-flask-exporter魔法）：

# business_operations装饰器读取标签：
operation_type = getattr(request, 'operation_type', 'unknown')
# 增加：webapp_business_operations_total{operation_type="payment"}

# request_counter装饰器读取端点：
endpoint = request.endpoint  # "business_metrics"
# 增加：webapp_custom_requests_total{endpoint="business_metrics"}

可用端点

端点	用途	参数	示例
`/`	基础hello world	无	`curl http://localhost:3001/`
`/health`	健康检查	无	`curl http://localhost:3001/health`
`/business-metrics`	自定义指标演示	`operation`	`curl "http://localhost:3001/business-metrics?operation=payment"`
`/delay`	延迟测试	`seconds`	`curl "http://localhost:3001/delay?seconds=2"`
`/error`	错误率测试	`rate`（%）	`curl "http://localhost:3001/error?rate=80"`
`/cpu-intensive`	CPU饱和度测试	`iterations`	`curl "http://localhost:3001/cpu-intensive?iterations=50000"`
`/memory-usage`	内存饱和度测试	`size`（MB）	`curl "http://localhost:3001/memory-usage?size=10"`
`/metrics`	Prometheus指标	无	`curl http://localhost:3001/metrics`

🏗️ 系统架构

本项目采用微服务架构，包含以下组件：

┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│    Grafana      │    │   Prometheus    │    │   Flask App     │
│   :3000         │◄───│     :9090       │◄───│     :3001       │
│  (可视化)        │    │  (指标收集)      │    │   (业务应用)     │
└─────────────────┘    └─────────────────┘    └─────────────────┘
                                ▲                       ▲
                                │                       │
                       ┌─────────────────┐    ┌─────────────────┐
                       │   cAdvisor      │    │ Node Exporter   │
                       │    :8080        │    │     :9100       │
                       │  (容器监控)      │    │   (系统监控)     │
                       └─────────────────┘    └─────────────────┘
                                ▲
                       ┌─────────────────┐
                       │StatsD Exporter  │
                       │:9102/9125       │
                       │  (自定义指标)    │
                       └─────────────────┘

🔬 实战练习

练习1：四大黄金信号监控与PromQL查询

本练习教您如何使用PromQL（Prometheus查询语言）监控四大黄金信号。您将学习编写查询、理解指标和分析应用性能。

准备工作

确保所有服务正在运行：docker-compose up -d
生成一些流量：./generate_traffic.sh quick
打开Prometheus：http://localhost:9090

A部分：流量（请求率）

目标：监控应用每秒处理多少请求。

打开Prometheus控制台 http://localhost:9090
点击页面顶部的"Graph"标签
基础请求计数查询：
flask_http_request_duration_seconds_count
- 点击Execute按钮
- 切换到Table视图查看所有指标
- 看到的内容：自启动以来的总请求数，按端点、方法和状态码分解
请求率查询（每秒请求数）：
rate(flask_http_request_duration_seconds_count[5m])
- 解释：rate()计算5分钟窗口内的每秒速率
- 切换到Graph视图查看随时间变化的速率
总应用请求率：
sum(rate(flask_http_request_duration_seconds_count[5m]))
- 解释：sum()将所有端点相加得到总应用流量

B部分：延迟（响应时间）

目标：监控请求完成需要多长时间（p95、p99百分位数）。

95百分位延迟（95%的请求比这个时间快）：
histogram_quantile(0.95, rate(flask_http_request_duration_seconds_bucket[5m]))
- 解释：计算95百分位数响应时间
- 关键洞察：如果显示2秒，95%的请求在2秒内完成

99百分位延迟（最慢的1%请求）：

histogram_quantile(0.99, rate(flask_http_request_duration_seconds_bucket[5m]))

C部分：错误（错误率）

目标：监控有多少百分比的请求失败。

错误率百分比：

(
  sum(rate(flask_http_request_duration_seconds_count{status=~"4..|5.."}[5m])) 
  / 
  sum(rate(flask_http_request_duration_seconds_count[5m]))
) * 100

解释：错误率除以总请求率的百分比

D部分：饱和度（资源使用）

目标：监控CPU和内存使用情况以检测资源瓶颈。

容器CPU使用率：

rate(container_cpu_usage_seconds_total{id=~"/docker/.*"}[5m]) * 100

容器内存使用量：

container_memory_usage_bytes{id=~"/docker/.*"} / 1024 / 1024

练习2：Grafana仪表板创建

本练习教您为相同的黄金信号创建Grafana仪表板，包含可视化图表和告警。

准备工作

打开Grafana：http://localhost:3000
登录：admin / foobar
生成流量：./generate_traffic.sh demo

A部分：配置Prometheus数据源

重要：创建仪表板前，必须将Grafana连接到Prometheus。

添加数据源：
- 在Grafana中，点击左侧边栏的**“Connections”**
- 点击**“Data sources”**
- 点击**“Add data source”**
- 选择**“Prometheus”**
配置Prometheus连接：
- 名称：Prometheus
- URL：http://prometheus:9090（Docker内部网络）
- 访问：Server（默认）
- 其他设置保持默认
测试连接：
- 滚动到底部点击**“Save & test”**
- 应显示：“Data source is working” ✅

B部分：创建您的第一个仪表板

创建新仪表板：
- 点击左侧边栏的**“+”** → “Dashboard”
- 点击**“+ Create dashboard”**
- 点击**“+ Add visualization”**
流量面板 - 请求率：
- 面板标题：更改为"请求率 (req/s)"
- 查询：
  sum(rate(flask_http_request_duration_seconds_count[5m])) by (path)
- 单位：设置为"requests/sec"
延迟监控面板：
- 面板标题：“响应时间百分位数”
- 查询A：
  histogram_quantile(0.95, rate(flask_http_request_duration_seconds_bucket[5m]))
- 图例A：“p95”

错误率面板：

面板标题：“错误率 %”

查询：

(sum(rate(flask_http_request_duration_seconds_count{status=~"4..|5.."}[5m])) / sum(rate(flask_http_request_duration_seconds_count[5m]))) * 100

可视化：Stat（单一数字）
阈值：黄色：1，红色：5

保存仪表板：
- 点击顶部的**“Save”**（磁盘图标）
- 名称：“四大黄金信号工作坊”
- 点击Save

🔧 故障排除

常见问题

服务无法启动

如果服务启动失败或有依赖错误：

# 检查特定服务的日志
docker-compose logs <service_name>

# 重启所有服务
docker-compose down
docker-compose up -d

# 检查状态（所有应显示"Up"）
docker-compose ps

Prometheus无法抓取目标

# 检查Prometheus目标
curl http://localhost:9090/api/v1/targets

# 检查应用指标端点是否可访问
curl http://localhost:3001/metrics

# 验证网络连接
docker network inspect prometheus_default

应用健康检查

# 检查应用日志
docker-compose logs webapp

# 验证所有服务正在运行
docker-compose ps

# 测试应用端点
curl http://localhost:3001/health
curl http://localhost:3001/metrics

完全重置

完全重置：

docker-compose down -v
# 等待片刻，然后重启：
docker-compose up -d
# 等待2-3分钟让所有服务变健康

🎓 学习目标

完成这些练习后，您将掌握：

✅ PromQL基础：

rate()计算每秒速率
sum()聚合指标
histogram_quantile()计算百分位数
标签过滤{status=~"4..|5.."}
分组by (label)

✅ 四大黄金信号监控：

流量：请求率和流量
延迟：响应时间百分位数（p95、p99）
错误：错误率和错误类型
饱和度：资源使用和容量

✅ Grafana技能：

创建仪表板和面板
使用不同的可视化类型
设置告警和阈值
配置图例和单位

✅ 实用监控：

哪些指标对应用健康重要
如何检测性能问题
设置有意义的告警阈值
解释监控数据

📚 扩展学习

完成本教学后，建议继续学习：

告警规则配置：学习Alertmanager配置
高级PromQL：复杂查询和函数
监控最佳实践：SLI/SLO设计
性能优化：监控系统本身的优化
生产部署：高可用Prometheus集群

项目作者：监控系统教学团队
最后更新：2025年7月27日
版本：v1.0