Grafana 仪表板使用指南¶

文档版本: 1.0.0
最后更新: 2025-08-19
Git 提交: c1aa5b0f
作者: Lincoln

本指南详细介绍如何使用 JAiRouter 的 Grafana 仪表板进行系统监控、性能分析和故障诊断。

快速开始¶

访问 Grafana¶

1. 启动监控栈

   # Windows
   .\scripts\setup-monitoring.ps1
   
   # Linux/macOS
   ./scripts/setup-monitoring.sh
   

2. 访问界面

3. URL: http://localhost:3000
4. 用户名: admin

5. 密码: jairouter2024

6. 验证数据源

7. 导航到 Configuration → Data Sources
8. 确认 Prometheus 数据源状态为绿色

仪表板概览¶

JAiRouter 提供以下预配置仪表板：

系统概览仪表板¶

主要面板¶

1. 系统状态概览¶

• 服务状态: 显示 JAiRouter 服务的运行状态
• JVM 内存使用: 堆内存、非堆内存使用情况
• CPU 使用率: 系统和进程 CPU 使用率
• 活跃连接数: 当前活跃的 HTTP 连接数

2. 请求统计¶

• 总请求率: 每秒处理的请求数 (RPS)
• 响应时间分布: P50、P95、P99 响应时间
• 状态码分布: 2xx、4xx、5xx 状态码统计
• 错误率: 错误请求占总请求的百分比

3. JVM 监控¶

• 垃圾回收: GC 频率和耗时统计
• 线程状态: 活跃线程、阻塞线程数量
• 类加载: 已加载类的数量和趋势

使用技巧¶

时间范围选择¶

常用时间范围：
- Last 5 minutes: 实时监控
- Last 1 hour: 短期趋势分析
- Last 24 hours: 日常运营分析
- Last 7 days: 周期性分析

数据刷新设置¶

• 自动刷新: 选择 5s、10s、30s 等间隔
• 手动刷新: 点击刷新按钮
• 暂停刷新: 点击暂停按钮冻结当前数据

面板交互¶

• 缩放: 在图表上拖拽选择时间范围
• 图例: 点击图例项隐藏/显示对应数据系列
• 详细信息: 悬停在数据点上查看具体数值

业务指标仪表板¶

核心业务指标¶

1. 服务类型分布¶

查询: sum by (service) (rate(jairouter_requests_total[5m]))

显示各种 AI 服务的使用情况： - Chat 服务: 聊天对话请求统计 - Embedding 服务: 向量化请求统计 - Rerank 服务: 重排序请求统计 - 其他服务: TTS、STT、图像生成等

2. 模型调用成功率¶

查询: sum(rate(jairouter_model_calls_total{status="success"}[5m])) / sum(rate(jairouter_model_calls_total[5m])) * 100

• 显示各个后端适配器的成功率
• 按时间趋势显示成功率变化
• 设置告警阈值（通常 < 95% 需要关注）

3. 请求大小分布¶

查询: histogram_quantile(0.95, rate(jairouter_request_size_bytes_bucket[5m]))

• P50、P95、P99 请求大小
• 按服务类型分组显示
• 识别异常大小的请求

4. 响应时间分析¶

查询: histogram_quantile(0.95, rate(jairouter_request_duration_seconds_bucket[5m]))

• 各服务类型的响应时间分布
• 识别性能瓶颈
• 对比不同时间段的性能表现

业务洞察面板¶

使用模式分析¶

• 峰值时间: 识别业务高峰期
• 服务偏好: 分析用户最常使用的服务类型
• 地域分布: 基于客户端 IP 的地域统计

容量规划¶

• 增长趋势: 请求量的长期增长趋势
• 资源需求: 基于使用模式预测资源需求
• 扩容建议: 根据历史数据提供扩容建议

基础设施监控仪表板¶

负载均衡监控¶

1. 负载均衡策略分布¶

查询: sum by (strategy) (jairouter_loadbalancer_selections_total)

显示不同策略的使用情况： - Random: 随机策略使用次数 - Round Robin: 轮询策略使用次数 - Least Connections: 最少连接策略使用次数 - IP Hash: IP 哈希策略使用次数

2. 后端实例健康状态¶

查询: jairouter_backend_health

• 实时显示各后端实例的健康状态
• 健康实例数量统计
• 故障实例告警

3. 请求分发均匀度¶

查询: sum by (instance) (rate(jairouter_backend_calls_total[5m]))

• 各实例接收请求的分布
• 识别负载不均衡问题
• 评估负载均衡策略效果

限流器监控¶

1. 限流器状态¶

查询: jairouter_rate_limit_tokens

• 各服务的可用令牌数
• 令牌消耗速率
• 限流触发频率

2. 限流事件统计¶

查询: sum by (result) (rate(jairouter_rate_limit_events_total[5m]))

• 通过的请求数
• 被限流的请求数
• 限流通过率

熔断器监控¶

1. 熔断器状态¶

查询: jairouter_circuit_breaker_state

状态说明： - CLOSED (0): 正常状态 - OPEN (1): 熔断开启状态 - HALF_OPEN (2): 半开状态

2. 熔断事件¶

查询: sum by (event) (rate(jairouter_circuit_breaker_events_total[5m]))

• 成功调用
• 失败调用
• 熔断触发
• 熔断恢复

性能分析仪表板¶

响应时间分析¶

1. 响应时间热力图¶

• 显示响应时间的分布密度
• 识别性能异常时间段
• 对比不同服务的性能表现

2. 响应时间趋势¶

• 长期响应时间趋势分析
• 性能退化检测
• 优化效果验证

吞吐量分析¶

1. 请求吞吐量¶

查询: sum(rate(jairouter_requests_total[1m]))

• 每分钟处理的请求数
• 峰值吞吐量记录
• 容量利用率分析

2. 后端调用吞吐量¶

查询: sum by (adapter) (rate(jairouter_backend_calls_total[1m]))

• 各适配器的调用频率
• 后端服务负载分析
• 瓶颈识别

资源使用分析¶

1. 内存使用趋势¶

• JVM 堆内存使用情况
• 内存泄漏检测
• GC 影响分析

2. 连接池监控¶

• 活跃连接数
• 连接池使用率
• 连接超时统计

告警概览仪表板¶

当前告警状态¶

1. 告警汇总¶

• 严重告警数量
• 警告告警数量
• 告警趋势图

2. 告警详情表格¶

显示信息： - 告警名称 - 触发时间 - 严重程度 - 影响范围 - 处理状态

告警历史分析¶

1. 告警频率统计¶

• 各类告警的触发频率
• 告警模式识别
• 系统稳定性评估

2. 平均恢复时间 (MTTR)¶

• 各类告警的平均恢复时间
• 故障处理效率分析
• 运维团队绩效评估

自定义仪表板¶

创建自定义面板¶

1. 添加新面板¶

1. 点击仪表板右上角的 "Add panel"
2. 选择面板类型（Graph、Stat、Table 等）
3. 配置查询和显示选项
4. 保存面板

2. 常用查询示例¶

自定义业务指标:

# 特定用户的请求统计
sum by (user_id) (rate(jairouter_requests_total{user_id!=""}[5m]))

# 特定时间段的错误率
sum(rate(jairouter_requests_total{status=~"4..|5.."}[1h])) / sum(rate(jairouter_requests_total[1h])) * 100

# 后端服务响应时间对比
histogram_quantile(0.95, sum by (adapter, le) (rate(jairouter_backend_call_duration_seconds_bucket[5m])))

仪表板模板变量¶

1. 环境变量¶

名称: environment
类型: Query
查询: label_values(jairouter_requests_total, environment)

2. 服务类型变量¶

名称: service
类型: Query
查询: label_values(jairouter_requests_total, service)

3. 时间范围变量¶

名称: time_range
类型: Interval
选项: 1m,5m,15m,1h,6h,24h

面板配置最佳实践¶

1. 颜色配置¶

• 使用一致的颜色方案
• 绿色表示正常状态
• 红色表示错误或告警
• 黄色表示警告状态

2. 阈值设置¶

• 设置合理的告警阈值
• 使用渐变色显示不同严重程度
• 配置阈值线便于快速识别

3. 单位和格式¶

• 时间使用 seconds、milliseconds
• 大小使用 bytes、KB、MB
• 百分比使用 percent (0-100)
• 速率使用 ops/sec、req/sec

仪表板管理¶

导入和导出¶

导出仪表板¶

1. 打开要导出的仪表板
2. 点击设置图标 → Export
3. 选择导出格式（JSON）
4. 保存文件

导入仪表板¶

1. 点击 "+" → Import
2. 上传 JSON 文件或输入仪表板 ID
3. 选择数据源
4. 点击 Import

权限管理¶

设置仪表板权限¶

1. 打开仪表板设置
2. 选择 Permissions 标签
3. 添加用户或团队权限
4. 设置权限级别（View、Edit、Admin）

版本控制¶

仪表板版本管理¶

• Grafana 自动保存仪表板版本
• 可以查看历史版本和变更
• 支持版本回滚功能

故障排查¶

常见问题¶

1. 仪表板显示 "No data"¶

解决方案: 1. 检查 Prometheus 数据源连接 2. 验证查询语法 3. 确认时间范围设置 4. 检查 JAiRouter 指标收集是否正常

2. 图表加载缓慢¶

解决方案: 1. 减少查询时间范围 2. 简化查询表达式 3. 增加刷新间隔 4. 使用 recording rules

3. 告警不触发¶

解决方案: 1. 检查告警规则配置 2. 验证阈值设置 3. 确认 Alertmanager 配置 4. 检查通知渠道设置

性能优化¶

1. 查询优化¶

• 使用适当的时间范围
• 避免过于复杂的查询
• 使用 recording rules 预计算常用指标

2. 仪表板优化¶

• 限制面板数量（建议 < 20 个）
• 使用合理的刷新间隔
• 避免高基数标签

最佳实践¶

监控策略¶

1. 分层监控¶

• L1: 系统级监控（可用性、性能）
• L2: 业务级监控（功能、用户体验）
• L3: 基础设施监控（资源、组件状态）

2. 仪表板组织¶

• 使用文件夹组织仪表板
• 按角色和用途分类
• 定期清理无用仪表板

团队协作¶

1. 知识共享¶

• 为仪表板添加描述和文档
• 创建操作手册和故障处理流程
• 定期进行监控培训

2. 标准化¶

• 使用统一的命名规范
• 保持一致的颜色和样式
• 建立仪表板模板

下一步¶

掌握仪表板使用后，您可以：

1. 配置告警规则
2. 了解详细指标
3. 进行故障排查
4. 优化监控性能

提示: 建议定期备份重要的仪表板配置，并建立仪表板变更的审核流程。