Apache APISIX 指标过期特性缺陷分析与修复方案

背景介绍

Apache APISIX 作为一款高性能的云原生API网关，其监控指标收集功能对于系统运维至关重要。在3.9.0版本中，APISIX引入了基于nginx-lua-prometheus库的指标过期特性，旨在优化内存使用。然而，该特性在实际运行中存在一个关键缺陷，可能导致部分指标数据丢失。

问题现象

当使用APISIX的Prometheus插件并开启指标过期功能后，会出现以下现象：

1. 首次访问API时，相关路由指标能正常收集和展示
2. 等待指标过期时间(如10秒)后再次访问相同API
3. 此时通过/metrics端点查询指标时，发现部分已重新生成的指标数据丢失

技术原理分析

问题的根源在于nginx-lua-prometheus库的指标缓存管理机制：

1. 指标缓存机制：库内部使用self.lookup缓存指标的完整名称映射，当缓存大小达到上限(self.lookup_size >= self.lookup_max_size)时会进行重置。

2. 首次添加流程：

   • 指标首次添加时，由于缓存中不存在，会执行以下操作：
     1. 设置映射缓存
     2. 调用self._key_index:add()保存键索引关系
     3. 设置过期时间(self.exptime)

3. 过期后问题：

   • 过期时间到达后，self._key_index.keys[i]的值变为null
   • 当相同指标再次被添加时：
     1. 由于缓存(self.lookup)中仍存在映射，直接返回完整名称
     2. 不再执行self._key_index:add()
     3. 导致self._key_index.keys列表数据缺失

4. 指标输出问题：

   • 指标输出时使用的self._key_index:list()方法会遍历self._key_index.keys列表
   • 由于该列表已缺失数据，导致指标无法正常输出

解决方案

修复方案主要围绕缓存一致性进行优化：

1. 缓存同步机制：确保self.lookup缓存与self._key_index.keys的数据一致性
2. 过期处理优化：在指标过期时，同时清理相关缓存
3. 重新添加逻辑：当过期指标重新添加时，强制更新索引关系

核心修复点包括：

• 在指标过期时同步清理lookup缓存
• 在指标重新添加时检查并重建索引
• 优化缓存失效策略

验证方法

可以通过以下步骤验证修复效果：

1. 配置APISIX路由和全局规则，启用Prometheus插件并设置较短过期时间(如10秒)
2. 首次访问API并确认指标收集正常
3. 等待过期时间后再次访问相同API
4. 检查指标端点确认所有指标正常显示

示例测试命令：

# 首次访问
curl "127.0.0.1:9080/hello" && sleep 12 && curl "127.0.0.1:9091/apisix/prometheus/metrics" | grep 'route'

# 再次访问
curl "127.0.0.1:9080/hello" && sleep 2 && curl "127.0.0.1:9091/apisix/prometheus/metrics" | grep 'route'

总结

指标监控是API网关的重要功能，确保指标数据的完整性和准确性对系统运维至关重要。本次修复解决了APISIX在特定场景下的指标丢失问题，提升了监控系统的可靠性。建议使用APISIX 3.9.0及以上版本并启用指标过期功能的用户及时应用此修复。