Kratos接入Grafana监控的核心是先暴露Prometheus兼容的/metrics端点,需手动注册handler(如srv.Handle("/metrics", promhttp.Handler())),并验证返回200及指标文本;Grafana数据源选Server模式,查询用kratos_前缀指标并加rate()计算,告警禁用raw counter。

Kratos 微服务接入 Grafana 监控,核心不是“配面板”,而是先让 Kratos 暴露 Prometheus 兼容的指标端点——没这一步,Grafana 连数据都拉不到。
Prometheus 指标端点必须显式启用
Kratos 默认不开启 metrics 暴露,即使你引入了 kratos/pkg/metrics,也得手动注册 HTTP handler。常见错误是只初始化了指标收集器,却忘了绑定到路由上,导致访问 /metrics 返回 404 或空响应。
- 确认你的
main.go或 server 初始化代码中调用了srv.Handle("/metrics", promhttp.Handler())(使用promhttp)或等效的 Kratos 内置封装(如metrics.NewHandler()) - 检查启动日志是否输出类似
register metrics handler on /metrics的提示;没有就说明没挂载 - 用
curl -v http://localhost:8000/metrics直接验证:应返回文本格式的指标(含# HELP和# TYPE行),且状态码为 200 - 若用的是 Kratos v2.5+,注意
kratos/pkg/metrics已被重构,旧写法如metrics.NewPrometheus可能已弃用,需改用metrics.NewMeter+prometheus.NewRegistry
Grafana 数据源配置要选对访问模式
在 Grafana 中添加 Prometheus 数据源时,Access 模式选 Server (default) 还是 Browser,直接影响 Kratos 指标能否加载成功。本地开发常用 Browser,但生产环境几乎必须用 Server。
-
Server模式下,Grafana 后端直连 Prometheus(或 Kratos 实例),需确保网络可达、端口开放、无跨域限制 -
Browser模式下,浏览器直接请求 Kratos 的/metrics,会受同源策略限制——如果你的 Grafana 域名和 Kratos 服务域名不同(如grafana.example.comvsapi.example.com),必须在 Kratos 服务侧显式设置 CORS 头,否则控制台报CORS error - 如果 Kratos 部署在 Kubernetes 中,且通过 Ingress 暴露,注意 Ingress 是否转发了
/metrics路径;默认可能只放行/下的 API 路由
面板查询语句要适配 Kratos 默认指标命名
Kratos 使用的指标前缀是 kratos_(如 kratos_http_server_requests_total),不是 http_requests_total。直接套用 Prometheus 官方示例或其它框架的查询会查不到数据。
- 常用指标包括:
kratos_http_server_requests_total{code=~"2..|3..",method="GET"}(成功请求数)、kratos_http_server_request_duration_seconds_bucket(延迟分布) - 计算成功率:用
sum(rate(kratos_http_server_requests_total{code=~"2..|3.."}[5m])) by (job) / sum(rate(kratos_http_server_requests_total[5m])) by (job),注意分母不能漏掉rate(),否则是总量比总量,结果恒为 1 - 延迟 P95:用
histogram_quantile(0.95, rate(kratos_http_server_request_duration_seconds_bucket[5m])),别漏掉rate()——直方图桶必须先做速率计算再分位数,否则结果严重失真 - 若指标带
service标签(如kratos_http_server_requests_total{service="order"}),可在面板变量中用label_values(kratos_http_server_requests_total, service)动态下拉筛选
告警规则里别直接用 raw counter
监控面板可以看原始计数器(counter),但告警规则必须基于速率(rate/irate)或变化量(delta),否则重启后 counter 归零会导致误告。
- 错误写法:
kratos_http_server_requests_total > 1000—— counter 单调递增,永远满足条件 - 正确写法:
rate(kratos_http_server_requests_total{code="500"}[5m]) > 0.1(每秒 5xx 错误超 0.1 次) - 对延迟类指标,优先用
irate()(最近两个采样点),比rate()更敏感;但注意irate()在陡升/陡降时波动大,生产告警建议仍以rate()为主 - Kratos 的
kratos_http_server_request_duration_seconds_sum和_count可组合算平均延迟:rate(kratos_http_server_request_duration_seconds_sum[5m]) / rate(kratos_http_server_request_duration_seconds_count[5m])
真正卡住人的地方,往往不是 Grafana 界面操作,而是 Kratos 的 metrics handler 没挂上、Prometheus 抓取目标没配对、或者查询语句里把 kratos_ 前缀写成了 go_ 或漏掉了 rate() ——这些细节一错,面板就是空白,且没有任何报错提示。











