From e5c0f5246687626125cff3146c720501708ea799 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E7=8E=8B=E7=84=B6?= <ranwang@alauda.io>
Date: Mon, 3 Aug 2026 11:09:58 +0000
Subject: [PATCH 1/8] docs: install jaeger images via Alauda Build of Jaeger v2
 cluster plugin
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Add a step to install the Alauda Build of Jaeger v2 cluster plugin
(web console and CLI) before installing the OpenTelemetry Operator,
and read Jaeger-related image addresses from the ConfigMap
jaeger-cluster-plugin-manifest instead of the operator CSV
relatedImages. The jq prerequisite is no longer needed.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Signed-off-by: 王然 <ranwang@alauda.io>
---
 ...ling-distributed-tracing-elasticsearch.mdx | 77 ++++++++++++++++---
 ...talling-distributed-tracing-opensearch.mdx | 77 ++++++++++++++++---
 2 files changed, 132 insertions(+), 22 deletions(-)

diff --git a/docs/en/installing/installing-distributed-tracing-elasticsearch.mdx b/docs/en/installing/installing-distributed-tracing-elasticsearch.mdx
index 996db95..b5f5cdf 100644
--- a/docs/en/installing/installing-distributed-tracing-elasticsearch.mdx
+++ b/docs/en/installing/installing-distributed-tracing-elasticsearch.mdx
@@ -6,9 +6,67 @@ weight: 10
 
 Installing the Alauda Distributed Tracing platform involves the following steps:
 
-1. Installing the Alauda Build of OpenTelemetry v2 Operator
-2. Deploying the Alauda Build of Jaeger v2
-3. Deploying the OpenTelemetry Collector to forward traces to Jaeger
+1. Installing the Alauda Build of Jaeger v2 cluster plugin
+2. Installing the Alauda Build of OpenTelemetry v2 Operator
+3. Deploying the Alauda Build of Jaeger v2
+4. Deploying the OpenTelemetry Collector to forward traces to Jaeger
+
+## Installing the Alauda Build of Jaeger v2 Cluster Plugin \{#installing-the-alauda-build-of-jaeger-v2-cluster-plugin}
+
+The Alauda Build of Jaeger v2 cluster plugin ships the container images required by the tracing components: Jaeger (`jaeger`, `jaeger-es-rollover`, `jaeger-es-index-cleaner`) and OAuth2 Proxy. Installing the plugin synchronizes these images to the platform's built-in registry and creates a ConfigMap named `jaeger-cluster-plugin-manifest` in the `cpaas-system` namespace of the target cluster. Later steps read the image addresses from this ConfigMap.
+
+### Installing via the web console
+
+1. In the platform management view, navigate to **Administrator** > **Marketplace** > **Cluster Plugins**.
+2. Select the cluster where the tracing components will be deployed.
+3. Find **Alauda Build of Jaeger v2** and click **Install**. The plugin requires no installation parameters.
+
+:::note
+If the plugin is not listed, download the plugin package from the Customer Portal and publish it to the platform with the `violet` tool, or contact technical support.
+:::
+
+### Installing via the CLI
+
+Cluster plugins are installed by creating a `ModuleInfo` resource **in the `global` cluster**, regardless of which cluster the plugin targets.
+
+1. Run the following command in the `global` cluster to check the published plugin versions:
+
+    ```bash
+    kubectl get moduleconfigs -l cpaas.io/module-name=jaeger-cluster-plugin \
+      -o custom-columns=NAME:.metadata.name,VERSION:.spec.version
+    ```
+
+2. Create a `ModuleInfo` resource in the `global` cluster to install the plugin. Replace `<target-cluster>` with the name of the cluster where the tracing components will be deployed, and `<plugin-version>` with a version from the previous step:
+
+    ```bash
+    kubectl apply -f - <<EOF
+    apiVersion: cluster.alauda.io/v1alpha1
+    kind: ModuleInfo
+    metadata:
+      labels:
+        cpaas.io/cluster-name: <target-cluster>
+        cpaas.io/module-name: jaeger-cluster-plugin
+        cpaas.io/module-type: plugin
+      name: <target-cluster>-jaeger-cluster-plugin
+    spec:
+      config: {}
+      version: <plugin-version>
+    EOF
+    ```
+
+3. Verify the installation in the `global` cluster:
+
+    ```bash
+    kubectl get moduleinfo -l cpaas.io/module-name=jaeger-cluster-plugin
+    ```
+
+    The plugin is installed successfully when the `STATUS` column shows `Running`.
+
+4. Verify that the ConfigMap has been created in the target cluster (run against the target cluster):
+
+    ```bash
+    kubectl get configmap jaeger-cluster-plugin-manifest -n cpaas-system
+    ```
 
 ## Installing the Alauda Build of OpenTelemetry v2 Operator \{#installing-the-alauda-build-of-opentelemetry-v2-operator}
 
@@ -28,10 +86,10 @@ Jaeger v2 is deployed as an `OpenTelemetryCollector` custom resource managed by
 
 **Prerequisites**
 
+- The Alauda Build of Jaeger v2 cluster plugin is installed.
 - The Alauda Build of OpenTelemetry v2 Operator is installed.
 - An Elasticsearch 8.x instance is available, and you have the endpoint URL, username, and password for it.
 - An active ACP CLI (`kubectl`) session by a cluster administrator with the `cluster-admin` role.
-- The `jq` command-line tool is installed.
 
 **Procedure**
 
@@ -45,7 +103,7 @@ Jaeger v2 is deployed as an `OpenTelemetryCollector` custom resource managed by
 
     Replace the placeholder values with your actual Elasticsearch credentials.
 
-2. Retrieve platform configuration and Jaeger-related container images from the cluster:
+2. Retrieve platform configuration from the cluster and the Jaeger-related container images from the ConfigMap created by the Alauda Build of Jaeger v2 cluster plugin:
 
     ```bash {name=install-tracing-elasticsearch:get-platform-config}
     export PLATFORM_URL=$(kubectl -nkube-public get configmap global-info -o jsonpath='{.data.platformURL}')
@@ -63,12 +121,9 @@ Jaeger v2 is deployed as an `OpenTelemetryCollector` custom resource managed by
       export OIDC_CLIENT_SECRET=$(kubectl -nkube-public get configmap global-info -o jsonpath='{.data.oidcClientSecret}')
     fi
 
-    JAEGER_RELATED_IMAGES=$(kubectl get csv -n opentelemetry-operator2 \
-      -l 'operators.coreos.com/opentelemetry-operator2.opentelemetry-operator2=' \
-      -o jsonpath='{.items[0].spec.relatedImages}')
-    export JAEGER_IMAGE=$(echo "$JAEGER_RELATED_IMAGES" | jq -r '.[] | select(.name=="component.jaeger") | .image')
-    export JAEGER_ES_ROLLOVER_IMAGE=$(echo "$JAEGER_RELATED_IMAGES" | jq -r '.[] | select(.name=="component.jaeger-es-rollover") | .image')
-    export JOAUTH2_PROXY_IMAGE=$(echo "$JAEGER_RELATED_IMAGES" | jq -r '.[] | select(.name=="component.oauth2-proxy") | .image')
+    export JAEGER_IMAGE=$(kubectl -ncpaas-system get configmap jaeger-cluster-plugin-manifest -o jsonpath='{.data.jaeger-image}')
+    export JAEGER_ES_ROLLOVER_IMAGE=$(kubectl -ncpaas-system get configmap jaeger-cluster-plugin-manifest -o jsonpath='{.data.jaeger-es-rollover-image}')
+    export JOAUTH2_PROXY_IMAGE=$(kubectl -ncpaas-system get configmap jaeger-cluster-plugin-manifest -o jsonpath='{.data.oauth2-proxy-image}')
     ```
 
     :::note
diff --git a/docs/en/installing/installing-distributed-tracing-opensearch.mdx b/docs/en/installing/installing-distributed-tracing-opensearch.mdx
index 99b2239..766ea72 100644
--- a/docs/en/installing/installing-distributed-tracing-opensearch.mdx
+++ b/docs/en/installing/installing-distributed-tracing-opensearch.mdx
@@ -6,9 +6,67 @@ weight: 20
 
 Installing the Alauda Distributed Tracing platform involves the following steps:
 
-1. Installing the Alauda Build of OpenTelemetry v2 Operator
-2. Deploying the Alauda Build of Jaeger v2
-3. Deploying the OpenTelemetry Collector to forward traces to Jaeger
+1. Installing the Alauda Build of Jaeger v2 cluster plugin
+2. Installing the Alauda Build of OpenTelemetry v2 Operator
+3. Deploying the Alauda Build of Jaeger v2
+4. Deploying the OpenTelemetry Collector to forward traces to Jaeger
+
+## Installing the Alauda Build of Jaeger v2 Cluster Plugin \{#installing-the-alauda-build-of-jaeger-v2-cluster-plugin}
+
+The Alauda Build of Jaeger v2 cluster plugin ships the container images required by the tracing components: Jaeger (`jaeger`, `jaeger-es-rollover`, `jaeger-es-index-cleaner`) and OAuth2 Proxy. Installing the plugin synchronizes these images to the platform's built-in registry and creates a ConfigMap named `jaeger-cluster-plugin-manifest` in the `cpaas-system` namespace of the target cluster. Later steps read the image addresses from this ConfigMap.
+
+### Installing via the web console
+
+1. In the platform management view, navigate to **Administrator** > **Marketplace** > **Cluster Plugins**.
+2. Select the cluster where the tracing components will be deployed.
+3. Find **Alauda Build of Jaeger v2** and click **Install**. The plugin requires no installation parameters.
+
+:::note
+If the plugin is not listed, download the plugin package from the Customer Portal and publish it to the platform with the `violet` tool, or contact technical support.
+:::
+
+### Installing via the CLI
+
+Cluster plugins are installed by creating a `ModuleInfo` resource **in the `global` cluster**, regardless of which cluster the plugin targets.
+
+1. Run the following command in the `global` cluster to check the published plugin versions:
+
+    ```bash
+    kubectl get moduleconfigs -l cpaas.io/module-name=jaeger-cluster-plugin \
+      -o custom-columns=NAME:.metadata.name,VERSION:.spec.version
+    ```
+
+2. Create a `ModuleInfo` resource in the `global` cluster to install the plugin. Replace `<target-cluster>` with the name of the cluster where the tracing components will be deployed, and `<plugin-version>` with a version from the previous step:
+
+    ```bash
+    kubectl apply -f - <<EOF
+    apiVersion: cluster.alauda.io/v1alpha1
+    kind: ModuleInfo
+    metadata:
+      labels:
+        cpaas.io/cluster-name: <target-cluster>
+        cpaas.io/module-name: jaeger-cluster-plugin
+        cpaas.io/module-type: plugin
+      name: <target-cluster>-jaeger-cluster-plugin
+    spec:
+      config: {}
+      version: <plugin-version>
+    EOF
+    ```
+
+3. Verify the installation in the `global` cluster:
+
+    ```bash
+    kubectl get moduleinfo -l cpaas.io/module-name=jaeger-cluster-plugin
+    ```
+
+    The plugin is installed successfully when the `STATUS` column shows `Running`.
+
+4. Verify that the ConfigMap has been created in the target cluster (run against the target cluster):
+
+    ```bash
+    kubectl get configmap jaeger-cluster-plugin-manifest -n cpaas-system
+    ```
 
 ## Installing the Alauda Build of OpenTelemetry v2 Operator \{#installing-the-alauda-build-of-opentelemetry-v2-operator}
 
@@ -28,10 +86,10 @@ Jaeger v2 is deployed as an `OpenTelemetryCollector` custom resource managed by
 
 **Prerequisites**
 
+- The Alauda Build of Jaeger v2 cluster plugin is installed.
 - The Alauda Build of OpenTelemetry v2 Operator is installed.
 - An OpenSearch 3.x instance is available, and you have the endpoint URL, username, and password for it.
 - An active ACP CLI (`kubectl`) session by a cluster administrator with the `cluster-admin` role.
-- The `jq` command-line tool is installed.
 
 **Procedure**
 
@@ -45,7 +103,7 @@ Jaeger v2 is deployed as an `OpenTelemetryCollector` custom resource managed by
 
     Replace the placeholder values with your actual OpenSearch credentials.
 
-2. Retrieve platform configuration and Jaeger-related container images from the cluster:
+2. Retrieve platform configuration from the cluster and the Jaeger-related container images from the ConfigMap created by the Alauda Build of Jaeger v2 cluster plugin:
 
     ```bash {name=install-tracing-opensearch:get-platform-config}
     export PLATFORM_URL=$(kubectl -nkube-public get configmap global-info -o jsonpath='{.data.platformURL}')
@@ -63,12 +121,9 @@ Jaeger v2 is deployed as an `OpenTelemetryCollector` custom resource managed by
       export OIDC_CLIENT_SECRET=$(kubectl -nkube-public get configmap global-info -o jsonpath='{.data.oidcClientSecret}')
     fi
 
-    JAEGER_RELATED_IMAGES=$(kubectl get csv -n opentelemetry-operator2 \
-      -l 'operators.coreos.com/opentelemetry-operator2.opentelemetry-operator2=' \
-      -o jsonpath='{.items[0].spec.relatedImages}')
-    export JAEGER_IMAGE=$(echo "$JAEGER_RELATED_IMAGES" | jq -r '.[] | select(.name=="component.jaeger") | .image')
-    export JAEGER_ES_INDEX_CLEANER_IMAGE=$(echo "$JAEGER_RELATED_IMAGES" | jq -r '.[] | select(.name=="component.jaeger-es-index-cleaner") | .image')
-    export JOAUTH2_PROXY_IMAGE=$(echo "$JAEGER_RELATED_IMAGES" | jq -r '.[] | select(.name=="component.oauth2-proxy") | .image')
+    export JAEGER_IMAGE=$(kubectl -ncpaas-system get configmap jaeger-cluster-plugin-manifest -o jsonpath='{.data.jaeger-image}')
+    export JAEGER_ES_INDEX_CLEANER_IMAGE=$(kubectl -ncpaas-system get configmap jaeger-cluster-plugin-manifest -o jsonpath='{.data.jaeger-es-index-cleaner-image}')
+    export JOAUTH2_PROXY_IMAGE=$(kubectl -ncpaas-system get configmap jaeger-cluster-plugin-manifest -o jsonpath='{.data.oauth2-proxy-image}')
     ```
 
     :::note

From 7185fd54613e073b1e4cef8e552bd16899029e41 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E7=8E=8B=E7=84=B6?= <ranwang@alauda.io>
Date: Tue, 4 Aug 2026 08:54:22 +0000
Subject: [PATCH 2/8] =?UTF-8?q?test:=20=E5=AE=89=E8=A3=85=E6=B5=8B?=
 =?UTF-8?q?=E8=AF=95=E8=A6=86=E7=9B=96=20Jaeger=20v2=20=E9=9B=86=E7=BE=A4?=
 =?UTF-8?q?=E6=8F=92=E4=BB=B6=20CLI=20=E5=AE=89=E8=A3=85=E7=AB=A0=E8=8A=82?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- 两篇安装文档「Installing via the CLI」的 4 个代码块命名
  （list-jaeger-plugin-versions / create-jaeger-plugin-moduleinfo /
  verify-jaeger-plugin-moduleinfo / verify-jaeger-plugin-configmap，
  各用所在文档前缀）
- 测试脚本新增步骤 1：调用共享函数 tracing_install_jaeger_plugin
  （docs-runme-tests projects/tracing/jaeger-plugin.sh，两文档章节
  内容一致，按 runme 前缀参数化防止重复），原步骤整体 +1
- 仅覆盖 CLI 安装方案；Web console 章节不纳入测试

Claude-Session: https://claude.ai/code/session_01HbXxahwdrejkRE3G68B9Ns
---
 ...ling-distributed-tracing-elasticsearch.mdx |   8 +-
 ...talling-distributed-tracing-opensearch.mdx |   8 +-
 ...lling-distributed-tracing-elasticsearch.sh | 159 ++++++++++--------
 ...stalling-distributed-tracing-opensearch.sh | 149 ++++++++--------
 4 files changed, 175 insertions(+), 149 deletions(-)

diff --git a/docs/en/installing/installing-distributed-tracing-elasticsearch.mdx b/docs/en/installing/installing-distributed-tracing-elasticsearch.mdx
index b5f5cdf..192eb74 100644
--- a/docs/en/installing/installing-distributed-tracing-elasticsearch.mdx
+++ b/docs/en/installing/installing-distributed-tracing-elasticsearch.mdx
@@ -31,14 +31,14 @@ Cluster plugins are installed by creating a `ModuleInfo` resource **in the `glob
 
 1. Run the following command in the `global` cluster to check the published plugin versions:
 
-    ```bash
+    ```bash {name=install-tracing-elasticsearch:list-jaeger-plugin-versions}
     kubectl get moduleconfigs -l cpaas.io/module-name=jaeger-cluster-plugin \
       -o custom-columns=NAME:.metadata.name,VERSION:.spec.version
     ```
 
 2. Create a `ModuleInfo` resource in the `global` cluster to install the plugin. Replace `<target-cluster>` with the name of the cluster where the tracing components will be deployed, and `<plugin-version>` with a version from the previous step:
 
-    ```bash
+    ```bash {name=install-tracing-elasticsearch:create-jaeger-plugin-moduleinfo}
     kubectl apply -f - <<EOF
     apiVersion: cluster.alauda.io/v1alpha1
     kind: ModuleInfo
@@ -56,7 +56,7 @@ Cluster plugins are installed by creating a `ModuleInfo` resource **in the `glob
 
 3. Verify the installation in the `global` cluster:
 
-    ```bash
+    ```bash {name=install-tracing-elasticsearch:verify-jaeger-plugin-moduleinfo}
     kubectl get moduleinfo -l cpaas.io/module-name=jaeger-cluster-plugin
     ```
 
@@ -64,7 +64,7 @@ Cluster plugins are installed by creating a `ModuleInfo` resource **in the `glob
 
 4. Verify that the ConfigMap has been created in the target cluster (run against the target cluster):
 
-    ```bash
+    ```bash {name=install-tracing-elasticsearch:verify-jaeger-plugin-configmap}
     kubectl get configmap jaeger-cluster-plugin-manifest -n cpaas-system
     ```
 
diff --git a/docs/en/installing/installing-distributed-tracing-opensearch.mdx b/docs/en/installing/installing-distributed-tracing-opensearch.mdx
index 766ea72..5d49b38 100644
--- a/docs/en/installing/installing-distributed-tracing-opensearch.mdx
+++ b/docs/en/installing/installing-distributed-tracing-opensearch.mdx
@@ -31,14 +31,14 @@ Cluster plugins are installed by creating a `ModuleInfo` resource **in the `glob
 
 1. Run the following command in the `global` cluster to check the published plugin versions:
 
-    ```bash
+    ```bash {name=install-tracing-opensearch:list-jaeger-plugin-versions}
     kubectl get moduleconfigs -l cpaas.io/module-name=jaeger-cluster-plugin \
       -o custom-columns=NAME:.metadata.name,VERSION:.spec.version
     ```
 
 2. Create a `ModuleInfo` resource in the `global` cluster to install the plugin. Replace `<target-cluster>` with the name of the cluster where the tracing components will be deployed, and `<plugin-version>` with a version from the previous step:
 
-    ```bash
+    ```bash {name=install-tracing-opensearch:create-jaeger-plugin-moduleinfo}
     kubectl apply -f - <<EOF
     apiVersion: cluster.alauda.io/v1alpha1
     kind: ModuleInfo
@@ -56,7 +56,7 @@ Cluster plugins are installed by creating a `ModuleInfo` resource **in the `glob
 
 3. Verify the installation in the `global` cluster:
 
-    ```bash
+    ```bash {name=install-tracing-opensearch:verify-jaeger-plugin-moduleinfo}
     kubectl get moduleinfo -l cpaas.io/module-name=jaeger-cluster-plugin
     ```
 
@@ -64,7 +64,7 @@ Cluster plugins are installed by creating a `ModuleInfo` resource **in the `glob
 
 4. Verify that the ConfigMap has been created in the target cluster (run against the target cluster):
 
-    ```bash
+    ```bash {name=install-tracing-opensearch:verify-jaeger-plugin-configmap}
     kubectl get configmap jaeger-cluster-plugin-manifest -n cpaas-system
     ```
 
diff --git a/docs/en/installing/runme-test_installing-distributed-tracing-elasticsearch.sh b/docs/en/installing/runme-test_installing-distributed-tracing-elasticsearch.sh
index 5ea080f..0a53108 100755
--- a/docs/en/installing/runme-test_installing-distributed-tracing-elasticsearch.sh
+++ b/docs/en/installing/runme-test_installing-distributed-tracing-elasticsearch.sh
@@ -1,8 +1,9 @@
 #!/usr/bin/env bash
 # Alauda Distributed Tracing 安装文档测试脚本
 # 对应文档: docs/en/installing/installing-distributed-tracing-elasticsearch.mdx
-# 覆盖范围: 「Deploying the Alauda Build of Jaeger v2」与「Deploying the OpenTelemetry
-#           Collector」「Verification」章节；「(Optional) SPM」章节首期不纳入。
+# 覆盖范围: 「Installing the Alauda Build of Jaeger v2 Cluster Plugin」（仅 CLI 安装方案）
+#           「Deploying the Alauda Build of Jaeger v2」「Deploying the OpenTelemetry
+#           Collector」「Verification」「(Optional) SPM」章节。
 # 前置步骤: TRACING_INSTALL_ES=true 且 PKG_LOG_CENTER_URL 非空时，步骤 0 自动安装
 #           ACP 日志存储 Elasticsearch（logcenter 集群插件）到 TRACING_ACP_ES_CLUSTER
 #           指定集群（已安装则跳过），见 docs-runme-tests/projects/tracing/elasticsearch.sh。
@@ -14,7 +15,8 @@ set -e
 # 加载框架函数库
 source "$FRAMEWORK_ROOT/framework/common.sh"
 source "$FRAMEWORK_ROOT/framework/verify.sh"
-# tracing 项目钩子：提供 _tracing_load_acp_es_config / _tracing_set_default_acp_es_cluster。
+# tracing 项目钩子：提供 _tracing_load_acp_es_config / _tracing_set_default_acp_es_cluster，
+# 以及 Jaeger v2 集群插件共享安装函数 tracing_install_jaeger_plugin（与 OpenSearch 版共用）。
 # ACP ES 配置加载已从 project_prepare 下沉到本 Elasticsearch 安装测试，确保
 # _tracing_load_acp_es_config 只在 Elasticsearch 场景执行（OpenSearch 测试不引入）。
 source "$FRAMEWORK_ROOT/projects/tracing/project.sh"
@@ -63,61 +65,61 @@ _deploy_telemetrygen() {
 _test_spm() {
     log_header "Service Performance Monitoring (SPM) 测试"
 
-    # 步骤 19: 拉取 monitoring 端点与凭据
-    log_info "步骤 19: 拉取 monitoring 配置"
+    # 步骤 20: 拉取 monitoring 端点与凭据
+    log_info "步骤 20: 拉取 monitoring 配置"
     eval "$(runme print install-tracing-elasticsearch-spm:get-monitoring-config)" || {
         log_error "拉取 monitoring 配置失败"
         return 1
     }
 
-    # 步骤 20: 创建 monitoring 凭据 Secret
-    log_info "步骤 20: 创建 monitoring 凭据 Secret"
+    # 步骤 21: 创建 monitoring 凭据 Secret
+    log_info "步骤 21: 创建 monitoring 凭据 Secret"
     runme run install-tracing-elasticsearch-spm:create-monitoring-secret || {
         log_error "创建 monitoring 凭据 Secret 失败"
         return 1
     }
 
-    # 步骤 21: Patch OpenTelemetry Collector 改用 loadbalancing 按 service 路由到 Jaeger（spanmetrics 已移至 Jaeger）
-    log_info "步骤 21: Patch OpenTelemetry Collector 配置 loadbalancing 按 service 路由"
+    # 步骤 22: Patch OpenTelemetry Collector 改用 loadbalancing 按 service 路由到 Jaeger（spanmetrics 已移至 Jaeger）
+    log_info "步骤 22: Patch OpenTelemetry Collector 配置 loadbalancing 按 service 路由"
     runme run install-tracing-elasticsearch-spm:patch-otel-collector || {
         log_error "Patch OpenTelemetry Collector 失败"
         return 1
     }
 
-    # 步骤 22: 等待 OpenTelemetry Collector 重启就绪
-    log_info "步骤 22: 等待 OpenTelemetry Collector 重启就绪"
+    # 步骤 23: 等待 OpenTelemetry Collector 重启就绪
+    log_info "步骤 23: 等待 OpenTelemetry Collector 重启就绪"
     runme run install-tracing-elasticsearch-spm:wait-otel-collector-rollout || {
         log_error "等待 OpenTelemetry Collector 重启失败"
         return 1
     }
 
-    # 步骤 23: 生成 jaeger-spm-patch.yaml 到 /tmp
-    log_info "步骤 23: 生成 /tmp/jaeger-spm-patch.yaml"
+    # 步骤 24: 生成 jaeger-spm-patch.yaml 到 /tmp
+    log_info "步骤 24: 生成 /tmp/jaeger-spm-patch.yaml"
     runme print install-tracing-elasticsearch-spm:jaeger-spm-patch-yaml > /tmp/jaeger-spm-patch.yaml || {
         log_error "生成 jaeger-spm-patch.yaml 失败"
         return 1
     }
 
-    # 步骤 24: 应用 SPM patch（需在 /tmp 目录下执行）
-    log_info "步骤 24: 应用 jaeger-spm-patch.yaml"
+    # 步骤 25: 应用 SPM patch（需在 /tmp 目录下执行）
+    log_info "步骤 25: 应用 jaeger-spm-patch.yaml"
     kubectl_apply_runme_block "install-tracing-elasticsearch-spm:apply-jaeger-patch" "/tmp/" || {
         log_error "应用 jaeger-spm-patch.yaml 失败"
         return 1
     }
 
-    # 步骤 25: 等待 Jaeger 重启就绪
-    log_info "步骤 25: 等待 Jaeger 重启就绪"
+    # 步骤 26: 等待 Jaeger 重启就绪
+    log_info "步骤 26: 等待 Jaeger 重启就绪"
     runme run install-tracing-elasticsearch-spm:wait-jaeger-rollout || {
         log_error "等待 Jaeger 重启失败"
         return 1
     }
 
-    # 步骤 26: 重新部署 telemetrygen 验证 SPM 指标（文档 Verification 要求）
-    # --skip-telemetrygen 时跳过：SPM 配置路径已由步骤 19-25 覆盖。
+    # 步骤 27: 重新部署 telemetrygen 验证 SPM 指标（文档 Verification 要求）
+    # --skip-telemetrygen 时跳过：SPM 配置路径已由步骤 20-26 覆盖。
     if [ "${SKIP_TELEMETRYGEN:-false}" = "true" ]; then
-        log_warn "SKIP_TELEMETRYGEN=true，跳过步骤 26 SPM telemetrygen 验证"
+        log_warn "SKIP_TELEMETRYGEN=true，跳过步骤 27 SPM telemetrygen 验证"
     else
-        log_info "步骤 26: 重新部署 telemetrygen 验证 SPM"
+        log_info "步骤 27: 重新部署 telemetrygen 验证 SPM"
         _deploy_telemetrygen "${TRACING_TELEMETRYGEN_TEST_DURATION_2:-130s}" || {
             log_error "SPM telemetrygen 验证失败"
             return 1
@@ -168,8 +170,19 @@ test_installing_distributed_tracing_elasticsearch() {
         log_info "使用手动 Elasticsearch 配置: endpoint=${TRACING_ES_ENDPOINT}"
     fi
 
-    # 步骤 1: 安装 Alauda Build of OpenTelemetry v2 Operator（跨仓库前置依赖）
-    log_info "步骤 1: 安装 OpenTelemetry v2 Operator"
+    # 步骤 1: 安装 Alauda Build of Jaeger v2 集群插件（文档「Installing the Alauda Build
+    # of Jaeger v2 Cluster Plugin > Installing via the CLI」章节。两篇安装文档的该章节
+    # 内容一致，安装逻辑抽象为共享函数、按 runme 前缀参数化，见
+    # docs-runme-tests/projects/tracing/jaeger-plugin.sh；后续 get-platform-config
+    # 从插件创建的 ConfigMap 读取 Jaeger 相关镜像地址）
+    log_info "步骤 1: 安装 Alauda Build of Jaeger v2 集群插件（CLI 方式）"
+    tracing_install_jaeger_plugin "install-tracing-elasticsearch" || {
+        log_error "Jaeger v2 集群插件安装失败"
+        return 1
+    }
+
+    # 步骤 2: 安装 Alauda Build of OpenTelemetry v2 Operator（跨仓库前置依赖）
+    log_info "步骤 2: 安装 OpenTelemetry v2 Operator"
     if [ -z "${OTEL_REPO_ROOT:-}" ]; then
         log_error "OTEL_REPO_ROOT 未注入，无法定位 opentelemetry-docs 安装 OTel Operator"
         return 1
@@ -183,98 +196,98 @@ test_installing_distributed_tracing_elasticsearch() {
         return 1
     }
 
-    # 步骤 2: 注入 Elasticsearch 连接环境变量（替代文档步骤 1 的占位符）
-    log_info "步骤 2: 设置 Elasticsearch 连接环境变量"
+    # 步骤 3: 注入 Elasticsearch 连接环境变量（替代文档步骤 1 的占位符）
+    log_info "步骤 3: 设置 Elasticsearch 连接环境变量"
     export ES_ENDPOINT="$TRACING_ES_ENDPOINT"
     export ES_USER="$TRACING_ES_USER"
     export ES_PASS="$TRACING_ES_PASS"
 
-    # 步骤 3: 拉取平台配置与 Jaeger 镜像
-    log_info "步骤 3: 拉取平台配置"
+    # 步骤 4: 拉取平台配置与 Jaeger 镜像
+    log_info "步骤 4: 拉取平台配置"
     eval "$(runme print install-tracing-elasticsearch:get-platform-config)" || {
         log_error "拉取平台配置失败"
         return 1
     }
 
-    # 步骤 4: 设置 Jaeger 默认环境变量
-    log_info "步骤 4: 设置 Jaeger 默认环境变量"
+    # 步骤 5: 设置 Jaeger 默认环境变量
+    log_info "步骤 5: 设置 Jaeger 默认环境变量"
     eval "$(runme print install-tracing-elasticsearch:set-jaeger-defaults)" || {
         log_error "设置 Jaeger 默认环境变量失败"
         return 1
     }
 
-    # 步骤 5: 创建 Jaeger 命名空间与 ES 凭据 Secret
-    log_info "步骤 5: 创建命名空间与 ES 凭据 Secret"
+    # 步骤 6: 创建 Jaeger 命名空间与 ES 凭据 Secret
+    log_info "步骤 6: 创建命名空间与 ES 凭据 Secret"
     runme run install-tracing-elasticsearch:create-jaeger-ns-and-es-secret || {
         log_error "创建命名空间与 ES Secret 失败"
         return 1
     }
 
-    # 步骤 5.1: 验证 ES Secret
-    log_info "步骤 5.1: 验证 ES Secret"
+    # 步骤 6.1: 验证 ES Secret
+    log_info "步骤 6.1: 验证 ES Secret"
     runme run install-tracing-elasticsearch:verify-es-secret || {
         log_error "验证 ES Secret 失败"
         return 1
     }
 
-    # 步骤 6: 创建 ILM Policy
-    log_info "步骤 6: 创建 ILM Policy"
+    # 步骤 7: 创建 ILM Policy
+    log_info "步骤 7: 创建 ILM Policy"
     runme run install-tracing-elasticsearch:create-ilm-policy || {
         log_error "创建 ILM Policy 失败"
         return 1
     }
 
-    # 步骤 6.1: 验证 ILM Policy
-    log_info "步骤 6.1: 验证 ILM Policy"
+    # 步骤 7.1: 验证 ILM Policy
+    log_info "步骤 7.1: 验证 ILM Policy"
     runme run install-tracing-elasticsearch:verify-ilm-policy || {
         log_error "验证 ILM Policy 失败"
         return 1
     }
 
-    # 步骤 7: 创建 jaeger-es-rollover-init Job
-    log_info "步骤 7: 创建 rollover-init Job"
+    # 步骤 8: 创建 jaeger-es-rollover-init Job
+    log_info "步骤 8: 创建 rollover-init Job"
     runme run install-tracing-elasticsearch:create-rollover-init-job || {
         log_error "创建 rollover-init Job 失败"
         return 1
     }
 
-    # 步骤 7.1: 等待 Job 完成并验证索引模板/别名
-    log_info "步骤 7.1: 等待 rollover-init Job 完成并验证"
+    # 步骤 8.1: 等待 Job 完成并验证索引模板/别名
+    log_info "步骤 8.1: 等待 rollover-init Job 完成并验证"
     runme run install-tracing-elasticsearch:verify-rollover-init || {
         log_error "验证 rollover-init 失败"
         return 1
     }
 
-    # 步骤 8: 清理 rollover-init Job
-    log_info "步骤 8: 清理 rollover-init Job"
+    # 步骤 9: 清理 rollover-init Job
+    log_info "步骤 9: 清理 rollover-init Job"
     runme run install-tracing-elasticsearch:delete-rollover-init-job || {
         log_error "清理 rollover-init Job 失败"
         return 1
     }
 
-    # 步骤 9: 创建 OAuth2 Proxy Secret
-    log_info "步骤 9: 创建 OAuth2 Proxy Secret"
+    # 步骤 10: 创建 OAuth2 Proxy Secret
+    log_info "步骤 10: 创建 OAuth2 Proxy Secret"
     runme run install-tracing-elasticsearch:create-oauth2-proxy-secret || {
         log_error "创建 OAuth2 Proxy Secret 失败"
         return 1
     }
 
-    # 步骤 10: 生成 jaeger.yaml 到 /tmp（envsubst apply 依赖 cwd 中存在该文件）
-    log_info "步骤 10: 生成 /tmp/jaeger.yaml"
+    # 步骤 11: 生成 jaeger.yaml 到 /tmp（envsubst apply 依赖 cwd 中存在该文件）
+    log_info "步骤 11: 生成 /tmp/jaeger.yaml"
     runme print install-tracing-elasticsearch:jaeger-yaml > /tmp/jaeger.yaml || {
         log_error "生成 jaeger.yaml 失败"
         return 1
     }
 
-    # 步骤 11: envsubst 渲染并 apply（需在 /tmp 目录下执行）
-    log_info "步骤 11: 渲染并应用 jaeger.yaml"
+    # 步骤 12: envsubst 渲染并 apply（需在 /tmp 目录下执行）
+    log_info "步骤 12: 渲染并应用 jaeger.yaml"
     kubectl_apply_runme_block "install-tracing-elasticsearch:apply-jaeger" "/tmp/" || {
         log_error "应用 jaeger.yaml 失败"
         return 1
     }
 
-    # 步骤 11.1: 等待 OpenTelemetryCollector 状态副本数收敛
-    log_info "步骤 11.1: 等待 OpenTelemetryCollector status.scale.statusReplicas=1/1"
+    # 步骤 12.1: 等待 OpenTelemetryCollector 状态副本数收敛
+    log_info "步骤 12.1: 等待 OpenTelemetryCollector status.scale.statusReplicas=1/1"
     kubectl wait "opentelemetrycollector/${JAEGER_INSTANCE_NAME}" \
         -n "${JAEGER_NS}" \
         --for=jsonpath='{.status.scale.statusReplicas}'=1/1 \
@@ -283,57 +296,57 @@ test_installing_distributed_tracing_elasticsearch() {
         return 1
     }
 
-    # 步骤 12: 等待 Jaeger collector deployment 就绪
-    log_info "步骤 12: 等待 Jaeger collector 就绪"
+    # 步骤 13: 等待 Jaeger collector deployment 就绪
+    log_info "步骤 13: 等待 Jaeger collector 就绪"
     runme run install-tracing-elasticsearch:wait-jaeger-rollout || {
         log_error "等待 Jaeger collector 就绪失败"
         return 1
     }
 
-    # 步骤 13: 给命名空间打 cpaas.io/project 标签
-    log_info "步骤 13: 标记 Jaeger 命名空间"
+    # 步骤 14: 给命名空间打 cpaas.io/project 标签
+    log_info "步骤 14: 标记 Jaeger 命名空间"
     runme run install-tracing-elasticsearch:label-jaeger-ns || {
         log_error "标记命名空间失败"
         return 1
     }
 
-    # 步骤 14: 创建 Jaeger Ingress
-    log_info "步骤 14: 创建 Jaeger Ingress"
+    # 步骤 15: 创建 Jaeger Ingress
+    log_info "步骤 15: 创建 Jaeger Ingress"
     runme run install-tracing-elasticsearch:create-jaeger-ingress || {
         log_error "创建 Jaeger Ingress 失败"
         return 1
     }
 
-    # 步骤 14.1: 等待 Ingress LoadBalancer 就绪
-    log_info "步骤 14.1: 等待 Jaeger Ingress 就绪"
+    # 步骤 15.1: 等待 Ingress LoadBalancer 就绪
+    log_info "步骤 15.1: 等待 Jaeger Ingress 就绪"
     runme run install-tracing-elasticsearch:wait-jaeger-ingress || {
         log_error "等待 Jaeger Ingress 就绪失败"
         return 1
     }
 
-    # 步骤 15: 打印 Jaeger UI URL
-    log_info "步骤 15: 打印 Jaeger UI URL"
+    # 步骤 16: 打印 Jaeger UI URL
+    log_info "步骤 16: 打印 Jaeger UI URL"
     runme run install-tracing-elasticsearch:print-jaeger-url || {
         log_error "打印 Jaeger UI URL 失败"
         return 1
     }
 
-    # 步骤 16: 生成 otel-collector.yaml 到 /tmp
-    log_info "步骤 16: 生成 /tmp/otel-collector.yaml"
+    # 步骤 17: 生成 otel-collector.yaml 到 /tmp
+    log_info "步骤 17: 生成 /tmp/otel-collector.yaml"
     runme print install-tracing-elasticsearch:otel-collector-yaml > /tmp/otel-collector.yaml || {
         log_error "生成 otel-collector.yaml 失败"
         return 1
     }
 
-    # 步骤 16.1: envsubst 渲染并 apply（需在 /tmp 目录下执行）
-    log_info "步骤 16.1: 渲染并应用 otel-collector.yaml"
+    # 步骤 17.1: envsubst 渲染并 apply（需在 /tmp 目录下执行）
+    log_info "步骤 17.1: 渲染并应用 otel-collector.yaml"
     kubectl_apply_runme_block "install-tracing-elasticsearch:apply-otel-collector" "/tmp/" || {
         log_error "应用 otel-collector.yaml 失败"
         return 1
     }
 
-    # 步骤 16.2: 等待 otel OpenTelemetryCollector 状态副本数收敛
-    log_info "步骤 16.2: 等待 otel OpenTelemetryCollector status.scale.statusReplicas=1/1"
+    # 步骤 17.2: 等待 otel OpenTelemetryCollector 状态副本数收敛
+    log_info "步骤 17.2: 等待 otel OpenTelemetryCollector status.scale.statusReplicas=1/1"
     kubectl wait "opentelemetrycollector/otel" \
         -n "${JAEGER_NS}" \
         --for=jsonpath='{.status.scale.statusReplicas}'=1/1 \
@@ -342,27 +355,27 @@ test_installing_distributed_tracing_elasticsearch() {
         return 1
     }
 
-    # 步骤 17: 等待 otel collector deployment 就绪
-    log_info "步骤 17: 等待 OpenTelemetry Collector 就绪"
+    # 步骤 18: 等待 otel collector deployment 就绪
+    log_info "步骤 18: 等待 OpenTelemetry Collector 就绪"
     runme run install-tracing-elasticsearch:wait-otel-collector-rollout || {
         log_error "等待 OpenTelemetry Collector 就绪失败"
         return 1
     }
 
-    # 步骤 18: 部署 telemetrygen 生成测试 trace（内含 wait/delete）
+    # 步骤 19: 部署 telemetrygen 生成测试 trace（内含 wait/delete）
     # --skip-telemetrygen 时跳过：用于 mesh 等仅需安装调用链组件、由
     # 业务流量产生 trace 而不依赖 telemetrygen 验证的编排场景。
     if [ "${SKIP_TELEMETRYGEN:-false}" = "true" ]; then
-        log_warn "SKIP_TELEMETRYGEN=true，跳过步骤 18 telemetrygen 端到端验证"
+        log_warn "SKIP_TELEMETRYGEN=true，跳过步骤 19 telemetrygen 端到端验证"
     else
-        log_info "步骤 18: 部署 telemetrygen 生成测试 trace"
+        log_info "步骤 19: 部署 telemetrygen 生成测试 trace"
         _deploy_telemetrygen "${TRACING_TELEMETRYGEN_TEST_DURATION_1:-30s}" || {
             log_error "telemetrygen 端到端验证失败"
             return 1
         }
     fi
 
-    # 步骤 19-26:（可选）Service Performance Monitoring (SPM) 章节
+    # 步骤 20-27:（可选）Service Performance Monitoring (SPM) 章节
     # SPM 需 ACP monitoring，默认跳过；设置 TRACING_TEST_SPM=true 启用。
     if [ "${TRACING_TEST_SPM:-true}" = "true" ]; then
         _test_spm || return 1
diff --git a/docs/en/installing/runme-test_installing-distributed-tracing-opensearch.sh b/docs/en/installing/runme-test_installing-distributed-tracing-opensearch.sh
index 7cfecd3..a0a43e5 100755
--- a/docs/en/installing/runme-test_installing-distributed-tracing-opensearch.sh
+++ b/docs/en/installing/runme-test_installing-distributed-tracing-opensearch.sh
@@ -1,7 +1,8 @@
 #!/usr/bin/env bash
 # Alauda Distributed Tracing 安装文档测试脚本（OpenSearch 后端）
 # 对应文档: docs/en/installing/installing-distributed-tracing-opensearch.mdx
-# 覆盖范围: 「Deploying the Alauda Build of Jaeger v2」（含 jaeger-es-index-cleaner）、
+# 覆盖范围: 「Installing the Alauda Build of Jaeger v2 Cluster Plugin」（仅 CLI 安装方案）、
+#           「Deploying the Alauda Build of Jaeger v2」（含 jaeger-es-index-cleaner）、
 #           「Deploying the OpenTelemetry Collector」「Verification」「(Optional) SPM」章节。
 #
 # 与 Elasticsearch 版的差异：
@@ -19,7 +20,8 @@ set -e
 # 加载框架函数库
 source "$FRAMEWORK_ROOT/framework/common.sh"
 source "$FRAMEWORK_ROOT/framework/verify.sh"
-# tracing 项目钩子：提供 telemetrygen 镜像解析公共函数 tracing_telemetrygen_image（与 ES 版共用）。
+# tracing 项目钩子：提供 telemetrygen 镜像解析公共函数 tracing_telemetrygen_image，
+# 以及 Jaeger v2 集群插件共享安装函数 tracing_install_jaeger_plugin（均与 ES 版共用）。
 # run.sh 引擎对 --project tracing 已自动 source 本文件，这里显式声明依赖、便于独立运行与阅读。
 source "$FRAMEWORK_ROOT/projects/tracing/project.sh"
 
@@ -67,61 +69,61 @@ _deploy_telemetrygen() {
 _test_spm() {
     log_header "Service Performance Monitoring (SPM) 测试"
 
-    # 步骤 19: 拉取 monitoring 端点与凭据
-    log_info "步骤 19: 拉取 monitoring 配置"
+    # 步骤 20: 拉取 monitoring 端点与凭据
+    log_info "步骤 20: 拉取 monitoring 配置"
     eval "$(runme print install-tracing-opensearch-spm:get-monitoring-config)" || {
         log_error "拉取 monitoring 配置失败"
         return 1
     }
 
-    # 步骤 20: 创建 monitoring 凭据 Secret
-    log_info "步骤 20: 创建 monitoring 凭据 Secret"
+    # 步骤 21: 创建 monitoring 凭据 Secret
+    log_info "步骤 21: 创建 monitoring 凭据 Secret"
     runme run install-tracing-opensearch-spm:create-monitoring-secret || {
         log_error "创建 monitoring 凭据 Secret 失败"
         return 1
     }
 
-    # 步骤 21: Patch OpenTelemetry Collector 改用 loadbalancing 按 service 路由到 Jaeger（spanmetrics 已移至 Jaeger）
-    log_info "步骤 21: Patch OpenTelemetry Collector 配置 loadbalancing 按 service 路由"
+    # 步骤 22: Patch OpenTelemetry Collector 改用 loadbalancing 按 service 路由到 Jaeger（spanmetrics 已移至 Jaeger）
+    log_info "步骤 22: Patch OpenTelemetry Collector 配置 loadbalancing 按 service 路由"
     runme run install-tracing-opensearch-spm:patch-otel-collector || {
         log_error "Patch OpenTelemetry Collector 失败"
         return 1
     }
 
-    # 步骤 22: 等待 OpenTelemetry Collector 重启就绪
-    log_info "步骤 22: 等待 OpenTelemetry Collector 重启就绪"
+    # 步骤 23: 等待 OpenTelemetry Collector 重启就绪
+    log_info "步骤 23: 等待 OpenTelemetry Collector 重启就绪"
     runme run install-tracing-opensearch-spm:wait-otel-collector-rollout || {
         log_error "等待 OpenTelemetry Collector 重启失败"
         return 1
     }
 
-    # 步骤 23: 生成 jaeger-spm-patch.yaml 到 /tmp
-    log_info "步骤 23: 生成 /tmp/jaeger-spm-patch.yaml"
+    # 步骤 24: 生成 jaeger-spm-patch.yaml 到 /tmp
+    log_info "步骤 24: 生成 /tmp/jaeger-spm-patch.yaml"
     runme print install-tracing-opensearch-spm:jaeger-spm-patch-yaml > /tmp/jaeger-spm-patch.yaml || {
         log_error "生成 jaeger-spm-patch.yaml 失败"
         return 1
     }
 
-    # 步骤 24: 应用 SPM patch（需在 /tmp 目录下执行）
-    log_info "步骤 24: 应用 jaeger-spm-patch.yaml"
+    # 步骤 25: 应用 SPM patch（需在 /tmp 目录下执行）
+    log_info "步骤 25: 应用 jaeger-spm-patch.yaml"
     kubectl_apply_runme_block "install-tracing-opensearch-spm:apply-jaeger-patch" "/tmp/" || {
         log_error "应用 jaeger-spm-patch.yaml 失败"
         return 1
     }
 
-    # 步骤 25: 等待 Jaeger 重启就绪
-    log_info "步骤 25: 等待 Jaeger 重启就绪"
+    # 步骤 26: 等待 Jaeger 重启就绪
+    log_info "步骤 26: 等待 Jaeger 重启就绪"
     runme run install-tracing-opensearch-spm:wait-jaeger-rollout || {
         log_error "等待 Jaeger 重启失败"
         return 1
     }
 
-    # 步骤 26: 重新部署 telemetrygen 验证 SPM 指标（文档 Verification 要求）
-    # --skip-telemetrygen 时跳过：SPM 配置路径已由步骤 19-25 覆盖。
+    # 步骤 27: 重新部署 telemetrygen 验证 SPM 指标（文档 Verification 要求）
+    # --skip-telemetrygen 时跳过：SPM 配置路径已由步骤 20-26 覆盖。
     if [ "${SKIP_TELEMETRYGEN:-false}" = "true" ]; then
-        log_warn "SKIP_TELEMETRYGEN=true，跳过步骤 26 SPM telemetrygen 验证"
+        log_warn "SKIP_TELEMETRYGEN=true，跳过步骤 27 SPM telemetrygen 验证"
     else
-        log_info "步骤 26: 重新部署 telemetrygen 验证 SPM"
+        log_info "步骤 27: 重新部署 telemetrygen 验证 SPM"
         _deploy_telemetrygen "${TRACING_TELEMETRYGEN_TEST_DURATION_2:-130s}" || {
             log_error "SPM telemetrygen 验证失败"
             return 1
@@ -161,8 +163,19 @@ test_installing_distributed_tracing_opensearch() {
         return 0
     fi
 
-    # 步骤 1: 安装 Alauda Build of OpenTelemetry v2 Operator（跨仓库前置依赖）
-    log_info "步骤 1: 安装 OpenTelemetry v2 Operator"
+    # 步骤 1: 安装 Alauda Build of Jaeger v2 集群插件（文档「Installing the Alauda Build
+    # of Jaeger v2 Cluster Plugin > Installing via the CLI」章节。两篇安装文档的该章节
+    # 内容一致，安装逻辑抽象为共享函数、按 runme 前缀参数化，见
+    # docs-runme-tests/projects/tracing/jaeger-plugin.sh；后续 get-platform-config
+    # 从插件创建的 ConfigMap 读取 Jaeger 相关镜像地址）
+    log_info "步骤 1: 安装 Alauda Build of Jaeger v2 集群插件（CLI 方式）"
+    tracing_install_jaeger_plugin "install-tracing-opensearch" || {
+        log_error "Jaeger v2 集群插件安装失败"
+        return 1
+    }
+
+    # 步骤 2: 安装 Alauda Build of OpenTelemetry v2 Operator（跨仓库前置依赖）
+    log_info "步骤 2: 安装 OpenTelemetry v2 Operator"
     if [ -z "${OTEL_REPO_ROOT:-}" ]; then
         log_error "OTEL_REPO_ROOT 未注入，无法定位 opentelemetry-docs 安装 OTel Operator"
         return 1
@@ -176,63 +189,63 @@ test_installing_distributed_tracing_opensearch() {
         return 1
     }
 
-    # 步骤 2: 注入 OpenSearch 连接环境变量（替代文档步骤 1 的占位符）
-    log_info "步骤 2: 设置 OpenSearch 连接环境变量"
+    # 步骤 3: 注入 OpenSearch 连接环境变量（替代文档步骤 1 的占位符）
+    log_info "步骤 3: 设置 OpenSearch 连接环境变量"
     export OPENSEARCH_ENDPOINT="$TRACING_OPENSEARCH_ENDPOINT"
     export OPENSEARCH_USER="$TRACING_OPENSEARCH_USER"
     export OPENSEARCH_PASS="$TRACING_OPENSEARCH_PASS"
 
-    # 步骤 3: 拉取平台配置与 Jaeger 镜像
-    log_info "步骤 3: 拉取平台配置"
+    # 步骤 4: 拉取平台配置与 Jaeger 镜像
+    log_info "步骤 4: 拉取平台配置"
     eval "$(runme print install-tracing-opensearch:get-platform-config)" || {
         log_error "拉取平台配置失败"
         return 1
     }
 
-    # 步骤 4: 设置 Jaeger 默认环境变量
-    log_info "步骤 4: 设置 Jaeger 默认环境变量"
+    # 步骤 5: 设置 Jaeger 默认环境变量
+    log_info "步骤 5: 设置 Jaeger 默认环境变量"
     eval "$(runme print install-tracing-opensearch:set-jaeger-defaults)" || {
         log_error "设置 Jaeger 默认环境变量失败"
         return 1
     }
 
-    # 步骤 5: 创建 Jaeger 命名空间与 OpenSearch 凭据 Secret
-    log_info "步骤 5: 创建命名空间与 OpenSearch 凭据 Secret"
+    # 步骤 6: 创建 Jaeger 命名空间与 OpenSearch 凭据 Secret
+    log_info "步骤 6: 创建命名空间与 OpenSearch 凭据 Secret"
     runme run install-tracing-opensearch:create-jaeger-ns-and-opensearch-secret || {
         log_error "创建命名空间与 OpenSearch Secret 失败"
         return 1
     }
 
-    # 步骤 5.1: 验证 OpenSearch Secret
-    log_info "步骤 5.1: 验证 OpenSearch Secret"
+    # 步骤 6.1: 验证 OpenSearch Secret
+    log_info "步骤 6.1: 验证 OpenSearch Secret"
     runme run install-tracing-opensearch:verify-opensearch-secret || {
         log_error "验证 OpenSearch Secret 失败"
         return 1
     }
 
-    # 步骤 6: 创建 OAuth2 Proxy Secret
-    log_info "步骤 6: 创建 OAuth2 Proxy Secret"
+    # 步骤 7: 创建 OAuth2 Proxy Secret
+    log_info "步骤 7: 创建 OAuth2 Proxy Secret"
     runme run install-tracing-opensearch:create-oauth2-proxy-secret || {
         log_error "创建 OAuth2 Proxy Secret 失败"
         return 1
     }
 
-    # 步骤 7: 生成 jaeger.yaml 到 /tmp（envsubst apply 依赖 cwd 中存在该文件）
-    log_info "步骤 7: 生成 /tmp/jaeger.yaml"
+    # 步骤 8: 生成 jaeger.yaml 到 /tmp（envsubst apply 依赖 cwd 中存在该文件）
+    log_info "步骤 8: 生成 /tmp/jaeger.yaml"
     runme print install-tracing-opensearch:jaeger-yaml > /tmp/jaeger.yaml || {
         log_error "生成 jaeger.yaml 失败"
         return 1
     }
 
-    # 步骤 8: envsubst 渲染并 apply（需在 /tmp 目录下执行）
-    log_info "步骤 8: 渲染并应用 jaeger.yaml"
+    # 步骤 9: envsubst 渲染并 apply（需在 /tmp 目录下执行）
+    log_info "步骤 9: 渲染并应用 jaeger.yaml"
     kubectl_apply_runme_block "install-tracing-opensearch:apply-jaeger" "/tmp/" || {
         log_error "应用 jaeger.yaml 失败"
         return 1
     }
 
-    # 步骤 8.1: 等待 OpenTelemetryCollector 状态副本数收敛
-    log_info "步骤 8.1: 等待 OpenTelemetryCollector status.scale.statusReplicas=1/1"
+    # 步骤 9.1: 等待 OpenTelemetryCollector 状态副本数收敛
+    log_info "步骤 9.1: 等待 OpenTelemetryCollector status.scale.statusReplicas=1/1"
     kubectl wait "opentelemetrycollector/${JAEGER_INSTANCE_NAME}" \
         -n "${JAEGER_NS}" \
         --for=jsonpath='{.status.scale.statusReplicas}'=1/1 \
@@ -241,78 +254,78 @@ test_installing_distributed_tracing_opensearch() {
         return 1
     }
 
-    # 步骤 9: 等待 Jaeger collector deployment 就绪
-    log_info "步骤 9: 等待 Jaeger collector 就绪"
+    # 步骤 10: 等待 Jaeger collector deployment 就绪
+    log_info "步骤 10: 等待 Jaeger collector 就绪"
     runme run install-tracing-opensearch:wait-jaeger-rollout || {
         log_error "等待 Jaeger collector 就绪失败"
         return 1
     }
 
-    # 步骤 10: 设置 jaeger-es-index-cleaner 环境变量
-    log_info "步骤 10: 设置 index-cleaner 环境变量"
+    # 步骤 11: 设置 jaeger-es-index-cleaner 环境变量
+    log_info "步骤 11: 设置 index-cleaner 环境变量"
     eval "$(runme print install-tracing-opensearch:set-index-cleaner-defaults)" || {
         log_error "设置 index-cleaner 环境变量失败"
         return 1
     }
 
-    # 步骤 11: 生成 jaeger-index-cleaner.yaml 到 /tmp
-    log_info "步骤 11: 生成 /tmp/jaeger-index-cleaner.yaml"
+    # 步骤 12: 生成 jaeger-index-cleaner.yaml 到 /tmp
+    log_info "步骤 12: 生成 /tmp/jaeger-index-cleaner.yaml"
     runme print install-tracing-opensearch:index-cleaner-yaml > /tmp/jaeger-index-cleaner.yaml || {
         log_error "生成 jaeger-index-cleaner.yaml 失败"
         return 1
     }
 
-    # 步骤 12: 渲染并部署 index-cleaner CronJob（需在 /tmp 目录下执行）
-    log_info "步骤 12: 部署 jaeger-es-index-cleaner CronJob"
+    # 步骤 13: 渲染并部署 index-cleaner CronJob（需在 /tmp 目录下执行）
+    log_info "步骤 13: 部署 jaeger-es-index-cleaner CronJob"
     kubectl_apply_runme_block "install-tracing-opensearch:apply-index-cleaner" "/tmp/" || {
         log_error "部署 jaeger-es-index-cleaner CronJob 失败"
         return 1
     }
 
-    # 步骤 13: 给命名空间打 cpaas.io/project 标签
-    log_info "步骤 13: 标记 Jaeger 命名空间"
+    # 步骤 14: 给命名空间打 cpaas.io/project 标签
+    log_info "步骤 14: 标记 Jaeger 命名空间"
     runme run install-tracing-opensearch:label-jaeger-ns || {
         log_error "标记命名空间失败"
         return 1
     }
 
-    # 步骤 14: 创建 Jaeger Ingress
-    log_info "步骤 14: 创建 Jaeger Ingress"
+    # 步骤 15: 创建 Jaeger Ingress
+    log_info "步骤 15: 创建 Jaeger Ingress"
     runme run install-tracing-opensearch:create-jaeger-ingress || {
         log_error "创建 Jaeger Ingress 失败"
         return 1
     }
 
-    # 步骤 14.1: 等待 Ingress LoadBalancer 就绪
-    log_info "步骤 14.1: 等待 Jaeger Ingress 就绪"
+    # 步骤 15.1: 等待 Ingress LoadBalancer 就绪
+    log_info "步骤 15.1: 等待 Jaeger Ingress 就绪"
     runme run install-tracing-opensearch:wait-jaeger-ingress || {
         log_error "等待 Jaeger Ingress 就绪失败"
         return 1
     }
 
-    # 步骤 15: 打印 Jaeger UI URL
-    log_info "步骤 15: 打印 Jaeger UI URL"
+    # 步骤 16: 打印 Jaeger UI URL
+    log_info "步骤 16: 打印 Jaeger UI URL"
     runme run install-tracing-opensearch:print-jaeger-url || {
         log_error "打印 Jaeger UI URL 失败"
         return 1
     }
 
-    # 步骤 16: 生成 otel-collector.yaml 到 /tmp
-    log_info "步骤 16: 生成 /tmp/otel-collector.yaml"
+    # 步骤 17: 生成 otel-collector.yaml 到 /tmp
+    log_info "步骤 17: 生成 /tmp/otel-collector.yaml"
     runme print install-tracing-opensearch:otel-collector-yaml > /tmp/otel-collector.yaml || {
         log_error "生成 otel-collector.yaml 失败"
         return 1
     }
 
-    # 步骤 16.1: envsubst 渲染并 apply（需在 /tmp 目录下执行）
-    log_info "步骤 16.1: 渲染并应用 otel-collector.yaml"
+    # 步骤 17.1: envsubst 渲染并 apply（需在 /tmp 目录下执行）
+    log_info "步骤 17.1: 渲染并应用 otel-collector.yaml"
     kubectl_apply_runme_block "install-tracing-opensearch:apply-otel-collector" "/tmp/" || {
         log_error "应用 otel-collector.yaml 失败"
         return 1
     }
 
-    # 步骤 16.2: 等待 otel OpenTelemetryCollector 状态副本数收敛
-    log_info "步骤 16.2: 等待 otel OpenTelemetryCollector status.scale.statusReplicas=1/1"
+    # 步骤 17.2: 等待 otel OpenTelemetryCollector 状态副本数收敛
+    log_info "步骤 17.2: 等待 otel OpenTelemetryCollector status.scale.statusReplicas=1/1"
     kubectl wait "opentelemetrycollector/otel" \
         -n "${JAEGER_NS}" \
         --for=jsonpath='{.status.scale.statusReplicas}'=1/1 \
@@ -321,27 +334,27 @@ test_installing_distributed_tracing_opensearch() {
         return 1
     }
 
-    # 步骤 17: 等待 otel collector deployment 就绪
-    log_info "步骤 17: 等待 OpenTelemetry Collector 就绪"
+    # 步骤 18: 等待 otel collector deployment 就绪
+    log_info "步骤 18: 等待 OpenTelemetry Collector 就绪"
     runme run install-tracing-opensearch:wait-otel-collector-rollout || {
         log_error "等待 OpenTelemetry Collector 就绪失败"
         return 1
     }
 
-    # 步骤 18: 部署 telemetrygen 生成测试 trace（内含 wait/delete）
+    # 步骤 19: 部署 telemetrygen 生成测试 trace（内含 wait/delete）
     # --skip-telemetrygen 时跳过：用于 mesh 等仅需安装调用链组件、由
     # 业务流量产生 trace 而不依赖 telemetrygen 验证的编排场景。
     if [ "${SKIP_TELEMETRYGEN:-false}" = "true" ]; then
-        log_warn "SKIP_TELEMETRYGEN=true，跳过步骤 18 telemetrygen 端到端验证"
+        log_warn "SKIP_TELEMETRYGEN=true，跳过步骤 19 telemetrygen 端到端验证"
     else
-        log_info "步骤 18: 部署 telemetrygen 生成测试 trace"
+        log_info "步骤 19: 部署 telemetrygen 生成测试 trace"
         _deploy_telemetrygen "${TRACING_TELEMETRYGEN_TEST_DURATION_1:-30s}" || {
             log_error "telemetrygen 端到端验证失败"
             return 1
         }
     fi
 
-    # 步骤 19-26:（可选）Service Performance Monitoring (SPM) 章节
+    # 步骤 20-27:（可选）Service Performance Monitoring (SPM) 章节
     # SPM 需 ACP monitoring，默认跳过；设置 TRACING_TEST_SPM=true 启用。
     if [ "${TRACING_TEST_SPM:-true}" = "true" ]; then
         _test_spm || return 1

From 11e8b0be338d9ef4e9ef387e32b0993e62451298 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E7=8E=8B=E7=84=B6?= <ranwang@alauda.io>
Date: Wed, 5 Aug 2026 10:28:58 +0000
Subject: [PATCH 3/8] feat: upgrade add_metric_suffixes config to
 translation_strategy
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Signed-off-by: 王然 <ranwang@alauda.io>
---
 docs/en/configuration/spm.mdx                               | 6 +++++-
 .../installing-distributed-tracing-elasticsearch.mdx        | 2 +-
 .../installing-distributed-tracing-opensearch.mdx           | 2 +-
 3 files changed, 7 insertions(+), 3 deletions(-)

diff --git a/docs/en/configuration/spm.mdx b/docs/en/configuration/spm.mdx
index 882ae2b..12ef4d6 100644
--- a/docs/en/configuration/spm.mdx
+++ b/docs/en/configuration/spm.mdx
@@ -87,7 +87,7 @@ service:
 ```yaml
 exporters:
   prometheus:
-    add_metric_suffixes: false # Jaeger expects standard OTel metric names without _total suffixes
+    translation_strategy: UnderscoreEscapingWithoutSuffixes # keep OTel metric names without _total suffixes (add_metric_suffixes is deprecated and ignored since Jaeger v2.20.0 / collector-contrib v0.154.0)
     endpoint: "0.0.0.0:8889"
     resource_to_telemetry_conversion:
       enabled: true
@@ -105,6 +105,10 @@ service:
       exporters: [prometheus]
 ```
 
+:::note
+The exporter and the Jaeger metrics reader must agree on metric names. By default Jaeger queries suffix-less names such as `traces_span_metrics_calls` (the `normalize_calls` and `normalize_duration` options of the `prometheus` metric backend default to `false`), so the exporter must not append Prometheus-style suffixes. Set `translation_strategy: UnderscoreEscapingWithoutSuffixes` explicitly for this: the older `add_metric_suffixes: false` option is deprecated and silently ignored since Jaeger v2.20.0 (collector-contrib v0.154.0), which would rename the metrics to `traces_span_metrics_calls_total` and break the Monitor tab.
+:::
+
 Define a remote PromQL-compatible storage in Jaeger:
 
 ```yaml
diff --git a/docs/en/installing/installing-distributed-tracing-elasticsearch.mdx b/docs/en/installing/installing-distributed-tracing-elasticsearch.mdx
index 192eb74..8772d27 100644
--- a/docs/en/installing/installing-distributed-tracing-elasticsearch.mdx
+++ b/docs/en/installing/installing-distributed-tracing-elasticsearch.mdx
@@ -795,7 +795,7 @@ Enabling SPM requires running the SpanMetrics Connector **inside Jaeger** to gen
           spanmetrics: {} # [!code callout]
         exporters:
           prometheus: # [!code callout]
-            add_metric_suffixes: false # Jaeger expects standard OTel metric names without _total suffixes
+            translation_strategy: UnderscoreEscapingWithoutSuffixes # keep OTel metric names without _total suffixes (add_metric_suffixes is deprecated and ignored since Jaeger v2.20.0 / collector-contrib v0.154.0)
             endpoint: "0.0.0.0:8889"
             resource_to_telemetry_conversion:
               enabled: true
diff --git a/docs/en/installing/installing-distributed-tracing-opensearch.mdx b/docs/en/installing/installing-distributed-tracing-opensearch.mdx
index 5d49b38..62f775f 100644
--- a/docs/en/installing/installing-distributed-tracing-opensearch.mdx
+++ b/docs/en/installing/installing-distributed-tracing-opensearch.mdx
@@ -784,7 +784,7 @@ Enabling SPM requires running the SpanMetrics Connector **inside Jaeger** to gen
           spanmetrics: {} # [!code callout]
         exporters:
           prometheus: # [!code callout]
-            add_metric_suffixes: false # Jaeger expects standard OTel metric names without _total suffixes
+            translation_strategy: UnderscoreEscapingWithoutSuffixes # keep OTel metric names without _total suffixes (add_metric_suffixes is deprecated and ignored since Jaeger v2.20.0 / collector-contrib v0.154.0)
             endpoint: "0.0.0.0:8889"
             resource_to_telemetry_conversion:
               enabled: true

From 1ba2d2da1a8acb86edb8eaef317f031092def4f5 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E7=8E=8B=E7=84=B6?= <ranwang@alauda.io>
Date: Wed, 5 Aug 2026 10:56:08 +0000
Subject: [PATCH 4/8] feat: upgrade add_metric_suffixes config to
 translation_strategy
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Signed-off-by: 王然 <ranwang@alauda.io>
---
 .../installing/installing-distributed-tracing-elasticsearch.mdx | 2 +-
 .../en/installing/installing-distributed-tracing-opensearch.mdx | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/docs/en/installing/installing-distributed-tracing-elasticsearch.mdx b/docs/en/installing/installing-distributed-tracing-elasticsearch.mdx
index 8772d27..0636379 100644
--- a/docs/en/installing/installing-distributed-tracing-elasticsearch.mdx
+++ b/docs/en/installing/installing-distributed-tracing-elasticsearch.mdx
@@ -593,7 +593,7 @@ After Jaeger v2 is running, deploy an OpenTelemetry Collector instance to receiv
             tls:
               insecure: true
           prometheus:
-            add_metric_suffixes: false
+            translation_strategy: UnderscoreEscapingWithoutSuffixes # keep OTel metric names without _total suffixes (add_metric_suffixes is deprecated and ignored since collector-contrib v0.154.0)
             endpoint: "0.0.0.0:8889"
             resource_to_telemetry_conversion:
               enabled: true # by default resource attributes are dropped
diff --git a/docs/en/installing/installing-distributed-tracing-opensearch.mdx b/docs/en/installing/installing-distributed-tracing-opensearch.mdx
index 62f775f..8dab869 100644
--- a/docs/en/installing/installing-distributed-tracing-opensearch.mdx
+++ b/docs/en/installing/installing-distributed-tracing-opensearch.mdx
@@ -582,7 +582,7 @@ After Jaeger v2 is running, deploy an OpenTelemetry Collector instance to receiv
             tls:
               insecure: true
           prometheus:
-            add_metric_suffixes: false
+            translation_strategy: UnderscoreEscapingWithoutSuffixes # keep OTel metric names without _total suffixes (add_metric_suffixes is deprecated and ignored since collector-contrib v0.154.0)
             endpoint: "0.0.0.0:8889"
             resource_to_telemetry_conversion:
               enabled: true # by default resource attributes are dropped

From 4f319e8b54eb8bdf80a152e1842cd3b119363b0b Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E7=8E=8B=E7=84=B6?= <ranwang@alauda.io>
Date: Thu, 6 Aug 2026 03:23:04 +0000
Subject: [PATCH 5/8] feat: migrate to new rotation config
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Signed-off-by: 王然 <ranwang@alauda.io>
---
 .../storage-backends/elasticsearch.mdx        | 44 +++++++++++++++++--
 ...ling-distributed-tracing-elasticsearch.mdx | 19 +++++---
 2 files changed, 54 insertions(+), 9 deletions(-)

diff --git a/docs/en/configuration/storage-backends/elasticsearch.mdx b/docs/en/configuration/storage-backends/elasticsearch.mdx
index 2f039f2..d5ea036 100644
--- a/docs/en/configuration/storage-backends/elasticsearch.mdx
+++ b/docs/en/configuration/storage-backends/elasticsearch.mdx
@@ -24,7 +24,11 @@ Shards and replicas are some configuration values to take special attention to,
 
 ## Index Rollover \{#index-rollover}
 
-[Elasticsearch rollover](https://www.elastic.co/guide/en/elasticsearch/reference/master/indices-rollover-index.html) is an index management strategy that optimizes use of resources allocated to indices. For example, indices that do not contain any data still allocate shards, and conversely, a single index might contain significantly more data than the others. Rollover feature can be enabled by `use_aliases: true` config property.
+[Elasticsearch rollover](https://www.elastic.co/guide/en/elasticsearch/reference/master/indices-rollover-index.html) is an index management strategy that optimizes use of resources allocated to indices. For example, indices that do not contain any data still allocate shards, and conversely, a single index might contain significantly more data than the others. Rollover feature can be enabled by configuring an alias-based rotation strategy (`rotation.manual_rollover` or `rotation.auto_rollover`) under `indices.<type>` for each index type.
+
+:::warning
+The legacy rotation flags (`use_aliases`, `use_ilm`, `span_read_alias`, `span_write_alias`, `service_read_alias`, `service_write_alias`) are rejected since Jaeger v2.20.0 and cause the collector to fail at startup. Migrate to the `indices.<type>.rotation` configuration described below.
+:::
 
 Rollover lets you configure when to roll over to a new index based on one or more of the following criteria:
 
@@ -46,7 +50,23 @@ nerdctl run -it --rm --net=host \
 
 If you need to initialize archive storage, add `-e ARCHIVE=true`.
 
-After the initialization Jaeger can be deployed with `use_aliases: true`.
+After the initialization Jaeger can be deployed with the `manual_rollover` rotation strategy on each index type. The default read/write alias names match the aliases created by the initialization:
+
+```yaml
+indices:
+  spans:
+    rotation:
+      manual_rollover: {}
+  services:
+    rotation:
+      manual_rollover: {}
+  dependencies:
+    rotation:
+      manual_rollover: {}
+  sampling:
+    rotation:
+      manual_rollover: {}
+```
 
 ### ILM support \{#ilm-support}
 
@@ -113,4 +133,22 @@ For example:
     "ILM policy jaeger-ilm-policy doesn't exist in Elasticsearch. Please create it and rerun init"
     :::
 
-After the initialization, deploy Jaeger with `use_ilm: true` and `use_aliases: true`.
+After the initialization, deploy Jaeger with the `auto_rollover` rotation strategy on each index type. Rollover and retention are then managed automatically by the ILM policy, and no external cron jobs are required:
+
+```yaml
+indices:
+  spans:
+    rotation:
+      auto_rollover: {}
+  services:
+    rotation:
+      auto_rollover: {}
+  dependencies:
+    rotation:
+      auto_rollover: {}
+  sampling:
+    rotation:
+      auto_rollover: {}
+```
+
+When `create_mappings: false` is set (index templates are created by the `es-rollover` init job), leave `rotation.auto_rollover.policy_name` empty; the ILM policy reference is already embedded in the index templates by the initialization.
diff --git a/docs/en/installing/installing-distributed-tracing-elasticsearch.mdx b/docs/en/installing/installing-distributed-tracing-elasticsearch.mdx
index 0636379..d1f44b7 100644
--- a/docs/en/installing/installing-distributed-tracing-elasticsearch.mdx
+++ b/docs/en/installing/installing-distributed-tracing-elasticsearch.mdx
@@ -381,8 +381,6 @@ Jaeger v2 is deployed as an `OpenTelemetryCollector` custom resource managed by
                       password_file: /etc/jaeger/es-credentials/pass
                   tls:
                     insecure_skip_verify: true
-                  use_aliases: true
-                  use_ilm: true
                   service_cache_ttl: 12h # [!code callout]
                   create_mappings: false # [!code callout]
                   indices:
@@ -390,15 +388,23 @@ Jaeger v2 is deployed as an `OpenTelemetryCollector` custom resource managed by
                     spans:
                       shards: 5
                       replicas: 1
+                      rotation: # [!code callout]
+                        auto_rollover: {}
                     services:
                       shards: 5
                       replicas: 1
+                      rotation:
+                        auto_rollover: {}
                     dependencies:
                       shards: 5
                       replicas: 1
+                      rotation:
+                        auto_rollover: {}
                     sampling:
                       shards: 5
                       replicas: 1
+                      rotation:
+                        auto_rollover: {}
 
           jaeger_query: # [!code callout]
             storage:
@@ -478,11 +484,12 @@ Jaeger v2 is deployed as an `OpenTelemetryCollector` custom resource managed by
       4. Resource requests and limits for the Jaeger container. Adjust based on your expected trace volume; higher throughput environments may require more CPU and memory.
       5. The `jaeger_storage` extension configures the [Elasticsearch backend](../configuration/storage-backends/elasticsearch.mdx#configuration) for storing trace data.
       6. `service_cache_ttl` controls how long the service name cache is kept. The default is `12h`. If the ILM hot-to-delete interval is short, reduce this value to ensure the Jaeger UI can discover services promptly.
-      7. `create_mappings` must be set to `false` when using ILM mode, because index mappings are managed by the rollover initialization.
+      7. `create_mappings` must be set to `false` when using the `auto_rollover` rotation strategy, because index templates and mappings are managed by the rollover initialization.
       8. `index_prefix` must match the prefix used during the `jaeger-es-rollover` initialization in step 6. For more details on shards and replicas tuning, see [Shards and Replicas](../configuration/storage-backends/elasticsearch.mdx#shards-and-replicas).
-      9. The `jaeger_query` extension serves the Jaeger Query API and the Jaeger UI.
-      10. The `additionalContainers` section defines the OAuth2 Proxy sidecar, which handles authentication for the Jaeger UI by integrating with the Alauda Container Platform Dex identity provider.
-      11. Resource requests and limits for the OAuth2 Proxy sidecar. This container has low resource requirements since it only proxies authentication requests.
+      9. The `rotation.auto_rollover` strategy uses read/write aliases and relies on the ILM policy (created in step 5) to trigger index rollover automatically. The default alias names match those created by the `jaeger-es-rollover` initialization in step 6. It replaces the legacy `use_aliases`/`use_ilm` flags, which are rejected since Jaeger v2.20.0.
+      10. The `jaeger_query` extension serves the Jaeger Query API and the Jaeger UI.
+      11. The `additionalContainers` section defines the OAuth2 Proxy sidecar, which handles authentication for the Jaeger UI by integrating with the Alauda Container Platform Dex identity provider.
+      12. Resource requests and limits for the OAuth2 Proxy sidecar. This container has low resource requirements since it only proxies authentication requests.
     </Callouts>
 
 10. Render the manifest with `envsubst` and apply the configuration:

From 2986ff6e5bc43034652aa091e2aaad2014886bc3 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E7=8E=8B=E7=84=B6?= <ranwang@alauda.io>
Date: Thu, 6 Aug 2026 03:32:27 +0000
Subject: [PATCH 6/8] feat: Replacing Jaeger version: v2.16.0 -
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Signed-off-by: 王然 <ranwang@alauda.io>
---
 docs/en/architecture.mdx                               | 10 +++++-----
 .../configuration/storage-backends/elasticsearch.mdx   |  2 +-
 docs/en/configuration/storage-backends/opensearch.mdx  |  2 +-
 v2.20.0                                                |  0
 4 files changed, 7 insertions(+), 7 deletions(-)
 create mode 100644 v2.20.0

diff --git a/docs/en/architecture.mdx b/docs/en/architecture.mdx
index 0710514..ccb7e52 100644
--- a/docs/en/architecture.mdx
+++ b/docs/en/architecture.mdx
@@ -65,11 +65,11 @@ The Jaeger binary is build on top of the OpenTelemetry Collector framework and i
 
 ### Jaeger Components
 
-* [Jaeger Storage Extension](https://github.com/alauda-mesh/jaeger/tree/v2.16.0/cmd/jaeger/internal/extension/jaegerstorage) - Extensible hub for storage backends supported in Jaeger. It provides all other Jaeger components access to Jaeger storage implementations.
-* [Jaeger Storage Exporter](https://github.com/alauda-mesh/jaeger/tree/v2.16.0/cmd/jaeger/internal/extension/jaegerstorage) - Writes spans to storage backend configured in the Jaeger Storage Extension.
-* [Jaeger Query Extension](https://github.com/alauda-mesh/jaeger/tree/v2.16.0/cmd/jaeger/internal/extension/jaegerquery) - Run the query APIs and the Jaeger UI.
-* [Adaptive Sampling Processor](https://github.com/alauda-mesh/jaeger/tree/v2.16.0/cmd/jaeger/internal/processors/adaptivesampling) - Performs probabilities calculations for adaptive sampling.
-* [Remote Sampling Extension](https://github.com/alauda-mesh/jaeger/tree/v2.16.0/cmd/jaeger/internal/extension/remotesampling) - Serves the endpoints for Remote Sampling, based on static configuration file or adaptive sampling.
+* [Jaeger Storage Extension](https://github.com/alauda-mesh/jaeger/tree/v2.20.0/cmd/jaeger/internal/extension/jaegerstorage) - Extensible hub for storage backends supported in Jaeger. It provides all other Jaeger components access to Jaeger storage implementations.
+* [Jaeger Storage Exporter](https://github.com/alauda-mesh/jaeger/tree/v2.20.0/cmd/jaeger/internal/extension/jaegerstorage) - Writes spans to storage backend configured in the Jaeger Storage Extension.
+* [Jaeger Query Extension](https://github.com/alauda-mesh/jaeger/tree/v2.20.0/cmd/jaeger/internal/extension/jaegerquery) - Run the query APIs and the Jaeger UI.
+* [Adaptive Sampling Processor](https://github.com/alauda-mesh/jaeger/tree/v2.20.0/cmd/jaeger/internal/processors/adaptivesampling) - Performs probabilities calculations for adaptive sampling.
+* [Remote Sampling Extension](https://github.com/alauda-mesh/jaeger/tree/v2.20.0/cmd/jaeger/internal/extension/remotesampling) - Serves the endpoints for Remote Sampling, based on static configuration file or adaptive sampling.
 
 ### OpenTelemetry Components
 
diff --git a/docs/en/configuration/storage-backends/elasticsearch.mdx b/docs/en/configuration/storage-backends/elasticsearch.mdx
index d5ea036..cc62ddd 100644
--- a/docs/en/configuration/storage-backends/elasticsearch.mdx
+++ b/docs/en/configuration/storage-backends/elasticsearch.mdx
@@ -16,7 +16,7 @@ Elasticsearch does not require initialization other than installing and running
 
 ## Configuration \{#configuration}
 
-A sample configuration for Jaeger with Elasticsearch backend is available in the Jaeger repository: [config-elasticsearch.yaml](https://github.com/alauda-mesh/jaeger/tree/v2.16.0/cmd/jaeger/config-elasticsearch.yaml). In the future the configuration documentation will be auto-generated from the schema. Meanwhile, please refer to [config.go](https://github.com/alauda-mesh/jaeger/tree/v2.16.0/internal/storage/elasticsearch/config/config.go) as the authoritative source.
+A sample configuration for Jaeger with Elasticsearch backend is available in the Jaeger repository: [config-elasticsearch.yaml](https://github.com/alauda-mesh/jaeger/tree/v2.20.0/cmd/jaeger/config-elasticsearch.yaml). In the future the configuration documentation will be auto-generated from the schema. Meanwhile, please refer to [config.go](https://github.com/alauda-mesh/jaeger/tree/v2.20.0/internal/storage/elasticsearch/config/config.go) as the authoritative source.
 
 ### Shards and Replicas \{#shards-and-replicas}
 
diff --git a/docs/en/configuration/storage-backends/opensearch.mdx b/docs/en/configuration/storage-backends/opensearch.mdx
index a925a91..2d99f22 100644
--- a/docs/en/configuration/storage-backends/opensearch.mdx
+++ b/docs/en/configuration/storage-backends/opensearch.mdx
@@ -18,7 +18,7 @@ Jaeger uses the same storage implementation for OpenSearch as for [Elasticsearch
 
 ## Configuration \{#configuration}
 
-A sample configuration for Jaeger with the OpenSearch backend is available in the Jaeger repository: [config-opensearch.yaml](https://github.com/alauda-mesh/jaeger/tree/v2.16.0/cmd/jaeger/config-opensearch.yaml). Because OpenSearch shares the Elasticsearch implementation, please refer to [config.go](https://github.com/alauda-mesh/jaeger/tree/v2.16.0/internal/storage/elasticsearch/config/config.go) as the authoritative source for the available options.
+A sample configuration for Jaeger with the OpenSearch backend is available in the Jaeger repository: [config-opensearch.yaml](https://github.com/alauda-mesh/jaeger/tree/v2.20.0/cmd/jaeger/config-opensearch.yaml). Because OpenSearch shares the Elasticsearch implementation, please refer to [config.go](https://github.com/alauda-mesh/jaeger/tree/v2.20.0/internal/storage/elasticsearch/config/config.go) as the authoritative source for the available options.
 
 ### Shards and Replicas \{#shards-and-replicas}
 
diff --git a/v2.20.0 b/v2.20.0
new file mode 100644
index 0000000..e69de29

From d7381d34d320f9f6e975ffbd0ff166052487a514 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E7=8E=8B=E7=84=B6?= <ranwang@alauda.io>
Date: Thu, 6 Aug 2026 06:29:12 +0000
Subject: [PATCH 7/8] perf:
 docs/en/configuration/storage-backends/elasticsearch.mdx for jaeger v2.20.0
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Signed-off-by: 王然 <ranwang@alauda.io>
---
 .../storage-backends/elasticsearch.mdx        | 58 ++++++++++++-------
 v2.20.0                                       |  0
 2 files changed, 38 insertions(+), 20 deletions(-)
 delete mode 100644 v2.20.0

diff --git a/docs/en/configuration/storage-backends/elasticsearch.mdx b/docs/en/configuration/storage-backends/elasticsearch.mdx
index cc62ddd..e05af0c 100644
--- a/docs/en/configuration/storage-backends/elasticsearch.mdx
+++ b/docs/en/configuration/storage-backends/elasticsearch.mdx
@@ -22,9 +22,31 @@ A sample configuration for Jaeger with Elasticsearch backend is available in the
 
 Shards and replicas are some configuration values to take special attention to, because this is decided upon index creation. [This article](https://www.elastic.co/blog/how-many-shards-should-i-have-in-my-elasticsearch-cluster) goes into more information about choosing how many shards should be chosen for optimization.
 
+## Index Management Strategies \{#index-management-strategies}
+
+Jaeger supports three index management strategies, selected with the `rotation` configuration under `indices.<type>` (for each of `spans`, `services`, `dependencies`, and `sampling`). At most one strategy can be set per index type; when no `rotation` is configured, time-based indices are used.
+
+| | **Time-based indices** (default) | **Manual rollover** | **Rollover with ILM** (recommended) |
+|---|----------------------------------|---------------------|-------------------------------------|
+| Rotation strategy | `rotation.periodic` | `rotation.manual_rollover` | `rotation.auto_rollover` |
+| How indices are created | Jaeger creates daily or hourly indices (e.g., `jaeger-span-2024-06-18`) | `jaeger-es-rollover init` creates the first numbered index (e.g., `jaeger-span-000001`); a cron job creates subsequent ones | `jaeger-es-rollover init` creates the first index; Elasticsearch creates subsequent ones |
+| Rollover trigger | Automatic (new time period) | `jaeger-es-rollover rollover` cron job | Elasticsearch ILM policy |
+| Retention cleanup | `jaeger-es-index-cleaner` cron job | `jaeger-es-rollover lookback` (optional) + `jaeger-es-index-cleaner` cron jobs | Elasticsearch ILM policy |
+| External tooling required | None | `jaeger-es-rollover init` (one-time) + cron jobs | `jaeger-es-rollover init` (one-time) + ILM policy |
+
+The relevant configuration fields under `indices.<type>.rotation` are:
+
+| Field | Strategy | Default | Description |
+|-------|----------|---------|-------------|
+| `periodic.date_layout` | Time-based | `2006-01-02` | Go time format for the index date suffix; controls index granularity (`2006-01-02-15` for hourly indices) |
+| `periodic.rollover_frequency` | Time-based | `day` | Granularity used to compute which indices to scan during reads (`day` or `hour`); must match `date_layout` |
+| `manual_rollover.read_alias` / `manual_rollover.write_alias` | Manual rollover | `<index-name>-read` / `<index-name>-write` | Read/write alias names (e.g., `jaeger-span-read`); the defaults match the aliases created by `jaeger-es-rollover init` |
+| `auto_rollover.read_alias` / `auto_rollover.write_alias` | ILM | `<index-name>-read` / `<index-name>-write` | Same as above |
+| `auto_rollover.policy_name` | ILM | (empty) | ILM policy name embedded into index templates when Jaeger creates them; leave empty when templates are created by `jaeger-es-rollover init` |
+
 ## Index Rollover \{#index-rollover}
 
-[Elasticsearch rollover](https://www.elastic.co/guide/en/elasticsearch/reference/master/indices-rollover-index.html) is an index management strategy that optimizes use of resources allocated to indices. For example, indices that do not contain any data still allocate shards, and conversely, a single index might contain significantly more data than the others. Rollover feature can be enabled by configuring an alias-based rotation strategy (`rotation.manual_rollover` or `rotation.auto_rollover`) under `indices.<type>` for each index type.
+[Elasticsearch rollover](https://www.elastic.co/guide/en/elasticsearch/reference/master/indices-rollover-index.html) is an index management strategy that optimizes use of resources allocated to indices. For example, indices that do not contain any data still allocate shards, and conversely, a single index might contain significantly more data than the others. Rollover feature can be enabled by configuring an alias-based rotation strategy (`rotation.auto_rollover`, recommended, or `rotation.manual_rollover`) under `indices.<type>` for each index type.
 
 :::warning
 The legacy rotation flags (`use_aliases`, `use_ilm`, `span_read_alias`, `span_write_alias`, `service_read_alias`, `service_write_alias`) are rejected since Jaeger v2.20.0 and cause the collector to fail at startup. Migrate to the `indices.<type>.rotation` configuration described below.
@@ -38,9 +60,9 @@ Rollover lets you configure when to roll over to a new index based on one or mor
 
 To learn more about rollover index management in Jaeger refer to this [article](https://medium.com/jaegertracing/using-elasticsearch-rollover-to-manage-indices-8b3d0c77915d).
 
-### Initialize
+### Initialize \{#initialize}
 
-The following command prepares Elasticsearch for rollover deployment by creating index aliases, indices, and index templates:
+The following command prepares Elasticsearch for rollover deployment:
 
 ```bash
 nerdctl run -it --rm --net=host \
@@ -50,23 +72,13 @@ nerdctl run -it --rm --net=host \
 
 If you need to initialize archive storage, add `-e ARCHIVE=true`.
 
-After the initialization Jaeger can be deployed with the `manual_rollover` rotation strategy on each index type. The default read/write alias names match the aliases created by the initialization:
+The initializer performs the following steps for each index type (spans, services, dependencies):
 
-```yaml
-indices:
-  spans:
-    rotation:
-      manual_rollover: {}
-  services:
-    rotation:
-      manual_rollover: {}
-  dependencies:
-    rotation:
-      manual_rollover: {}
-  sampling:
-    rotation:
-      manual_rollover: {}
-```
+1. **Creates index templates** that define field mappings, shard/replica settings, and index patterns (e.g., `jaeger-span-*`). All future rollover indices inherit their schema from these templates.
+2. **Creates the first rollover index** (e.g., `jaeger-span-000001`). Subsequent rollovers increment this number.
+3. **Creates read and write aliases** (e.g., `jaeger-span-read` and `jaeger-span-write`) pointing to the initial index. Jaeger queries via the read alias and writes via the write alias.
+
+After the initialization, Jaeger can be deployed with the `manual_rollover` rotation strategy (`indices.<type>.rotation.manual_rollover: {}`), whose default alias names match the aliases created by the initialization. With this strategy, index rollover and retention must be driven by external `jaeger-es-rollover rollover` and `lookback` cron jobs, so use it only when ILM is not available (for example, when the Jaeger Elasticsearch account lacks ILM privileges). Otherwise, prefer the ILM-based `auto_rollover` strategy described below.
 
 ### ILM support \{#ilm-support}
 
@@ -133,7 +145,13 @@ For example:
     "ILM policy jaeger-ilm-policy doesn't exist in Elasticsearch. Please create it and rerun init"
     :::
 
-After the initialization, deploy Jaeger with the `auto_rollover` rotation strategy on each index type. Rollover and retention are then managed automatically by the ILM policy, and no external cron jobs are required:
+    The initializer performs the same steps as described in [Initialize](#initialize) (creates index templates, seed indices, and aliases), with the following ILM-specific additions:
+
+    - Validates that the ILM policy (`jaeger-ilm-policy`) exists in Elasticsearch.
+    - Embeds `index.lifecycle.name` and `index.lifecycle.rollover_alias` in the index templates, so Elasticsearch automatically applies the ILM policy to every new rollover index.
+    - Sets `is_write_index: true` on the write aliases, which is required for Elasticsearch to perform ILM-triggered rollovers.
+
+After the initialization, deploy Jaeger with the `auto_rollover` rotation strategy on each index type. Rollover and retention are then managed automatically by the ILM policy, and no external cron jobs (`rollover`, `lookback`, or `index-cleaner`) are required:
 
 ```yaml
 indices:
diff --git a/v2.20.0 b/v2.20.0
deleted file mode 100644
index e69de29..0000000

From 7a7ca17c484cf5ac53327f5239ba1bbc1de3cd94 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E7=8E=8B=E7=84=B6?= <ranwang@alauda.io>
Date: Thu, 6 Aug 2026 07:35:40 +0000
Subject: [PATCH 8/8] fix: telemetry.resource and spanmetrics warning
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Signed-off-by: 王然 <ranwang@alauda.io>
---
 docs/en/configuration/spm.mdx                      |  6 +++---
 docs/en/installing/_spm-ha-common.sh               |  7 ++++---
 ...nstalling-distributed-tracing-elasticsearch.mdx | 14 ++++++++------
 .../installing-distributed-tracing-opensearch.mdx  | 14 ++++++++------
 docs/en/migrating/migrating-from-acp-tracing.mdx   |  2 +-
 5 files changed, 24 insertions(+), 19 deletions(-)

diff --git a/docs/en/configuration/spm.mdx b/docs/en/configuration/spm.mdx
index 12ef4d6..2f9f5ac 100644
--- a/docs/en/configuration/spm.mdx
+++ b/docs/en/configuration/spm.mdx
@@ -93,15 +93,15 @@ exporters:
       enabled: true
 
 connectors:
-  spanmetrics:
+  span_metrics:
     # connector configuration options
 
 service:
   pipelines:
     traces:
-      exporters: [jaeger_storage_exporter, spanmetrics]
+      exporters: [jaeger_storage_exporter, span_metrics]
     metrics/spanmetrics:
-      receivers: [spanmetrics]
+      receivers: [span_metrics]
       exporters: [prometheus]
 ```
 
diff --git a/docs/en/installing/_spm-ha-common.sh b/docs/en/installing/_spm-ha-common.sh
index 08a29c9..ae609dc 100755
--- a/docs/en/installing/_spm-ha-common.sh
+++ b/docs/en/installing/_spm-ha-common.sh
@@ -37,11 +37,12 @@ _spm_ha_precheck() {
         log_error "前置 otel 未配置 loadbalancing(routing_key=service)，当前值: '${rk}'"
         return 1
     fi
+    # glob 同时兼容新名 span_metrics（Jaeger v2.20.0+ 正式名）与旧别名 spanmetrics
     case "$connectors" in
-        *spanmetrics*) ;;
-        *) log_error "Jaeger 实例 '${JAEGER_INSTANCE_NAME}' 未配置 spanmetrics connector"; return 1 ;;
+        *span*metrics*) ;;
+        *) log_error "Jaeger 实例 '${JAEGER_INSTANCE_NAME}' 未配置 span_metrics connector"; return 1 ;;
     esac
-    log_success "前置检查通过：otel loadbalancing(routing_key=service) + jaeger spanmetrics"
+    log_success "前置检查通过：otel loadbalancing(routing_key=service) + jaeger span_metrics"
     return 0
 }
 
diff --git a/docs/en/installing/installing-distributed-tracing-elasticsearch.mdx b/docs/en/installing/installing-distributed-tracing-elasticsearch.mdx
index d1f44b7..5d28e57 100644
--- a/docs/en/installing/installing-distributed-tracing-elasticsearch.mdx
+++ b/docs/en/installing/installing-distributed-tracing-elasticsearch.mdx
@@ -424,7 +424,9 @@ Jaeger v2 is deployed as an `OpenTelemetryCollector` custom resource managed by
               exporters: [debug, jaeger_storage_exporter]
           telemetry:
             resource:
-              service.name: jaeger
+              attributes:
+                - name: service.name
+                  value: jaeger
             metrics:
               level: detailed
               readers:
@@ -799,7 +801,7 @@ Enabling SPM requires running the SpanMetrics Connector **inside Jaeger** to gen
           readOnly: true
       config:
         connectors:
-          spanmetrics: {} # [!code callout]
+          span_metrics: {} # [!code callout]
         exporters:
           prometheus: # [!code callout]
             translation_strategy: UnderscoreEscapingWithoutSuffixes # keep OTel metric names without _total suffixes (add_metric_suffixes is deprecated and ignored since Jaeger v2.20.0 / collector-contrib v0.154.0)
@@ -827,22 +829,22 @@ Enabling SPM requires running the SpanMetrics Connector **inside Jaeger** to gen
           extensions: [basicauth/monitoring, healthcheckv2, jaeger_storage, jaeger_query] # [!code callout]
           pipelines:
             traces: # [!code callout]
-              exporters: [debug, jaeger_storage_exporter, spanmetrics]
+              exporters: [debug, jaeger_storage_exporter, span_metrics]
             metrics/spanmetrics:
-              receivers: [spanmetrics]
+              receivers: [span_metrics]
               exporters: [prometheus]
     ```
 
     <Callouts>
       1. The `monitoring-credentials` volume mounts the monitoring basic-auth credentials into the Jaeger container.
       2. The `monitoring-credentials` volumeMount makes the credentials available at `/etc/jaeger/monitoring-credentials/`.
-      3. The `spanmetrics` connector generates RED metrics from the spans Jaeger receives. Because the Collector routes each service to a single Jaeger replica, every replica aggregates a disjoint set of services correctly.
+      3. The `span_metrics` connector generates RED metrics from the spans Jaeger receives. Because the Collector routes each service to a single Jaeger replica, every replica aggregates a disjoint set of services correctly.
       4. The `prometheus` exporter exposes the generated metrics on port `8889`. The Jaeger instance already carries the `prometheus: kube-prometheus` label and `observability.metrics.enableMetrics: true` (set in `jaeger.yaml`), so the Operator automatically creates a `ServiceMonitor` that lets ACP Prometheus scrape this endpoint.
       5. The `basicauth/monitoring` extension provides basic authentication for the monitoring metrics endpoint.
       6. The `metric_backends` section configures the PromQL-compatible metrics storage that Jaeger queries for SPM data.
       7. Reference the metrics store in the `jaeger_query` extension.
       8. The `basicauth/monitoring` extension must be added to the `service.extensions` list to be active.
-      9. The `traces` pipeline now also exports to `spanmetrics` (storage plus metrics generation), and a dedicated `metrics/spanmetrics` pipeline forwards the generated metrics to the `prometheus` exporter.
+      9. The `traces` pipeline now also exports to `span_metrics` (storage plus metrics generation), and a dedicated `metrics/spanmetrics` pipeline forwards the generated metrics to the `prometheus` exporter.
     </Callouts>
 
     :::warning
diff --git a/docs/en/installing/installing-distributed-tracing-opensearch.mdx b/docs/en/installing/installing-distributed-tracing-opensearch.mdx
index 8dab869..b0db798 100644
--- a/docs/en/installing/installing-distributed-tracing-opensearch.mdx
+++ b/docs/en/installing/installing-distributed-tracing-opensearch.mdx
@@ -311,7 +311,9 @@ Jaeger v2 is deployed as an `OpenTelemetryCollector` custom resource managed by
               exporters: [debug, jaeger_storage_exporter]
           telemetry:
             resource:
-              service.name: jaeger
+              attributes:
+                - name: service.name
+                  value: jaeger
             metrics:
               level: detailed
               readers:
@@ -781,7 +783,7 @@ Enabling SPM requires running the SpanMetrics Connector **inside Jaeger** to gen
           readOnly: true
       config:
         connectors:
-          spanmetrics: {} # [!code callout]
+          span_metrics: {} # [!code callout]
         exporters:
           prometheus: # [!code callout]
             translation_strategy: UnderscoreEscapingWithoutSuffixes # keep OTel metric names without _total suffixes (add_metric_suffixes is deprecated and ignored since Jaeger v2.20.0 / collector-contrib v0.154.0)
@@ -809,22 +811,22 @@ Enabling SPM requires running the SpanMetrics Connector **inside Jaeger** to gen
           extensions: [basicauth/monitoring, healthcheckv2, jaeger_storage, jaeger_query] # [!code callout]
           pipelines:
             traces: # [!code callout]
-              exporters: [debug, jaeger_storage_exporter, spanmetrics]
+              exporters: [debug, jaeger_storage_exporter, span_metrics]
             metrics/spanmetrics:
-              receivers: [spanmetrics]
+              receivers: [span_metrics]
               exporters: [prometheus]
     ```
 
     <Callouts>
       1. The `monitoring-credentials` volume mounts the monitoring basic-auth credentials into the Jaeger container.
       2. The `monitoring-credentials` volumeMount makes the credentials available at `/etc/jaeger/monitoring-credentials/`.
-      3. The `spanmetrics` connector generates RED metrics from the spans Jaeger receives. Because the Collector routes each service to a single Jaeger replica, every replica aggregates a disjoint set of services correctly.
+      3. The `span_metrics` connector generates RED metrics from the spans Jaeger receives. Because the Collector routes each service to a single Jaeger replica, every replica aggregates a disjoint set of services correctly.
       4. The `prometheus` exporter exposes the generated metrics on port `8889`. The Jaeger instance already carries the `prometheus: kube-prometheus` label and `observability.metrics.enableMetrics: true` (set in `jaeger.yaml`), so the Operator automatically creates a `ServiceMonitor` that lets ACP Prometheus scrape this endpoint.
       5. The `basicauth/monitoring` extension provides basic authentication for the monitoring metrics endpoint.
       6. The `metric_backends` section configures the PromQL-compatible metrics storage that Jaeger queries for SPM data.
       7. Reference the metrics store in the `jaeger_query` extension.
       8. The `basicauth/monitoring` extension must be added to the `service.extensions` list to be active.
-      9. The `traces` pipeline now also exports to `spanmetrics` (storage plus metrics generation), and a dedicated `metrics/spanmetrics` pipeline forwards the generated metrics to the `prometheus` exporter.
+      9. The `traces` pipeline now also exports to `span_metrics` (storage plus metrics generation), and a dedicated `metrics/spanmetrics` pipeline forwards the generated metrics to the `prometheus` exporter.
     </Callouts>
 
     :::warning
diff --git a/docs/en/migrating/migrating-from-acp-tracing.mdx b/docs/en/migrating/migrating-from-acp-tracing.mdx
index a442063..a51fba7 100644
--- a/docs/en/migrating/migrating-from-acp-tracing.mdx
+++ b/docs/en/migrating/migrating-from-acp-tracing.mdx
@@ -498,4 +498,4 @@ With the default single-export path, the new index family grows from zero while
 
 **Can Service Performance Monitoring (SPM) be enabled as part of the migration?**
 
-SPM is optional and can be enabled at any time after [Verify the migration](#verify-the-migration). Follow [(Optional) Enabling Service Performance Monitoring (SPM)](../installing/installing-distributed-tracing-elasticsearch.mdx#optional-enabling-service-performance-monitoring-spm) to add the `spanmetrics` connector to the v2 OpenTelemetry Collector and configure a metrics backend in the new Jaeger.
+SPM is optional and can be enabled at any time after [Verify the migration](#verify-the-migration). Follow [(Optional) Enabling Service Performance Monitoring (SPM)](../installing/installing-distributed-tracing-elasticsearch.mdx#optional-enabling-service-performance-monitoring-spm) to add the `span_metrics` connector and configure a metrics backend in the new Jaeger.