kgateway项目中的访问日志功能迁移与设计思考

背景与需求

在kgateway项目中，团队正在考虑将Gloo网关的访问日志功能迁移到新的架构中。访问日志是网关系统的重要功能，它记录了所有经过网关的请求和响应信息，对于系统监控、故障排查和安全审计都至关重要。

现有实现分析

Gloo网关当前的访问日志实现是通过ListenerOption层级的配置完成的。当在监听器层级配置访问日志时，该配置会自动应用于下游监听器、HTTP连接管理器(HCM)和TCP代理等多个上下文环境。这种设计虽然方便，但也带来了一些问题：

1. 相同的日志格式会被强制应用于不同上下文
2. 不适用于当前上下文的命令指令会被忽略并记录警告
3. 可能导致同一请求产生多条日志记录

技术挑战与设计考量

在迁移过程中，开发团队面临几个关键设计决策：

配置继承问题

当前Gloo的实现中，监听器层级的访问日志配置会自动"继承"到更细粒度的配置中。这种隐式的继承机制虽然减少了配置工作量，但带来了以下问题：

• 行为不够透明，用户可能不清楚配置的实际应用范围
• 与kgateway现有的策略附件机制不一致
• 难以实现全局默认配置（如为整个GatewayClass启用访问日志）

上下文差异

Envoy提供的访问日志数据在不同上下文中有所差异：

1. 通用数据（TCP和HTTP共用）：

   • 下游（客户端）地址、连接信息、TLS配置和时间信息
   • 上游（服务）地址、连接信息、TLS配置、时间和Envoy路由信息
   • Envoy相关配置如采样率
   • 过滤器链中发布的动态元数据

2. HTTP特有数据：

   • 请求方法、路径、协议、端口、用户代理、头信息等
   • 响应码、头信息、正文等
   • 协议版本

设计方案演进

经过深入讨论，团队确定了以下设计方向：

1. 初始阶段：仅支持HTTP连接管理器(HCM)的访问日志功能，不处理TCP代理等其他上下文的日志。

2. 策略分离：引入新的HTTPListenerPolicy专门处理HTTP相关的配置，而不是使用通用的ListenerOption。这种设计更符合单一职责原则，也使得配置更加明确。

3. 默认配置：全局默认配置的支持将作为后续功能开发，当前阶段不处理。

实现意义

这种设计选择带来了几个优势：

1. 明确性：HTTP特定的配置与通用监听器配置分离，使系统行为更加可预测。

2. 可扩展性：为未来可能的TCP访问日志支持保留了设计空间。

3. 一致性：与kgateway现有的策略模型保持一致，降低了用户的学习成本。

4. 灵活性：为将来支持更细粒度的日志配置（如基于路由的日志设置）奠定了基础。

总结

kgateway对访问日志功能的重新设计体现了从简单到复杂的渐进式开发理念。通过先支持核心的HTTP访问日志功能，并采用更清晰的策略分离设计，为系统未来的扩展打下了良好基础。这种设计既考虑了现有功能的平滑迁移，又为更丰富的日志功能预留了演进空间。