Alauda Distributed Tracing
  • 简体中文

    • 使用 Elasticsearch 安装 Alauda 分布式追踪

    安装 Alauda 分布式追踪平台包括以下步骤：

    1. 安装 Alauda Build of Jaeger v2 集群插件
    2. 安装 Alauda Build of OpenTelemetry v2 Operator
    3. 部署 Alauda Build of Jaeger v2
    4. 部署 OpenTelemetry Collector，将追踪数据转发到 Jaeger
    NOTE

    从 ACP 4.5 开始，以下插件使用了新名称：

    • Alauda Build of Jaeger v2 更名为 Alauda Container Platform Distributed Tracing。
    • Alauda Build of OpenTelemetry v2 更名为 Alauda Container Platform Application Observability。

    从 Customer Portal 下载插件时，请搜索新名称。在重命名之前发布的插件包上传到平台后，平台中仍会显示其原名称。

    目录

    安装 Alauda Build of Jaeger v2 集群插件通过 Web 控制台安装通过 CLI 安装安装 Alauda Build of OpenTelemetry v2 Operator通过 Web 控制台安装通过 CLI 安装部署 Alauda Build of Jaeger v2部署 OpenTelemetry Collector验证（可选）启用服务性能监控（SPM）卸载

    安装 Alauda Build of Jaeger v2 集群插件

    Alauda Build of Jaeger v2 集群插件提供追踪组件所需的容器镜像：Jaeger（jaeger、jaeger-es-rollover、jaeger-es-index-cleaner）和 OAuth2 Proxy。安装插件会将这些镜像同步到平台的内置 registry，并在目标集群的 cpaas-system 命名空间中创建名为 jaeger-cluster-plugin-manifest 的 ConfigMap。后续步骤会从此 ConfigMap 中读取镜像地址。

    通过 Web 控制台安装

    1. 在平台管理视图中，导航至 管理员 > Marketplace > 集群插件。
    2. 选择要部署追踪组件的集群。
    3. 找到 Alauda Container Platform Distributed Tracing（对于重命名之前发布的包，显示为 Alauda Build of Jaeger v2），然后单击 安装。此插件无需安装参数。
    NOTE

    如果列表中未显示该插件，请从 Customer Portal 下载插件包，并使用 violet 工具将其发布到平台，或联系技术支持。

    通过 CLI 安装

    无论插件面向哪个集群，集群插件都必须通过在 global 集群中创建 ModuleInfo 资源来安装。

    1. 在 global 集群中运行以下命令，检查已发布的插件版本：

      kubectl get moduleconfigs -l cpaas.io/module-name=jaeger-cluster-plugin \
  -o custom-columns=NAME:.metadata.name,VERSION:.spec.version

    2. 在 global 集群中创建 ModuleInfo 资源以安装插件。将 <target-cluster> 替换为要部署追踪组件的集群名称，并将 <plugin-version> 替换为上一步中的某个版本：

      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

      平台在接收该资源时会重写 metadata.name，并将记录存储为 <target-cluster>-<hash>。之后，所应用的名称将不再存在，因此再次运行此命令时，对于从未写入的名称会报告 AlreadyExists，且不会创建任何内容。请按照下一步所示，通过标签识别该记录。

    3. 在 global 集群中验证安装：

      kubectl get moduleinfo -l cpaas.io/module-name=jaeger-cluster-plugin

      当 STATUS 列显示 Running 时，表示插件已成功安装。

    4. 验证目标集群中是否已创建 ConfigMap（针对目标集群运行）：

      kubectl get configmap jaeger-cluster-plugin-manifest -n cpaas-system

    安装 Alauda Build of OpenTelemetry v2 Operator

    Alauda Build of OpenTelemetry v2 Operator 管理 Jaeger v2 和 OpenTelemetry Collector 实例的生命周期。在部署任何追踪组件之前，必须先安装此 Operator。

    通过 Web 控制台安装

    请按照 Alauda Build of OpenTelemetry v2 文档中 通过 Web 控制台安装 部分中的说明进行操作。

    通过 CLI 安装

    请按照 Alauda Build of OpenTelemetry v2 文档中 通过 CLI 安装 部分中的说明进行操作。

    部署 Alauda Build of Jaeger v2

    Jaeger v2 作为由 Alauda Build of OpenTelemetry v2 Operator 管理的 OpenTelemetryCollector 自定义资源进行部署。它使用后端存储，并通过 OAuth2 Proxy sidecar 与 Alauda Container Platform 身份验证系统集成。

    前提条件

    • 已安装 Alauda Container Platform Distributed Tracing（以前称为 Alauda Build of Jaeger v2）集群插件。
    • 已安装 Alauda Container Platform Application Observability（以前称为 Alauda Build of OpenTelemetry v2）Operator。
    • 有一个可用的 Elasticsearch 8.x 实例，并且已获取其端点 URL、用户名和密码。
    • 集群管理员已建立活动的 ACP CLI（kubectl）会话，并具有 cluster-admin 角色。

    操作步骤

    1. 设置用于连接 Elasticsearch 的用户可配置环境变量：

      export ES_ENDPOINT='<Elasticsearch endpoint URL>'
export ES_USER='<Elasticsearch username>'
export ES_PASS='<Elasticsearch password>'

      将占位值替换为实际的 Elasticsearch 凭据。

    2. 从集群中获取平台配置，并从 Alauda Build of Jaeger v2 集群插件创建的 ConfigMap 中获取 Jaeger 相关容器镜像：

      export PLATFORM_URL=$(kubectl -nkube-public get configmap global-info -o jsonpath='{.data.platformURL}')
export CLUSTER_NAME=$(kubectl -nkube-public get configmap global-info -o jsonpath='{.data.clusterName}')
export ALB_CLASS_NAME=$(kubectl -nkube-public get configmap global-info -o jsonpath='{.data.systemAlbIngressClassName}')

export OIDC_ISSUER=$(kubectl -nkube-public get configmap global-info -o jsonpath='{.data.oidcIssuer}')
OIDC_CLIENT_SECRET_REF=$(kubectl -nkube-public get configmap global-info -o jsonpath='{.data.oidcClientSecretRef}')
if [ -n "$OIDC_CLIENT_SECRET_REF" ]; then
  SYSTEM_NAMESPACE=$(kubectl -nkube-public get configmap global-info -o jsonpath='{.data.systemNamespace}')
  export OIDC_CLIENT_ID=$(kubectl -n"$SYSTEM_NAMESPACE" get secret "$OIDC_CLIENT_SECRET_REF" -o go-template='{{index .data "client-id"}}' | base64 -d)
  export OIDC_CLIENT_SECRET=$(kubectl -n"$SYSTEM_NAMESPACE" get secret "$OIDC_CLIENT_SECRET_REF" -o go-template='{{index .data "client-secret"}}' | base64 -d)
else
  export OIDC_CLIENT_ID=$(kubectl -nkube-public get configmap global-info -o jsonpath='{.data.oidcClientID}')
  export OIDC_CLIENT_SECRET=$(kubectl -nkube-public get configmap global-info -o jsonpath='{.data.oidcClientSecret}')
fi

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

      确认命令执行时未发生错误。

    3. 设置默认环境变量。您可以根据部署要求调整这些值：

      # Namespace for the Jaeger instance
export JAEGER_NS="jaeger-system"
# Name of the Jaeger instance
export JAEGER_INSTANCE_NAME="jaeger"
# Elasticsearch index prefix for Jaeger data
export JAEGER_ES_INDEX_PREFIX="acp-${CLUSTER_NAME}"
# Maximum expected duration of a single trace. Controls how far beyond the search window spans are looked up.
export JAEGER_MAX_TRACE_DURATION="1h"
# Base path for the Jaeger UI
export JAEGER_BASEPATH="/clusters/${CLUSTER_NAME}/jaeger"

    4. 创建 Jaeger 命名空间和 Elasticsearch 凭据 Secret：

      kubectl get namespace ${JAEGER_NS} &> /dev/null || kubectl create namespace ${JAEGER_NS}

kubectl create secret generic es-credentials \
  --namespace=${JAEGER_NS} \
  --from-literal=ES_USER=${ES_USER} \
  --from-literal=ES_PASS=${ES_PASS} \
  --dry-run=client -o yaml | kubectl apply -f -

      验证 Secret 是否已创建：

      kubectl get secret es-credentials -n ${JAEGER_NS}

    5. 在 Elasticsearch 中创建 ILM（Index Lifecycle Management）Policy。Jaeger 使用 ILM 管理索引滚动和保留：

      curl -k -u "${ES_USER}:${ES_PASS}" -X PUT \
  "${ES_ENDPOINT}/_ilm/policy/jaeger-ilm-policy" \
  -H 'Content-Type: application/json' \
  --data-binary @- << 'EOF'
{
  "policy": {
    "phases": {
      "hot": {
        "min_age": "0ms",
        "actions": {
          "rollover": {
            "max_primary_shard_size": "50gb",
            "max_age": "1d"
          },
          "set_priority": {
            "priority": 100
          }
        }
      },
      "delete": {
        "min_age": "7d",
        "actions": {
          "delete": {}
        }
      }
    }
  }
}
EOF

      关键字段：

      • policy.phases.hot.actions.rollover.max_primary_shard_size：单个主分片的最大大小。当分片超过此大小时，将触发滚动以创建新索引。默认值：50gb。
      • policy.phases.hot.actions.rollover.max_age：触发滚动前索引的最大存留时间。默认值：1d（1 天）。
      • policy.phases.delete.min_age：滚动后等待删除旧索引的时间。默认值：7d（7 天）。

      验证 ILM Policy：

      curl -k -u "${ES_USER}:${ES_PASS}" "${ES_ENDPOINT}/_ilm/policy/jaeger-ilm-policy?pretty"

      输出应显示 ILM Policy 详细信息，包括 hot 和 delete 阶段。

    6. 使用 jaeger-es-rollover 工具初始化索引别名和模板。这会为 Elasticsearch 存储 Jaeger 数据做好准备：

      kubectl apply -n ${JAEGER_NS} -f - <<EOF
apiVersion: batch/v1
kind: Job
metadata:
  name: jaeger-es-rollover-init
spec:
  template:
    spec:
      containers:
      - name: es-rollover-init
        image: "${JAEGER_ES_ROLLOVER_IMAGE}"
        args:
          - init
          - "${ES_ENDPOINT}"
        env:
        - name: INDEX_PREFIX
          value: "${JAEGER_ES_INDEX_PREFIX}"
        - name: ES_USE_ILM
          value: "true"
        - name: ADAPTIVE_SAMPLING
          value: "true"
        - name: ES_TLS_ENABLED
          value: "true"
        - name: ES_TLS_SKIP_HOST_VERIFY
          value: "true"
        - name: ES_USERNAME
          valueFrom:
            secretKeyRef:
              name: es-credentials
              key: ES_USER
        - name: ES_PASSWORD
          valueFrom:
            secretKeyRef:
              name: es-credentials
              key: ES_PASS
      restartPolicy: Never
  backoffLimit: 3
EOF

      等待 Job 完成，然后验证索引模板和别名是否已创建：

      kubectl wait --for=condition=complete job/jaeger-es-rollover-init \
  -n ${JAEGER_NS} --timeout=120s

# Verify index templates
curl -k -sS -u "${ES_USER}:${ES_PASS}" "${ES_ENDPOINT}/_index_template?pretty" \
  | grep ${JAEGER_ES_INDEX_PREFIX}-jaeger-

# Verify index aliases
curl -k -sS -u "${ES_USER}:${ES_PASS}" "${ES_ENDPOINT}/_alias?pretty" \
  | grep ${JAEGER_ES_INDEX_PREFIX}-jaeger-

      预期结果如下：

      • Job 状态为 Complete。
      • Elasticsearch 中存在与 ${JAEGER_ES_INDEX_PREFIX}-jaeger-* 匹配的索引模板。
      • Elasticsearch 中存在 ${JAEGER_ES_INDEX_PREFIX}-jaeger-*-read 和 ${JAEGER_ES_INDEX_PREFIX}-jaeger-*-write 的索引别名。

    7. Job 完成后清理初始化 Job：

      kubectl delete job jaeger-es-rollover-init -n ${JAEGER_NS}

    8. 为 OAuth2 Proxy 创建 Secret。OAuth2 Proxy 用于将 Jaeger UI 与 Alauda Container Platform 身份验证集成：

      # Generate a cookie secret for the OAuth2 Proxy:
OAUTH2_PROXY_COOKIE_SECRET=$(dd if=/dev/urandom bs=32 count=1 2>/dev/null | base64 | tr -d -- '\n' | tr -- '+/' '-_')
# Create the Secret:
kubectl create secret generic ${JAEGER_INSTANCE_NAME}-oauth2-proxy \
  --namespace=${JAEGER_NS} \
  --from-literal=OAUTH2_PROXY_CLIENT_SECRET=${OIDC_CLIENT_SECRET} \
  --from-literal=OAUTH2_PROXY_COOKIE_SECRET=${OAUTH2_PROXY_COOKIE_SECRET} \
  --dry-run=client -o yaml | kubectl apply -f -

    9. 创建名为 jaeger.yaml 的文件，内容如下：

      jaeger.yaml
      apiVersion: opentelemetry.io/v1beta1
kind: OpenTelemetryCollector
metadata:
  labels:
    prometheus: kube-prometheus
  name: ${JAEGER_INSTANCE_NAME}
  namespace: ${JAEGER_NS}
spec:
  image: "${JAEGER_IMAGE}"
  mode: deployment
  replicas: 1

  resources:
    requests:
      cpu: 100m
      memory: 256Mi
    limits:
      cpu: "2"
      memory: 2Gi

  ports:
    - name: oauth2-proxy
      port: 4180
    - name: jaeger-grpc
      port: 16685

  observability:
    metrics:
      enableMetrics: true

  volumes:
    - name: es-credentials
      secret:
        secretName: es-credentials
        items:
          - key: ES_PASS
            path: pass
    - name: oauth2-proxy-secrets
      secret:
        secretName: ${JAEGER_INSTANCE_NAME}-oauth2-proxy
        items:
          - key: OAUTH2_PROXY_CLIENT_SECRET
            path: client-secret
          - key: OAUTH2_PROXY_COOKIE_SECRET
            path: cookie-secret
  volumeMounts:
    - name: es-credentials
      mountPath: /etc/jaeger/es-credentials
      readOnly: true

  config:
    receivers:
      otlp:
        protocols:
          grpc:
            endpoint: "0.0.0.0:4317"
          http:
            endpoint: "0.0.0.0:4318"

    processors:
      batch: {}
      memory_limiter:
        check_interval: 1s
        limit_percentage: 80
        spike_limit_percentage: 20

    exporters:
      debug: {}
      jaeger_storage_exporter:
        trace_storage: es_storage

    extensions:
      healthcheckv2:
        use_v2: true
        http:
          endpoint: "0.0.0.0:13133"

      jaeger_storage:
        backends:
          es_storage:
            elasticsearch:
              server_urls:
                - "${ES_ENDPOINT}"
              auth:
                basic:
                  username: "${ES_USER}"
                  password_file: /etc/jaeger/es-credentials/pass
              tls:
                insecure_skip_verify: true
              service_cache_ttl: 12h
              max_trace_duration: "${JAEGER_MAX_TRACE_DURATION}"
              create_mappings: false
              indices:
                index_prefix: "${JAEGER_ES_INDEX_PREFIX}"
                spans:
                  shards: 5
                  replicas: 1
                  rotation:
                    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:
        storage:
          traces: es_storage
        ui:
          config_file: ""
        base_path: "${JAEGER_BASEPATH}"
        http:
          endpoint: 0.0.0.0:16686

    service:
      extensions: [healthcheckv2, jaeger_storage, jaeger_query]
      pipelines:
        traces:
          receivers: [otlp]
          processors: [memory_limiter, batch]
          exporters: [debug, jaeger_storage_exporter]
      telemetry:
        metrics:
          level: detailed
          readers:
            - pull:
                exporter:
                  prometheus:
                    host: "0.0.0.0"
                    port: 8888
        logs:
          level: info

  additionalContainers:
    - name: oauth2-proxy
      image: ${JOAUTH2_PROXY_IMAGE}
      args:
        - --http-address=0.0.0.0:4180
        - --upstream=http://127.0.0.1:16686
        - --proxy-prefix=${JAEGER_BASEPATH}/oauth2
        - --redirect-url=${PLATFORM_URL}${JAEGER_BASEPATH}/oauth2/callback
        - --provider=oidc
        - --oidc-issuer-url=${OIDC_ISSUER}
        - --scope=openid profile email groups ext
        - --email-domain=*
        - --code-challenge-method=S256
        - --insecure-oidc-allow-unverified-email=true
        - --cookie-secure=false
        - --skip-provider-button=true
        - --ssl-insecure-skip-verify=true
        - --skip-jwt-bearer-tokens=true
        - --client-id=${OIDC_CLIENT_ID}
        - --client-secret-file=/etc/oauth2-proxy/client-secret
        - --cookie-secret-file=/etc/oauth2-proxy/cookie-secret
      resources:
        requests:
          cpu: 50m
          memory: 64Mi
        limits:
          cpu: 500m
          memory: 256Mi
      volumeMounts:
        - name: oauth2-proxy-secrets
          mountPath: /etc/oauth2-proxy
          readOnly: true
      ports:
        - containerPort: 4180
          name: oauth2-proxy
          protocol: TCP
      1. prometheus: kube-prometheus 标签会由自动创建的 ServiceMonitor 资源继承，从而使 ACP Prometheus 能够抓取 Jaeger 指标。
      2. Jaeger v2 容器镜像。这不是默认的 OpenTelemetry Collector 镜像，而是基于 OpenTelemetry Collector 框架构建的自定义 Jaeger 二进制文件。
      3. 为 Jaeger 实例启用 Prometheus 指标端点。
      4. Jaeger 容器的资源请求和限制。请根据预期的追踪量进行调整；吞吐量较高的环境可能需要更多 CPU 和内存。
      5. jaeger_storage 扩展配置用于存储追踪数据的 Elasticsearch 后端。
      6. service_cache_ttl 控制服务名称缓存的保留时长。默认值为 12h。如果 ILM 从 hot 阶段到 delete 阶段的间隔较短，请减小此值，以确保 Jaeger UI 能够及时发现服务。
      7. max_trace_duration 是单个追踪的最大预期持续时间，此处设置为 JAEGER_MAX_TRACE_DURATION。查询服务会在时间范围过滤器的两侧各扩展此值，因此仍可找到超出搜索窗口的 span。默认值为 24h；如果追踪持续时间较短，请将其调小。请参阅查询时间范围。
      8. 使用 auto_rollover 轮换策略时，必须将 create_mappings 设置为 false，因为索引模板和映射由滚动初始化进行管理。
      9. index_prefix 必须与第 6 步中 jaeger-es-rollover 初始化期间使用的前缀匹配。有关分片和副本调优的更多详细信息，请参阅分片和副本。
      10. rotation.auto_rollover 策略使用读/写别名，并依赖第 5 步创建的 ILM Policy 自动触发索引滚动。默认别名称与第 6 步中 jaeger-es-rollover 初始化所创建的别名匹配。它取代了旧版 use_aliases/use_ilm 标志；Jaeger v2.20.0 起不再接受这些标志。由于读别名始终解析为与其关联的所有索引，因此 max_span_age 在此策略下不起作用，特意保持未设置状态；保留策略完全由 ILM Policy 管理。
      11. jaeger_query 扩展为 Jaeger Query API 和 Jaeger UI 提供服务。
      12. additionalContainers 部分定义 OAuth2 Proxy sidecar。该 sidecar 通过与 Alauda Container Platform Dex Identity Provider 集成，为 Jaeger UI 处理身份验证。
      13. OAuth2 Proxy sidecar 的资源请求和限制。由于此容器仅代理身份验证请求，因此资源需求较低。

    10. 使用 envsubst 渲染清单并应用配置：

      envsubst < jaeger.yaml | kubectl apply -f -

    11. 等待 Jaeger Pod 就绪。Operator 会根据 OpenTelemetryCollector 资源渲染 Deployment；资源应用几秒后 Deployment 才会出现，因此请先等待其创建，再等待其 rollout：

      kubectl wait --for=create deployment/${JAEGER_INSTANCE_NAME}-collector \
  -n ${JAEGER_NS} --timeout=2m
kubectl rollout status deployment/${JAEGER_INSTANCE_NAME}-collector \
  -n ${JAEGER_NS} --timeout=180s

    12. 为命名空间添加标签并创建 Ingress，以公开 Jaeger UI：

      kubectl label namespace ${JAEGER_NS} cpaas.io/project=cpaas-system --overwrite
      kubectl apply -n ${JAEGER_NS} -f - <<EOF
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: ${JAEGER_INSTANCE_NAME}
  annotations:
    nginx.ingress.kubernetes.io/enable-cors: "true"
spec:
  ingressClassName: ${ALB_CLASS_NAME}
  rules:
    - http:
        paths:
          - path: ${JAEGER_BASEPATH}
            pathType: ImplementationSpecific
            backend:
              service:
                name: ${JAEGER_INSTANCE_NAME}-collector
                port:
                  number: 4180
EOF

      等待 Ingress 就绪：

      kubectl wait --for=jsonpath='{.status.loadBalancer.ingress}' ingress/${JAEGER_INSTANCE_NAME} \
  -n ${JAEGER_NS} --timeout=180s

    验证

    访问 <platform-url>/clusters/<cluster-name>/jaeger 中的 Jaeger UI，其中 <platform-url> 是 Alauda Container Platform URL，<cluster-name> 是集群名称。

    运行以下命令以打印 Jaeger UI URL：

    echo "Jaeger UI: ${PLATFORM_URL}${JAEGER_BASEPATH}"

    部署 OpenTelemetry Collector

    Jaeger v2 运行后，部署一个 OpenTelemetry Collector 实例，以接收来自已插桩应用的 trace 数据并将其转发到 Jaeger。

    1. 创建名为 otel-collector.yaml 的文件，内容如下：

      otel-collector.yaml
      apiVersion: opentelemetry.io/v1beta1
kind: OpenTelemetryCollector
metadata:
  labels:
    prometheus: kube-prometheus
  name: otel
  namespace: ${JAEGER_NS}
spec:
  mode: deployment
  replicas: 1
  resources:
    requests:
      cpu: 100m
      memory: 256Mi
    limits:
      cpu: "2"
      memory: 2Gi
  observability:
    metrics:
      enableMetrics: true
  config:
    receivers:
      otlp:
        protocols:
          grpc:
            endpoint: 0.0.0.0:4317
          http:
            endpoint: 0.0.0.0:4318
      zipkin: {}
    processors:
      batch: {}
      memory_limiter:
        check_interval: 1s
        limit_percentage: 80
        spike_limit_percentage: 20
    exporters:
      debug: {}
      otlp_grpc/traces:
        endpoint: "${JAEGER_INSTANCE_NAME}-collector.${JAEGER_NS}.svc.cluster.local:4317"
        tls:
          insecure: true
      prometheus:
        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
    service:
      pipelines:
        traces:
          receivers: [otlp, zipkin]
          processors: [memory_limiter, batch]
          exporters: [debug, otlp_grpc/traces] 
        metrics:
          receivers: [otlp]
          processors: [memory_limiter, batch]
          exporters: [debug, prometheus]
      telemetry:
        metrics:
          readers:
          - pull:
              exporter:
                prometheus:
                  host: 0.0.0.0
                  port: 8888
      1. prometheus: kube-prometheus 标签使 ACP Prometheus 能够通过自动创建的 ServiceMonitor 抓取 Collector 指标。
      2. Collector 容器的资源请求和限制。请根据预期的 trace 吞吐量进行调整。
      3. 启用 Operator 为 Collector 的指标端点自动创建 ServiceMonitor 资源。
      4. OTLP receiver 通过 gRPC（端口 4317）和 HTTP（端口 4318）接收来自已插桩应用的 trace 数据。
      5. otlp_grpc/traces exporter 将接收到的 trace 转发到 Jaeger collector service。该端点根据 Jaeger 实例名称和命名空间推导得出。
      6. trace pipeline 通过 OTLP 和 Zipkin 接收数据，经由 memory_limiter 和 batch 处理后，同时导出到 debug exporter（用于日志记录）和 otlp_grpc/traces（用于转发到 Jaeger）。
      OTLP gRPC exporter 名为

      otlp_grpc exporter 类型名称是 otlp_grpc，而不是 otlp。后一个名称仍可作为已弃用的别名使用，但 Collector 随后会在启动时针对每个受影响的组件实例记录弃用警告，并且上游计划在未来版本中移除该别名。

    2. 使用 envsubst 渲染 manifest 并应用配置：

      envsubst < otel-collector.yaml | kubectl apply -f -

    3. 等待 Collector pod 就绪。同上，只有在 Operator 处理完该资源后，Deployment 才会出现：

      kubectl wait --for=create deployment/otel-collector \
  -n ${JAEGER_NS} --timeout=2m
kubectl rollout status deployment/otel-collector \
  -n ${JAEGER_NS} --timeout=180s

    验证

    安装所有组件后，通过生成示例 trace 数据验证端到端 tracing pipeline。

    1. 部署 telemetrygen 作为测试客户端，以生成示例 trace：

      kubectl apply -f - <<EOF
apiVersion: v1
kind: Pod
metadata:
  name: telemetrygen
  namespace: ${JAEGER_NS}
spec:
  restartPolicy: Never
  containers:
    - name: telemetrygen
      image: ghcr.io/open-telemetry/opentelemetry-collector-contrib/telemetrygen:latest
      args:
        - traces
        - --otlp-endpoint=otel-collector.${JAEGER_NS}.svc.cluster.local:4317
        - --otlp-insecure
        - --duration=150s
        - --interval=5s
        - --child-spans=3
        - --rate=2
        - --service=telemetrygen
        - --workers=1
EOF
# Wait for telemetrygen to complete, then clean up the test Pod
kubectl wait -n ${JAEGER_NS} --for=jsonpath='{.status.phase}'=Succeeded pod/telemetrygen --timeout=10m
kubectl delete pod -n ${JAEGER_NS} telemetrygen
      NOTE

      --otlp-endpoint 必须指向上一步部署的 OpenTelemetry Collector service。

    2. 在 <platform-url>/clusters/<cluster-name>/jaeger 打开 Jaeger UI。

      从 Service 下拉菜单中选择 telemetrygen service，然后点击 Find Traces，验证生成的 trace 是否可见。

      运行以下命令以输出 Jaeger UI URL：

      echo "Jaeger UI: ${PLATFORM_URL}${JAEGER_BASEPATH}"

    （可选）启用服务性能监控（SPM）

    服务性能监控（SPM）以 Jaeger UI 中 Monitor 标签页的形式呈现，通过聚合 span 数据生成 RED（请求、错误、时长）指标。借助此功能，您无需预先了解服务名称或操作名称，即可识别性能问题。有关详细信息，请参阅服务性能监控（SPM）。

    启用 SPM 需要在 Jaeger 内部运行 SpanMetrics Connector 以生成 RED 指标，并通过 load_balancing exporter 将 span 从前端 OpenTelemetry Collector 路由到 Jaeger，从而确保即使两个组件都运行多个副本，指标仍保持准确。Jaeger 会在 Prometheus endpoint 上公开这些指标，并通过兼容 PromQL 的后端将其返回到 Monitor 标签页。

    前提条件

    • 已部署 Jaeger v2 和 OpenTelemetry Collector（已完成之前的所有步骤）。
    • 集群中已提供 ACP 监控。

    操作步骤

    1. 从集群中获取监控 endpoint 和凭据：

      export MONITORING_URL=$(kubectl get feature monitoring -o jsonpath='{.spec.accessInfo.database.address}')
MONITORING_SECRET_NAME=$(kubectl get feature monitoring -o jsonpath='{.spec.accessInfo.database.basicAuth.secretName}')

export MONITORING_USERNAME=$(kubectl -ncpaas-system get secret "$MONITORING_SECRET_NAME" -o jsonpath="{.data.username}" | base64 -d)
export MONITORING_PASSWORD=$(kubectl -ncpaas-system get secret "$MONITORING_SECRET_NAME" -o jsonpath="{.data.password}" | base64 -d)

    2. 创建用于存储监控凭据的 Secret：

      kubectl create secret generic monitoring-credentials \
  --namespace=${JAEGER_NS} \
  --from-literal=username=${MONITORING_USERNAME} \
  --from-literal=password=${MONITORING_PASSWORD} \
  --dry-run=client -o yaml | kubectl apply -f -

    3. 修补 OpenTelemetry Collector，使其通过 load_balancing exporter 将 span 转发到 Jaeger，并替换直接使用的 otlp_grpc/traces exporter。借助 routing_key: service，给定服务的所有 span 都会一致地发送到同一个 Jaeger 副本，因此在 Jaeger 内部运行的 SpanMetrics Connector（下一步）会对每个服务恰好聚合一次。这可以确保在 Collector 或 Jaeger 运行多个副本时指标保持正确：

      kubectl patch opentelemetrycollector otel -n ${JAEGER_NS} --type=merge -p "
spec:
  config:
    exporters:
      otlp_grpc/traces: null # remove the direct exporter, replaced by load_balancing
      load_balancing:
        routing_key: service
        protocol:
          otlp: # a configuration field of the load_balancing exporter, not a component type name
            tls:
              insecure: true
        resolver:
          dns:
            hostname: ${JAEGER_INSTANCE_NAME}-collector-headless.${JAEGER_NS}.svc.cluster.local
            port: '4317' # the dns resolver requires the port as a string
    service:
      pipelines:
        traces:
          exporters: [debug, load_balancing]
"

      dns resolver 会通过 OpenTelemetry Operator 自动创建的无头 Service（${JAEGER_INSTANCE_NAME}-collector-headless）发现每个 Jaeger collector Pod，因此无需额外的 Service 或 RBAC。

      等待 Collector 重启：

      kubectl rollout status deployment/otel-collector \
  -n ${JAEGER_NS} --timeout=180s

    4. 创建名为 jaeger-spm-patch.yaml 的文件，内容如下。此补丁会在 Jaeger 内部运行 SpanMetrics Connector，在 Prometheus endpoint 上公开生成的 RED 指标，并添加 PromQL 指标后端，使 Jaeger 能够将这些指标提供给 Monitor 标签页：

      jaeger-spm-patch.yaml
      spec:
  volumes:
    - name: es-credentials
      secret:
        secretName: es-credentials
        items:
          - key: ES_PASS
            path: pass
    - name: oauth2-proxy-secrets
      secret:
        secretName: ${JAEGER_INSTANCE_NAME}-oauth2-proxy
        items:
          - key: OAUTH2_PROXY_CLIENT_SECRET
            path: client-secret
          - key: OAUTH2_PROXY_COOKIE_SECRET
            path: cookie-secret
    - name: monitoring-credentials
      secret:
        secretName: monitoring-credentials
        items:
          - key: username
            path: user
          - key: password
            path: pass
  volumeMounts:
    - name: es-credentials
      mountPath: /etc/jaeger/es-credentials
      readOnly: true
    - name: monitoring-credentials
      mountPath: /etc/jaeger/monitoring-credentials
      readOnly: true
  config:
    connectors:
      span_metrics: {} 
    exporters:
      prometheus:
        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
    extensions:
      basicauth/monitoring:
        client_auth:
          username_file: /etc/jaeger/monitoring-credentials/user
          password_file: /etc/jaeger/monitoring-credentials/pass
      jaeger_storage:
        metric_backends:
          monitoring_metrics_storage:
            prometheus:
              endpoint: ${MONITORING_URL}
              tls:
                insecure_skip_verify: true
              auth:
                authenticator: basicauth/monitoring
      jaeger_query:
        storage:
          metrics: monitoring_metrics_storage
    service:
      extensions: [basicauth/monitoring, healthcheckv2, jaeger_storage, jaeger_query] 
      pipelines:
        traces:
          exporters: [debug, jaeger_storage_exporter, span_metrics]
        metrics/spanmetrics:
          receivers: [span_metrics]
          exporters: [prometheus]
      1. monitoring-credentials volume 会将监控 basic-auth 凭据挂载到 Jaeger 容器中。
      2. monitoring-credentials volumeMount 会使凭据在 /etc/jaeger/monitoring-credentials/ 处可用。
      3. span_metrics connector 会根据 Jaeger 接收的 span 生成 RED 指标。由于 Collector 会将每个服务路由到单个 Jaeger 副本，因此每个副本都会正确聚合不重叠的服务集合。
      4. prometheus exporter 会在端口 8889 上公开生成的指标。Jaeger 实例已经带有 prometheus: kube-prometheus 标签和 observability.metrics.enableMetrics: true（在 jaeger.yaml 中设置），因此 Operator 会自动创建 ServiceMonitor，使 ACP Prometheus 能够抓取此 endpoint。
      5. basicauth/monitoring extension 为监控指标 endpoint 提供 basic authentication。
      6. metric_backends 部分配置 Jaeger 用于查询 SPM 数据的兼容 PromQL 的指标存储。
      7. 在 jaeger_query extension 中引用指标存储。
      8. 必须将 basicauth/monitoring extension 添加到 service.extensions 列表中，才能使其生效。
      9. traces pipeline 现在还会导出到 span_metrics（存储和指标生成），而专用的 metrics/spanmetrics pipeline 会将生成的指标转发到 prometheus exporter。
      WARNING

      volumes、volumeMounts、service.extensions 字段以及 exporters pipeline 都是数组。合并补丁会完整替换数组，而不是向其中追加内容。上面的补丁文件包含所有现有条目以及新增条目，以防止数据丢失。

    5. 应用补丁：

      kubectl patch opentelemetrycollector ${JAEGER_INSTANCE_NAME} -n ${JAEGER_NS} \
  --type=merge -p "$(envsubst < jaeger-spm-patch.yaml)"

      等待 Jaeger 重启：

      kubectl rollout status deployment/${JAEGER_INSTANCE_NAME}-collector \
  -n ${JAEGER_NS} --timeout=180s
    扩展到多个副本

    要以高可用模式运行 SPM，请增加 spec.replicas 在 otel 和 ${JAEGER_INSTANCE_NAME} collector 上的值；无需进行其他更改。无状态 Collector 层可以自由扩展，并且由于 span 由 service 进行负载均衡，每个 Jaeger 副本都会负责不重叠的服务集合并无冲突地进行聚合。

    验证

    启用 SPM 后，可以按照上文验证部分中的说明部署 telemetrygen 测试客户端来进行验证。

    生成 trace 后，在 Jaeger UI 中转到 Monitor 标签页，查看 telemetrygen service 的聚合 RED 指标。

    卸载

    要从集群中移除 Alauda Distributed Tracing 组件，请参阅卸载 Alauda Distributed Tracing。