Higress 监控面板搭建指南从指标采集到 Grafana 告警的完整路径【免费下载链接】higress AI Gateway | AI Native API Gateway项目地址: https://gitcode.com/GitHub_Trending/hi/higressHigress 是一个 AI 原生的云原生 API 网关而 Higress 监控面板是你在生产环境里确认网关到底健不健康最直接的手段。本文带你从零把网关接入 Prometheus在 Grafana 里看到请求量、延迟与错误率并配上第一条告警规则。全程不需要改网关源码只改 Helm 配置和两条命令。先说结论这套方案能覆盖日常巡检流量与成功率、故障定位延迟分位与 5xx 占比和资源评估CPU/内存水位三类场景且采集开销可控——因为指标端点复用网关自带的 Admin 端口不额外起任何组件。准备工作先确认这 3 项前提动手前把下表过一遍缺任何一项都会让后面的步骤卡住类别内容说明前提条件已部署 Higress 网关Helm release 存在后文默认网关在higress-system命名空间名字为higress-gatewayHelm 默认值前提条件集群里已有 Prometheus 监控栈需要支持 PodMonitor CRD即 kube-prometheus-stack 或 VictoriaMetrics OperatorHelm 配置里的provider字段就是用来二选一的前提条件有 Grafana 可登录用于导入仪表盘和查看告警所需组件本地装有 kubectl 和 Helm一条命令都不用手工敲 YAML所需组件Higress 仓库git clone https://gitcode.com/GitHub_Trending/hi/higress后文引用的配置都在 helm/core/ 目录下预计耗时30~60 分钟取决于是否已有现成的 Grafana 实例一个名词先交代清楚PodMonitor 是告诉 Prometheus 去哪抓指标的声明——它写明选哪些 Pod、抓哪个端口哪条路径、多久抓一次。理解了这一点本文所有配置改动你都能自己推断。准备工作就绪后搭建就按一条因果链推进先让指标能从网关吐出来再接面板看图最后才配告警。顺序反了会白忙——面板没数据时你调再多阈值也没有意义。搭建路径先通指标 → 再连面板 → 后配告警整条链路长这样你做完每步都能用一条命令验证端点可达 → PodMonitor 生效 → Prometheus 出现 target → Grafana 有数据 → 告警规则开始评估第一步确认指标端点可达。网关进程内置了 Prometheus 格式指标端点地址在 15020 端口的/stats/prometheus路径上。进网关 Pod 验证一下kubectl exec -it deploy/higress-gateway -n higress-system -- curl -s localhost:15020/stats/prometheus | head看到requests_total、request_duration_milliseconds这类以# HELP开头的输出就说明源头没问题。如果这一步就没数据问题在网关自身后面所有步骤都不用做。第二步用 Helm 生成 PodMonitor。打开 helm/core/values.yaml在gateway.metrics段打开开关gateway: metrics: enabled: true podMonitorSelector: release: kube-prome # 需要匹配你监控栈的 release 标签默认适配 kube-prometheus-stack改完执行helm upgrade higress ./helm/core -n higress-system。这一步会按 helm/core/templates/podmonitor.yaml 模板生成一个名为higress-gateway-metrics的 PodMonitor选中的正是带app.kubernetes.io/name: higress-gateway标签的 Pod抓istio-prom端口的/stats/prometheus。用kubectl get podmonitor -n higress-system能看到它说明声明已落地。第三步等 Prometheus 侧出现 target。在 Grafana 或 Prometheus UI 的 Targets 页面搜higress看到状态为 UP 的抓取任务数据链路就通了。从helm upgrade到 target UP 通常只需一两个采集周期默认 30 秒PodMonitor 里可配interval缩短。第四步连面板。在 Grafana 里导入 Higress 官方仪表盘模板社区维护的 JSON导入后无需再改数据源。导入完成先别急着看全貌——切到流量页签确认请求量曲线和刚才是否有流量对得上。看到曲线在上涨就说明面板和 Prometheus 之间的查询也通了。第五步配第一条告警。告警规则加在你监控栈的 PrometheusRule 里即可最小可用的一条是groups: - name: higress.rules rules: - alert: HigressHighErrorRate expr: | sum(rate(requests_total{response_code~5..}[5m])) / sum(rate(requests_total[5m])) 0.01 for: 3m labels: severity: critical含义5 分钟窗口内 5xx 占比超过 1%并持续 3 分钟才触发。for: 3m这个缓冲是刻意的——瞬时毛刺不值得半夜叫人。看到这条规则出现在 Prometheus 的 Rules 页面且状态为 OK整条链路就闭环了。面板和告警都就绪后剩下的问题是该看哪几个数。下面按你实际会遇到的场景分组。面板使用指南三类场景对应哪几张图别试图看懂仪表盘上每一张图。日常只需要盯住下面三组出问题时再下钻。日常巡检每天瞟一眼指标含义阈值建议requests_total网关处理的请求总数带response_code、upstream_cluster等标签突降 50% 以上关注业务侧异常response_code聚合的 2xx/5xx 占比成功率巡检时看 5xx 是否恒为 05xx 占比 1% 持续 3 分钟即告警同上一步规则延迟 P99request_duration_milliseconds分位最慢 1% 请求的耗时超过该服务正常基线的 2 倍需下钻故障定位告警响了之后指标含义阈值建议按upstream_cluster拆分的 5xx区分是网关自身问题还是某个上游服务在挂单个 cluster 占全部 5xx 比例 80% 时锅在上游上游连接/超时类计数upstream_rq_*前缀上游连接失败、重置的计数从零开始非零增长即可告警请求速率 × 错误率双图联动判断错误是流量放大导致还是无流量也错无流量仍出 5xx优先查网关配置推送成本与性能容量规划时指标含义阈值建议网关 Pod 的 CPU / 内存用量Kubernetes 侧container_*指标评估要不要扩副本内存持续接近 limit默认 1024Mi的 80% 就该扩容每秒请求数QPS趋势判断容量余量峰值接近当前容量 70% 时规划扩容判断依据都摆在表里了哪条指标、什么阈值照着配即可不需要凭感觉。常见坑指标没出来的 3 个排查点搭建过程中 90% 的卡点集中在下面三种情况按现象→原因→处理对照即可现象原因处理Prometheus 里完全没有higress-gateway-metrics这个 targetPodMonitor 没生成或podMonitorSelector标签与监控栈对不上先kubectl get podmonitor -n higress-system确认资源存在再核对你监控栈的 release 名把 values 里的release: kube-prome改成实际值PodMonitor 存在但 target 仍是 DOWN标签不匹配PodMonitor 选中的是app.kubernetes.io/name: higress-gateway如果你自定义过gateway.name两边就不一致了用kubectl get pod -n higress-system --show-labels核对实际标签保证 selector 与 Pod 标签一一对应指标全都有但 Prometheus 存储量暴涨、查询变慢高基数upstream_cluster、路由类标签取值随服务数量线性增长100 服务的集群尤其明显在 helm/core/values.yaml 把global.liteMetrics设为true收窄指标面或在global.proxy.proxyStatsMatcher.inclusionRegexps里从默认的.*收紧为只保留http、tcp前缀的正则再配合 PodMonitor 的metricRelabelings丢弃用不到的标签还有一个低概率但值得记一笔的坑端点能 curl 到、但 Prometheus 抓不到。此时先检查 Pod 的prometheus.io/scrape注解网关 Pod 默认已带见 values 中podAnnotations如果手动删过注解恢复即可无需动 PodMonitor。排查完这三点绝大多数没数据的问题都能收敛。总结从看面板到自定义指标回到开头的价值主张这套Prometheus PodMonitor Grafana 告警规则的组合让你不新增任何组件就拿到了网关的全链路可观测性——流量、成功率、延迟、资源四类信号各有一张能直接下钻的图。如果内置指标不满足需求延伸方向是两条采集侧通过 PodMonitor 的metricRelabelings和global.proxy.proxyStatsMatcher.inclusionRegexps精细控制暴露哪些 Envoy 原始统计这决定了指标的成本上限定义侧网关侧的代码都在主仓库中指标与状态端点相关的实现集中在 pkg/ 目录如 pkg/cmd/ 下的服务启动逻辑与 pkg/config/ 下的常量定义想扩展自定义指标可以从这里入手。监控不是装完面板就结束的事阈值建议只是起点——跑两周后用你的真实流量基线替换本文给的经验阈值面板才算真正长在你的业务上。【免费下载链接】higress AI Gateway | AI Native API Gateway项目地址: https://gitcode.com/GitHub_Trending/hi/higress创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考