#Alauda Distributed Tracing v2.1.0

Alauda Distributed Tracing v2.1.0 通过 Alauda Build of OpenTelemetry v2 Operator 0.157.0 交付，并集成开源 Jaeger 2.20.0。它提供了一个基于 Jaeger v2 构建、可直接用于生产环境的分布式跟踪解决方案，使团队能够在 Alauda Container Platform 上收集、存储和可视化微服务之间的 traces。

#支持的特性

• Jaeger v2 后端：跟踪后端基于 OpenTelemetry Collector 框架构建，支持按角色部署，包括用于接收和存储 trace 数据的 collector，以及用于提供 Jaeger UI 和 query APIs 的 query。Jaeger ES Rollover 管理 Elasticsearch 索引生命周期操作，例如模板、别名和索引轮转。

• 多协议采集：支持来自多种协议和格式的 trace 数据，包括 OTLP（gRPC 和 HTTP）、Jaeger（gRPC 和 Thrift）、Zipkin（v1 和 v2）以及 Kafka。

• 存储后端：支持的存储后端为 Elasticsearch 8.x 和 OpenSearch 3.x。两者都使用带别名的索引 rollover 进行自动轮转和保留，分别由 Elasticsearch 上的 Index Lifecycle Management (ILM) policy 和 OpenSearch 上的 Index State Management (ISM) policy 驱动。

• 采样策略：支持带集中式远程配置的基于头部采样（静态和自适应两种），以及基于尾部采样，用于在 traces 完成后做出采样决策。

• Service Performance Monitoring (SPM)：通过使用 SpanMetrics Connector 和兼容 PromQL 的指标后端，从 trace 数据计算聚合 RED 指标（Request rate、Error rate、Duration），以监控服务性能趋势。

• 可观测性和指标：Jaeger v2 和 OpenTelemetry Collector 组件默认暴露 Prometheus 指标，并自动创建 ServiceMonitor 和 PodMonitor，以便与监控栈集成。

• 部署和管理：Jaeger 实例通过 Kubernetes 上的 OpenTelemetry Operator 进行部署和管理。支持 Web 控制台和 CLI 两种安装方式，以及用于 pod 调度的 taints and tolerations。

• 集成：与 Alauda Build of OpenTelemetry v2 集成，用于遥测数据采集和转发；与 Alauda Service Mesh (Kiali) 集成，用于从服务网格控制台打开 trace 数据；并与 Alauda Container Platform 集成，通过 OAuth2 Proxy 进行身份验证。

#新特性和增强

• Alauda Build of Jaeger v2 集群插件：跟踪组件所需的容器镜像现在由专用集群插件提供。安装该插件会将镜像同步到内置 registry，并在 jaeger-cluster-plugin-manifest ConfigMap 中发布其地址，因此安装操作步骤会从集群中读取镜像地址，而不是将其硬编码。参见 使用 Elasticsearch 安装 Alauda Distributed Tracing。

• 可水平扩展的 Service Performance Monitoring：SPM 现在可以横向扩展。前端 OpenTelemetry Collector 按 service 将 spans 负载均衡到 Jaeger 层，因此每个 (service, operation) 时间序列都由单个写入方进行聚合，即使两层都运行多个副本，RED 指标也能保持准确。参见 Service Performance Monitoring (SPM)。

• Elasticsearch 和 OpenSearch 的 query 时间范围可配置：max_trace_duration 选项控制 query service 在请求时间窗口之外查找属于某个 trace 的 spans 的范围，替代了此前硬编码的 padding。参见 Query Time Range。

#升级说明

此版本从 Alauda Build of OpenTelemetry v2 Operator 0.147.0 和 Jaeger 2.16.0 升级到 Operator 0.157.0 和 Jaeger 2.20.0。以下变更可能会改变现有配置的行为。请在升级前检查这些变更，并按照 使用 Elasticsearch 升级 Alauda Distributed Tracing 或 使用 OpenSearch 升级 Alauda Distributed Tracing 执行操作步骤。

#不再接受旧版 Elasticsearch 轮转标志

旧版轮转标志 use_aliases、use_ilm、span_read_alias、span_write_alias、service_read_alias 和 service_write_alias 之前虽然带有弃用警告，但仍可接受。自 Jaeger v2.20.0 起，它们会导致配置校验失败，Jaeger 实例也不会启动。

请在 spans、services、dependencies 和 sampling 各自的 indices.<type> 下，使用 rotation 配置替代它们：

indices:
  spans:
    rotation:
      auto_rollover: {}

auto_rollover 的默认别名名称与 jaeger-es-rollover init 创建的别名一致，因此 Elasticsearch 侧无需更改任何数据、别名或 ILM policy。当索引模板由 rollover 初始化创建（create_mappings: false）时，请将 auto_rollover.policy_name 保持为空。参见 Index Management Strategies。

#date_layout 和 rollover_frequency 已移至 rotation.periodic 下

indices.<type> 下直接配置的 date_layout 和 rollover_frequency 字段已弃用，应改为使用 rotation.periodic.date_layout 和 rotation.periodic.rollover_frequency。仍然使用旧字段的配置可以继续工作，但同一索引类型同时设置两种形式会在启动时被拒绝，因此应当迁移字段，而不是重复配置：

indices:
  spans:
    rotation:
      periodic:
        date_layout: "2006-01-02"
        rollover_frequency: "day"

此变更不会影响索引名称。

#query 时间范围 padding 从 ±1h 变更为 ±24h

读取 spans 时，Elasticsearch 和 OpenSearch query service 会向请求时间窗口的两侧扩展，以便完整返回跨越索引边界的 traces。此前这个 padding 是硬编码为 ±1h。现在可以通过 max_trace_duration 进行配置，默认值为 24h。

更大的默认值可以提升正确性，但也会增加 query 成本：对于基于时间的索引，每次 query 在两侧都会额外扫描一个索引。请将 max_trace_duration 设置为与你预期的最长 trace 相匹配的值，例如 1h，即可恢复之前的行为。参见 Query Time Range。

#spanmetrics connector 已重命名为 span_metrics

在 Jaeger 发行版中，spanmetrics connector 类型已弃用，改用 span_metrics。旧名称仍可使用，但在启动时会报告弃用警告。请更新 connectors 部分及引用它的 pipelines：

connectors:
  span_metrics:

service:
  pipelines:
    traces:
      exporters: [jaeger_storage_exporter, span_metrics]
    metrics/spanmetrics:
      receivers: [span_metrics]
      exporters: [prometheus]

#Prometheus exporter 会忽略 add_metric_suffixes

prometheus exporter 的 add_metric_suffixes 选项已弃用，并且会被静默忽略。Jaeger 查询的是不带后缀的指标名称，例如 traces_span_metrics_calls，因此 exporter 不能追加 Prometheus 风格的后缀。请将 add_metric_suffixes: false 替换为：

exporters:
  prometheus:
    translation_strategy: UnderscoreEscapingWithoutSuffixes

如果保留这个已弃用选项，会将指标重命名为 traces_span_metrics_calls_total，并导致 Monitor 选项卡失效。

#内部指标不再需要 without_* 设置

service.telemetry.metrics 下 Prometheus reader 的 without_units、without_type_suffix 和 without_scope_info 设置现在默认值为 true。如果配置中显式将它们设为 true，可以将其删除；暴露出来的指标名称不会改变。

#service.telemetry.resource 必须保持为平面的 string map

OpenTelemetry Operator 会将 spec.config.service.telemetry.resource 解析为一个平面的 string 值 map。如果任何值是列表或嵌套 map，Operator 会静默丢弃整个 service.telemetry 部分，包括 logs.level 和 metrics.level。Jaeger 已经会报告自身的 service.name 和 service.version，因此推荐的配置是省略 resource 块，只保留 logs 和 metrics：

service:
  telemetry:
    logs:
      level: info
    metrics:
      level: detailed