如何正确配置Grafana以展示Prometheus直方图延迟热力图？

一、先确保PromQL查询正确 #

Prometheus Histogram的核心数据存储在带_bucket后缀的指标中，每个序列通过le标签标记延迟上限。要生成热力图，需先计算每个时间窗口内各延迟区间的请求速率，推荐使用以下格式的查询：

sum by (le, grpc_service, grpc_method) (rate(grpc_server_handling_seconds_bucket{<你的标签过滤条件>}[1m]))

• 替换<你的标签过滤条件>：比如指定grpc_service="xxx"、grpc_method="yyy"缩小数据范围，避免全量数据导致渲染异常
• sum by用于聚合不需要的标签（如account、client），只保留le和你关心的维度（如服务、方法）
• rate([1m])：根据请求量调整时间窗口，请求量低的场景可改为[5m]，确保每个窗口有有效数据

二、Grafana热力图面板配置步骤 #

1. 选择面板类型：新建面板后，选择Heatmap类型
2. Query标签页配置：
   • 数据源选择你的Prometheus实例
   • 粘贴上述PromQL语句，验证能返回带le标签的时间序列
3. Visualization标签页关键配置：
   • Data format：必须选择Time series buckets，Grafana会自动识别le标签作为热力图的Y轴延迟区间
   • Y轴设置：
     • 单位选择Seconds，匹配你的延迟指标单位
     • 调整Y轴范围为0到60（覆盖你定义的所有bucket区间：0.005~60秒）
     • 若延迟跨度极大，可开启Log scale优化展示，但你的数据集中在5-30秒，优先用线性刻度
   • Color配置：调整颜色梯度（比如从蓝色到红色），让高请求量的区间更醒目
   • Tooltip：开启显示具体请求数和延迟区间，方便排查细节

三、常见问题排查 #

• 检查标签过滤是否准确：比如要查看成功请求的延迟，需添加grpc_status_code="0"（根据你的grpc状态码定义调整），避免错误请求的延迟干扰结果
• 验证PromQL在Prometheus UI中是否有效：执行查询后，确认le为5、10、30的序列有非零数值，说明数据已正确采集
• 调整Grafana时间范围：确保面板时间范围覆盖你观察到数据集中的时间段

内容的提问来源于stack exchange，提问作者sashas