feat: querier add ooo metric

[xiaochaoren1]

This PR is for:

[xiaochaoren1]

@claude 审核代码，中文回答

[claude[bot]]

Claude finished @xiaochaoren1's task —— View job

---

代码审查完成

任务清单

• [x] 检查仓库配置文件
• [x] 审查核心代码变更
• [x] 审查数据库描述文件的一致性
• [x] 审查查询引擎集成
• [x] 提供审查反馈

---

审查总结

本 PR 主要添加了 TCP 乱序（Out-of-Order, OOO）相关的指标支持，同时改进了 ch_vtap_port.go 的更新逻辑，并修复了 ClickHouse 客户端的资源泄漏问题。整体代码质量良好，改动合理，但有一些建议供参考。

主要变更

1. 新增 OOO 指标 ✅

在多个数据库描述文件中新增了 TCP 乱序包计数指标：

• ooo - TCP 乱序总数
• ooo_tx - TCP 客户端乱序数
• ooo_rx - TCP 服务端乱序数
• fin_count - TCP FIN 包数

涉及文件：

• server/querier/db_descriptions/clickhouse/metrics/flow_log/l4_flow_log*
• server/querier/db_descriptions/clickhouse/metrics/flow_metrics/network*
• server/querier/db_descriptions/clickhouse/metrics/flow_metrics/network_map*

评价： 指标命名规范，中英文描述文件保持一致，分类合理（归类为 L3 Throughput）。

2. 新增 init_ipid 标签 ✅

在 L4 流日志的标签描述中新增了 init_ipid（首包 IPID）字段。

涉及文件：

• server/querier/db_descriptions/clickhouse/tag/flow_log/l4_flow_log*

评价： 字段添加位置合理，中英文描述完整。

3. 优化 ch_vtap_port.go 更新逻辑 ⭐

将 generateUpdateInfo 方法从使用 JSON 序列化/反序列化的方式改为显式字段比较。

变更前（第 458-493 行）：

func (v *ChVTapPort) generateUpdateInfo(oldItem, newItem metadbmodel.ChVTapPort) (map[string]interface{}, bool) {
    updateInfo := make(map[string]interface{})
    oldItemMap := make(map[string]interface{})
    newItemMap := make(map[string]interface{})
    oldItemStr, err := json.Marshal(oldItem)
    // ... 使用 JSON 序列化/反序列化进行比较
}

变更后：

func (v *ChVTapPort) generateUpdateInfo(oldItem, newItem metadbmodel.ChVTapPort) (map[string]interface{}, bool) {
    updateInfo := make(map[string]interface{})
    if oldItem.Name != newItem.Name {
        updateInfo["name"] = newItem.Name
    }
    // ... 逐字段显式比较
}

评价： ⭐ 重大改进！

• 性能提升： 避免了 JSON 序列化/反序列化的开销，性能显著提升
• 可读性提升： 代码意图更加清晰，易于维护
• 类型安全： 编译时类型检查，减少运行时错误
• 删除未使用的导入： 移除了 encoding/json 导入

潜在问题： 目前只检查了 11 个字段（Name, HostID, HostName, CHostID, CHostName, PodNodeID, PodNodeName, DeviceID, DeviceType, DeviceName, IconID），但可能遗漏了 ChVTapPort 结构体的其他字段（如 VTapID, TapPort, MacType, TeamID 等）。建议确认是否这些字段确实不需要更新检测，或者在注释中说明原因。

4. 修复资源泄漏问题 ✅

在 client.go 的错误处理中添加了 rows.Close() 调用。

涉及文件： server/querier/engine/clickhouse/client/client.go

变更位置：

• 第 159-164 行：DoQuery 方法
• 第 241-246 行：GetVersion 方法

评价： ⭐ 重要的 Bug 修复！

• 防止数据库连接泄漏
• 遵循 Go 资源管理最佳实践
• 但需要注意 rows 可能为 nil 的情况已经正确处理

5. 查询引擎集成 ✅

在查询引擎的指标计算中添加了 OOO 指标支持。

涉及文件：

• server/querier/engine/clickhouse/metrics/l4_flow_log.go (第 87 行)
• server/querier/engine/clickhouse/metrics/vtap_flow_port.go (第 24 行)
• server/querier/engine/clickhouse/metrics/vtap_flow_edge_port.go (第 24 行)

实现：

"ooo": NewReplaceMetrics("ooo_tx+ooo_rx", ""),

评价： 实现一致，正确地将 ooo_tx 和 ooo_rx 合并为 ooo 指标。

建议与问题

🔴 必要改进

1. 字段遗漏检查（ch_vtap_port.go）
   • 建议：确认 generateUpdateInfo 是否需要检查所有 ChVTapPort 结构体字段
   • 位置：server/controller/tagrecorder/ch_vtap_port.go:458
   • 当前只检查了 11 个字段，可能遗漏了 VTapID、TapPort、MacType、TeamID 等字段

🟡 建议改进

1. 添加单元测试

   • 建议为新的 OOO 指标添加单元测试
   • 特别是 generateUpdateInfo 重构后应该有测试覆盖

2. 文档完善

   • 建议在 PR 描述中说明 OOO 指标的业务含义和使用场景
   • init_ipid 字段的用途说明

3. ClickHouse 版本兼容性

   • client.go 中的版本判断逻辑（第 122、141 行）值得关注
   • 确保新指标在不同 ClickHouse 版本中都能正常工作

✅ 优点

1. 代码重构合理，性能优化明显
2. 资源管理问题修复及时
3. 多语言文档保持同步
4. 指标定义一致性好

代码风格

代码整体符合 Go 语言规范，格式良好，命名清晰。

结论

本 PR 质量良好，主要改进包括：

• ✅ 新增有价值的 TCP 乱序监控指标
• ✅ 重要的性能优化和代码质量提升
• ✅ 关键的资源泄漏问题修复

建议在合并前确认 generateUpdateInfo 方法是否需要检查所有字段，其他问题可以在后续 PR 中优化。

---