Kiali项目中Tempo查询范围(query_scope)配置失效问题分析

在Kiali项目与Tempo分布式追踪系统集成时，发现了一个关于查询范围(query_scope)配置项的重要问题。当用户在使用HTTP协议连接单集群环境的Tempo时，配置的query_scope参数会被完全忽略，导致预期的追踪查询过滤条件无法生效。

问题背景

Kiali作为Istio服务网格的可视化工具，提供了与多种追踪后端的集成能力，其中包括Tempo。为了增强查询的精确性，Kiali允许用户通过query_scope配置项为追踪查询添加额外的过滤条件。这些条件会以标签(tag)的形式附加到TraceQL查询语句中。

问题现象

在单集群环境下，当用户配置了类似以下的追踪设置时：

tracing:
  enabled: true
  provider: "tempo"
  query_scope:
    custom_tag: "specific_value"
  use_grpc: false

预期生成的TraceQL查询应该包含custom_tag="specific_value"这样的条件。然而实际观察发现，这些自定义的查询范围条件被完全忽略了，除非Tempo运行在多租户模式下(即追踪数据包含cluster标签)。

技术分析

通过查看Kiali源码中的Tempo HTTP客户端实现，发现问题出在查询条件构建的逻辑上。在tracing/tempo/http_client.go文件中，prepareTraceQL方法负责构建最终的TraceQL查询语句。当前实现中有一个条件判断：

if k != models.IstioClusterTag && oc.ClusterTag {

这个条件导致只有当标签不是IstioClusterTag且ClusterTag为true时，才会将查询范围中的标签添加到查询条件中。这种实现方式在多集群环境下工作正常，但在单集群环境下会导致所有自定义查询范围条件被过滤掉。

解决方案

修复方案相对简单，只需移除不必要的条件判断。修改后的代码应该如下：

if k != models.IstioClusterTag {

这样修改后，无论是否在多集群环境下，所有非IstioClusterTag的查询范围条件都会被正确添加到TraceQL查询中。

影响范围

该问题影响所有使用以下配置组合的用户：

1. 使用Tempo作为追踪后端
2. 通过HTTP协议连接(非gRPC)
3. 运行在单集群环境
4. 配置了query_scope参数

修复状态

该问题已在Kiali的主干分支中修复，并已向后移植到1.89版本。用户升级到包含修复的版本后即可解决此问题。

最佳实践建议

对于需要使用查询范围功能的用户，建议：

1. 确保使用包含此修复的Kiali版本
2. 在配置query_scope时，避免使用Istio保留的系统标签(如cluster)
3. 对于重要的业务追踪，建议添加具有业务意义的自定义标签进行过滤
4. 在生产环境部署前，先在测试环境验证查询范围条件是否按预期工作

这个问题虽然修复简单，但它提醒我们在实现跨环境兼容的功能时需要更加谨慎，特别是在处理不同部署模式(单集群/多集群)时，应该确保核心功能在所有模式下都能一致工作。