Kong网关升级至3.7.0后Prometheus监控指标丢失问题分析

问题现象

在使用Kong网关开源版本时，从3.6.1升级到3.7.0版本后，管理员发现Prometheus插件暴露的/metrics端点中缺少了多个关键监控指标。具体表现为：

• 缺失HTTP请求总数指标(kong_http_requests_total)
• 缺失Kong延迟相关指标(kong_kong_latency*)
• 仅能获取到基础系统指标如内存使用情况(kong_memory*)和Nginx相关指标(kong_nginx_*)

配置检查

管理员确认了Prometheus插件的配置完全正确，包含了以下关键参数：

• 带宽指标采集(bandwidth_metrics)启用
• 延迟指标采集(latency_metrics)启用
• 按消费者指标采集(per_consumer)启用
• 状态码指标采集(status_code_metrics)启用
• 上游健康检查指标采集(upstream_health_metrics)启用

问题排查过程

经过深入分析，发现问题根源在于Nginx配置模板的更新。在Kong 3.7.0版本中，核心的nginx_kong.lua模板文件发生了重要变更，而使用自定义Nginx模板(custom_nginx.template)的环境未能及时同步这些变更。

值得注意的是，这种配置不匹配的情况并不会导致Kong服务启动失败，也不会在调试日志中产生明显的错误信息。服务看似正常运行，但实际上影响了Prometheus插件的指标收集功能。

解决方案

要解决此问题，管理员需要：

1. 获取最新版本的nginx_kong.lua模板文件
2. 将变更内容合并到自定义的Nginx模板中
3. 确保所有必要的Lua代码块和配置指令得到保留
4. 重新加载或重启Kong服务使配置生效

经验总结

这个案例揭示了Kong网关升级过程中的一个重要实践：当使用自定义Nginx模板时，必须仔细检查并同步核心模板文件的变更。特别是在以下版本升级场景中需要特别注意：

• 主要版本升级(如3.x到4.x)
• 次要版本升级(如3.6到3.7)
• 涉及监控或日志功能的更新

建议在升级前，先对比新旧版本的模板文件差异，确保所有必要的配置变更都被正确应用到自定义模板中。这样可以避免类似监控指标丢失这种"静默"问题的发生。

对于生产环境，还建议在升级后立即验证所有监控指标是否正常采集，确保系统的可观测性不受影响。