#从 Alauda Container Platform Tracing 迁移

本文档介绍如何将基于旧版 Alauda Container Platform (ACP) Tracing 技术栈的现有 tracing 部署——Alauda Build of Jaeger（Jaeger 1.60.0）加上 Alauda Build of OpenTelemetry——迁移到基于 Jaeger v2（2.16.0）加上 Alauda Build of OpenTelemetry v2 的 Alauda Distributed Tracing。

迁移分为两个阶段：

1. OpenTelemetry 技术栈迁移。 将旧版 Alauda Build of OpenTelemetry Operator 和 Collector 替换为 Alauda Build of OpenTelemetry v2。随后对应用 Pod 进行滚动发布，以注入 v2 Java agent。完成此阶段后，遥测数据由 v2 Collector 收集，但仍写入旧版 Jaeger 后端。该阶段请按照 从 Alauda Build of OpenTelemetry 迁移到 Alauda Build of OpenTelemetry v2 执行。

2. Jaeger 后端迁移。 在旧版 Jaeger 旁边部署一个新的 Jaeger v2 实例，将 v2 Collector 的 trace 导出器切换到新的后端，并在旧版保留期结束后卸载旧版 Jaeger。

切换完成后，新的 trace 数据会进入新的 Jaeger v2 后端，而旧版 Jaeger 仍然提供对已存储 trace 的查询。待旧版保留期结束后（默认 7 天），再卸载旧版技术栈。

#概述

#ACP Tracing 与 Alauda Distributed Tracing 之间的变化

有关 OpenTelemetry Operator、Collector 以及 Instrumentation 资源的变更（包括现在必需的 spec.java.image 字段、Service Mesh v1 不兼容问题，以及 Collector 配置 schema 迁移），请参见 OpenTelemetry v2 迁移指南中的 v1 与 v2 之间的变化。

#迁移中断窗口

trace 采集会在两个位置中断：

1. 在 OpenTelemetry v1 → v2 迁移期间，从删除旧版 OpenTelemetryCollector 到 v2 OpenTelemetryCollector 变为 ready 之间。请参见 OpenTelemetry v2 迁移指南中的 迁移中断窗口。

2. 在 Jaeger 切换期间，当对 v2 Collector 打补丁以将其 trace 导出器从旧版 Jaeger 重定向到新的 Jaeger v2 后端时。Collector deployment 会滚动，因此在滚动过程中可能出现短暂的采集空档。

在这两个窗口期间，应用 Pod 都会继续正常运行，但在空档期间生成的遥测数据可能会被临时缓冲，并且如果不能及时导出，可能会被丢弃。请将每个阶段安排在低流量时段，并提前通知遥测数据使用者（开发者、SRE、Kiali 用户）。

迁移期间，旧版 Jaeger 查询路径始终可用，因此在新管道启动的同时，仍可在旧版 Jaeger UI 中搜索之前存储的 trace。

#迁移流程概览

[Stage 1] Migrate Alauda Build of OpenTelemetry to v2 (per external guide)
              ↓ v2 Collector keeps writing traces to the legacy Jaeger
[Step 1]  Deploy the new Jaeger v2 instance (jaeger-system)
[Step 2]  Switch the v2 OpenTelemetry Collector to write to the new Jaeger
              ↓ trace ingestion cutover; new traces go to the new Jaeger
[Step 3]  Verify the migration
              ↓
[Observation] ≤ 7 days — legacy Jaeger remains queryable for historical traces
              ↓
[Step 4]  Uninstall the legacy Jaeger instance and Operator
[Step 5]  Disable the legacy feature switch and clean up legacy ES indices

#trace 数据连续性策略

在 OpenTelemetry v2 迁移过程中，按照 重新创建 OpenTelemetryCollector 资源 的指导操作后，v2 OpenTelemetry Collector 会以与旧版 Collector 相同的 namespace 和相同的 Service 名称（cpaas-system 中的 otel-collector）进行部署。将 OTLP 导出到 otel-collector.cpaas-system 的应用无需任何配置变更即可继续工作。

在 Jaeger 切换完成后，trace 数据会按时间清晰分区：

• 切换前采集的 traces 仅保留在旧版 Jaeger 中。只要旧版 jaeger-es-index-cleaner 仍未删除它们，就可以通过旧版 Jaeger UI <platform-url>/clusters/<cluster>/acp/jaeger 进行查询——默认从索引创建日期起保留 7 天。
• 切换后采集的 traces 仅写入新的 Jaeger v2 后端。它们可以通过新的 Jaeger UI <platform-url>/clusters/<cluster>/jaeger 进行查询。

在观察期内，旧版 Jaeger 实例及其 Operator 会被刻意保留运行，以便用户继续通过旧版 UI 搜索最近的历史 trace。待旧版数据完全过期（≥ 7 天）后，即可在 清理 中卸载旧版技术栈。

#前提条件

• 由具有 cluster-admin 角色的集群管理员登录的有效 ACP CLI（kubectl）会话。
• 当前已安装旧版 ACP Tracing 技术栈（Alauda Build of Jaeger Operator 和一个 Jaeger 实例，以及 Alauda Build of OpenTelemetry 和一个 OpenTelemetryCollector 及一个或多个 Instrumentation 资源）。
• 集群可以访问 Elasticsearch 8.x，并且你拥有一个具有创建 ILM 策略、索引模板和索引别名权限的 Elasticsearch 用户。
• 执行迁移命令的工作站已安装 jq 和 envsubst 命令行工具。
• 已通知遥测数据使用者（开发者、Kiali 用户、SRE dashboard）以及应用所有者有关计划中的中断窗口。

#迁移前任务

#将 Alauda Build of OpenTelemetry 迁移到 v2

在迁移 Jaeger 后端之前，请先按照 从 Alauda Build of OpenTelemetry 迁移到 Alauda Build of OpenTelemetry v2 完成从 Alauda Build of OpenTelemetry 到 Alauda Build of OpenTelemetry v2 的迁移。该指南涵盖：

• 备份并卸载旧版 Alauda Build of OpenTelemetry Operator 及其 OpenTelemetryCollector 和 Instrumentation 资源。
• 安装 v2 Operator。
• 准备 Java auto-instrumentation 镜像并重新创建 OpenTelemetryCollector 和 Instrumentation 资源，包括设置现在必需的 spec.java.image 字段。
• 对应用 Pod 进行滚动发布，以注入新的 Java agent。

在此阶段结束时：

• 已安装 v2 Alauda Build of OpenTelemetry Operator，旧版 Operator 已卸载。
• cpaas-system 中的 v2 OpenTelemetryCollector 正在运行，其 trace 导出器仍然指向旧版 Jaeger（这是从 v1 备份重建 Collector 的自然结果）。
• 所有 Instrumentation 资源都已设置 spec.java.image，并且应用 Pod 已通过 v2 Java agent 完成滚动发布。

在本指南的 将 v2 OpenTelemetry Collector 切换到新的 Jaeger 之前，trace 采集会继续流向旧版 Jaeger。

#清点旧版 Jaeger 部署

记录旧版 Jaeger 的当前状态，以便了解迁移范围并生成回滚所需的备份。

1. 列出旧版 Alauda Build of Jaeger Operator 和 Jaeger 实例：

   kubectl get csv -A | grep -i jaeger
   kubectl get jaeger -A

2. 记录旧版 Jaeger 资源中引用的旧版 Elasticsearch endpoint、凭据和索引前缀。它们也会被新的 Jaeger v2 实例复用。

#备份旧版 Jaeger 资源

导出旧版 Jaeger 资源，以便后续重建（以及在需要时回滚）：

mkdir -p ./acp-tracing-backup

# Jaeger CR (covers the jaeger-prod instance in cpaas-system).
kubectl get jaeger -A -o yaml \
  > ./acp-tracing-backup/jaegers.yaml

# Alauda Build of Jaeger Operator Subscription and CSV.
kubectl get subscription -n jaeger-operator jaeger-operator -o yaml \
  > ./acp-tracing-backup/jaeger-v1-subscription.yaml || true
kubectl -n jaeger-operator get csv -o yaml \
  > ./acp-tracing-backup/jaeger-v1-csv.yaml || true

# Supporting resources for jaeger-prod in cpaas-system. Each is removed in
# Cleanup, so back them up here so rollback can restore them. Skip silently
# (|| true) if a resource is not present in this environment.
kubectl -n cpaas-system get ingress     jaeger-prod-query         -o yaml \
  > ./acp-tracing-backup/jaeger-prod-ingress.yaml             || true
kubectl -n cpaas-system get podmonitor  jaeger-prod-monitor       -o yaml \
  > ./acp-tracing-backup/jaeger-prod-podmonitor.yaml          || true
kubectl -n cpaas-system get rolebinding jaeger-prod-rb            -o yaml \
  > ./acp-tracing-backup/jaeger-prod-rolebinding.yaml         || true
kubectl -n cpaas-system get role        jaeger-prod-role          -o yaml \
  > ./acp-tracing-backup/jaeger-prod-role.yaml                || true
kubectl -n cpaas-system get sa          jaeger-prod-sa            -o yaml \
  > ./acp-tracing-backup/jaeger-prod-sa.yaml                  || true
kubectl -n cpaas-system get secret      jaeger-prod-oauth2-proxy  -o yaml \
  > ./acp-tracing-backup/jaeger-prod-oauth2-proxy-secret.yaml || true
kubectl -n cpaas-system get secret      jaeger-prod-es-basic-auth -o yaml \
  > ./acp-tracing-backup/jaeger-prod-es-basic-auth-secret.yaml || true
kubectl -n cpaas-system get configmap   jaeger-prod-oauth2-proxy  -o yaml \
  > ./acp-tracing-backup/jaeger-prod-oauth2-proxy-configmap.yaml || true

#验证 Elasticsearch 容量

新的 Jaeger 会写入一组单独的索引（acp-<cluster>-jaeger-*），而旧版索引（acp-tracing-<cluster>-jaeger-*）会在旧版保留期内逐步过期。请为 Elasticsearch 中额外一整段保留期的 trace 存储预留容量。如果选择 (可选) 启用向旧版 Jaeger 的双重导出，则在观察期内应按大约两倍的稳态存储量来规划。

#迁移操作步骤

export JAEGER_NS="jaeger-system"
export JAEGER_INSTANCE_NAME="jaeger"
export JAEGER_ES_INDEX_PREFIX="acp-${CLUSTER_NAME}"      # different from the legacy "acp-tracing-${CLUSTER_NAME}"
export JAEGER_BASEPATH="/clusters/${CLUSTER_NAME}/jaeger"  # different from the legacy "/clusters/${CLUSTER_NAME}/acp/jaeger"

spec:
  config:
    exporters:
      debug: {}
      otlp:
        balancer_name: round_robin
        endpoint: dns:///jaeger-prod-collector-headless.cpaas-system:4317
        tls:
          insecure: true
    service:
      pipelines:
        traces:
          receivers:  [otlp]
          processors: [memory_limiter, batch]
          exporters:  [debug, otlp] 

kubectl -n cpaas-system patch opentelemetrycollector otel --type=merge -p '
spec:
  config:
    exporters:
      otlp/jaeger-v2:
        endpoint: jaeger-collector.jaeger-system.svc.cluster.local:4317
        tls:
          insecure: true
      otlp: null
    service:
      pipelines:
        traces:
          exporters: [debug, otlp/jaeger-v2]
'
kubectl rollout status deployment/otel-collector -n cpaas-system --timeout=180s

#观察期

在切换完成后，请让旧版 Jaeger 继续运行 至少 7 天，与旧版 esIndexCleaner.numberOfDays 保留设置保持一致。在此窗口期间：

• 旧版 Jaeger UI 会继续提供任何尚未被旧版 jaeger-es-index-cleaner 删除的切换前 traces。清理器会在每个索引创建日期约 7 天后将其删除；一旦所有切换前索引都被清理，旧版 Jaeger 就不再保有有价值的数据，可以卸载。
• 新的 Jaeger 会持续累积切换后产生的 traces。请基于新的 Jaeger UI 和 v2 Java agent 的指标名称验证 dashboard、告警以及 Kiali 集成。
• 请清楚地向用户说明分界：新的 Jaeger UI 显示的是切换后的 traces，而较旧的 traces 仍保留在旧版 Jaeger UI 中。

如果切换前的 traces 没有业务价值，你可以缩短或跳过观察期，直接进入 清理；代价是，一旦旧版技术栈被移除，切换前的所有 traces 就不再可访问。

#清理

kubectl -n cpaas-system delete ingress      jaeger-prod-query         --ignore-not-found
kubectl -n cpaas-system delete podmonitor   jaeger-prod-monitor       --ignore-not-found
kubectl -n cpaas-system delete jaeger       jaeger-prod               --ignore-not-found
kubectl -n cpaas-system delete rolebinding  jaeger-prod-rb            --ignore-not-found
kubectl -n cpaas-system delete role         jaeger-prod-role          --ignore-not-found
kubectl -n cpaas-system delete sa           jaeger-prod-sa            --ignore-not-found
kubectl -n cpaas-system delete secret       jaeger-prod-oauth2-proxy  --ignore-not-found
kubectl -n cpaas-system delete secret       jaeger-prod-es-basic-auth --ignore-not-found
kubectl -n cpaas-system delete configmap    jaeger-prod-oauth2-proxy  --ignore-not-found

kubectl -n jaeger-operator delete subscription jaeger-operator --ignore-not-found

kubectl get jaeger -A
kubectl delete crd jaegers.jaegertracing.io

#（可选）启用向旧版 Jaeger 的双重导出

将 v2 OpenTelemetry Collector 配置为把每个 span 同时写入新的 Jaeger和旧版 Jaeger，是默认单导出 pipeline 的一种可选方案。以下场景下可以考虑使用：

• 并行验证。 你希望在完全依赖新的后端之前，使用生产流量对比新的 Jaeger 与旧版 Jaeger。
• 更快的原地回滚。 如果新的 Jaeger 在观察期内出现问题，你可以通过一个补丁将 otlp/jaeger-v2 从 trace pipeline 中移除，而旧版 Jaeger 会继续无中断地接收 traces。
• 渐进式 UI 切换。 不同团队计划按照各自节奏从旧版 UI 切换到新 UI，而你希望在过渡期间两个 UI 都能显示切换后的数据。

权衡如下：

• 由于每个 span 都会被索引到两套索引族中，Elasticsearch 的写入负载和存储使用在观察期内大约会翻倍。
• 在卸载旧版 Jaeger 之前，必须通过 停止双重导出 中的额外补丁来回退 trace pipeline。
• 必须监控两个导出 pipeline 的失败情况（otelcol_exporter_send_failed_spans_total，同时适用于 otlp/jaeger-v2 和 otlp/jaeger-v1）。

双重导出不会将切换前的 traces 回填到新的 Jaeger；切换前的 traces 仍然只能通过旧版 Jaeger UI 查询。

#启用双重导出

在 将 v2 OpenTelemetry Collector 切换到新的 Jaeger 收敛后，otel Collector 只有 otlp/jaeger-v2 这一个会写入 Jaeger 后端的 trace 导出器（trace pipeline 为 [debug, otlp/jaeger-v2]）。请对 Collector 打补丁，将旧版 Jaeger 重新作为第二个导出器 otlp/jaeger-v1 加回去，镜像此前在切换步骤中移除的原始 otlp 导出器的旧版 Jaeger endpoint、headless-Service 负载均衡和 TLS 设置：

kubectl -n cpaas-system patch opentelemetrycollector otel --type=merge -p '
spec:
  config:
    exporters:
      otlp/jaeger-v1:
        endpoint: dns:///jaeger-prod-collector-headless.cpaas-system:4317
        balancer_name: round_robin
        tls:
          insecure: true
    service:
      pipelines:
        traces:
          exporters: [debug, otlp/jaeger-v2, otlp/jaeger-v1]
'
kubectl rollout status deployment/otel-collector -n cpaas-system --timeout=180s

补丁应用后，每个 span 都会同时写入两个 Jaeger 后端。

#停止双重导出

在观察期结束后、执行 卸载旧版 Jaeger 实例 之前，请从 trace pipeline 中移除旧版导出器：

kubectl -n cpaas-system patch opentelemetrycollector otel --type=merge -p '
spec:
  config:
    exporters:
      otlp/jaeger-v1: null
    service:
      pipelines:
        traces:
          exporters: [debug, otlp/jaeger-v2]
'
kubectl rollout status deployment/otel-collector -n cpaas-system --timeout=180s

应用此补丁后，v2 Collector 将只把 traces 写入新的 Jaeger。此时即可继续执行 卸载旧版 Jaeger 实例。

#回滚

关于 OpenTelemetry v1 → v2 阶段的回滚，请参见 OpenTelemetry v2 迁移指南中的 回滚。对于本文档中执行的 Jaeger 迁移阶段，请根据你当前所处的阶段选择对应的回滚路径：

#FAQ

应用是否需要更新它们的 OTLP endpoint？

不需要。按照 OpenTelemetry v2 迁移指南中的 重新创建 OpenTelemetryCollector 资源 操作后，v2 OpenTelemetry Collector 会部署在相同的 namespace（cpaas-system）中，使用相同的 Service 名称（otel-collector）和相同的端口（4317/4318）。向 otel-collector.cpaas-system:4317 导出的工作负载无需任何变更即可继续工作。

新的 Jaeger UI 会显示切换前的 traces 吗？

不会。切换前的 traces 仅存储在旧版 Jaeger 中，并会在旧版保留窗口期间（默认 7 天）继续可通过旧版 Jaeger UI 查询。新的 Jaeger UI 会从切换点开始显示 traces。请提前向用户说明这一点，并在观察期内将较旧的 traces 引导到旧版 UI 中查询。

什么时候应该启用双重导出？

默认的单导出路径足以满足大多数迁移需求。只有在以下任一情况成立时，才启用双重导出（(可选) 启用向旧版 Jaeger 的双重导出）：

• 你需要在依赖新 Jaeger 之前，使用生产流量将其与旧版 Jaeger 进行验证。
• 不同团队会按照独立节奏从旧版 UI 切换到新 UI，而你希望在过渡期间两个 UI 都显示切换后的数据。
• 你希望在观察期内获得尽可能快的原地回滚路径。

请注意，双重导出会在观察期内将 Elasticsearch 的写入负载和存储大约翻倍，并且在卸载旧版 Jaeger 之前还要额外执行一个补丁步骤。

旧版 Jaeger 和新的 Jaeger 能共享同一个 Elasticsearch 索引吗？

不能。旧版 Jaeger 使用按天生成带日期戳的索引（acp-tracing-<cluster>-jaeger-span-YYYY-MM-DD），而 Jaeger v2 使用 rollover 别名（acp-<cluster>-jaeger-span-write / -read，其后端为 *-000001、*-000002 等）。两者的 schema 和生命周期管理方式不同，因此必须保持两套索引族分离。请保留 部署新的 Jaeger v2 实例 中显示的默认前缀，以避免冲突。

观察期需要额外多少 Elasticsearch 存储？

采用默认单导出路径时，新索引族会从零增长，而旧索引族会在旧版保留期内逐步过期；请按额外一整段保留期的 trace 存储量预留稳态缓冲。启用双重导出时，在观察期内请按旧索引族稳态大小的大约两倍来规划，并为重试和采集突发预留余量。

是否可以在迁移过程中启用 Service Performance Monitoring（SPM）？

SPM 是可选功能，可以在 验证迁移 之后随时启用。请按照 (可选) 启用 Service Performance Monitoring（SPM） 的说明，将 spanmetrics connector 添加到 v2 OpenTelemetry Collector，并在新的 Jaeger 中配置一个 metrics 后端。