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

问题背景

Apache APISIX 作为一款高性能的云原生API网关，其指标监控功能对于系统运维至关重要。在3.9.0版本中，引入了一个基于Nginx Lua Prometheus库的指标过期特性，该特性旨在自动清理长时间未被更新的指标数据。然而，这一特性在实际使用中被发现存在缺陷，会导致部分已过期并重新添加的指标在输出时丢失。

问题现象

当用户配置了指标过期时间后，会出现以下异常现象：

1. 首次访问API接口时，相关指标正常记录
2. 等待指标过期后（如设置的10秒过期时间）
3. 再次访问相同API接口时，指标数据无法在/metrics端点中显示
4. 但实际业务请求仍在正常处理

技术原理分析

问题的根源在于指标处理库中的缓存机制与过期机制的交互存在缺陷。具体表现为：

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

2. 过期机制：首次添加指标时，系统会：

   • 设置映射缓存
   • 执行self._key_index:add()保存key索引关系
   • 设置过期时间，导致一段时间后self._key_index.keys[i]变为null

3. 问题触发点：当指标再次添加时：

   • 由于缓存中存在映射，直接返回完整名称
   • 不再执行self._key_index:add()
   • 此时self._key_index.keys已丢失数据
   • 最终导致指标输出时无法获取完整列表

影响范围

该缺陷影响所有使用以下配置的用户：

• 启用了prometheus插件
• 设置了指标过期时间(exptime)
• 使用Apache APISIX 3.9.0版本

解决方案

修复方案主要围绕缓存与过期机制的协调工作，核心思路包括：

1. 缓存一致性保障：确保在指标重新添加时，无论缓存是否存在，都维护正确的索引关系。

2. 过期处理优化：改进过期指标的重新注册流程，避免因缓存命中导致的索引丢失。

3. 状态同步机制：建立缓存与索引之间的同步机制，确保两者状态一致。

最佳实践建议

对于使用指标过期功能的用户，建议：

1. 监控策略：在关键业务指标上设置告警，及时发现指标丢失情况。

2. 过期时间设置：根据业务实际需求合理设置过期时间，避免过短导致频繁重建。

3. 版本升级：及时关注官方修复版本，升级到包含该问题修复的版本。

总结

指标监控是API网关可观测性的重要组成部分。Apache APISIX社区对此问题的快速响应和修复，体现了对产品质量的严格要求和持续改进的承诺。通过深入分析此类问题，开发者可以更好地理解系统内部机制，构建更健壮的监控体系。