全部產品
Search

搜尋本產品

    Container Service for Kubernetes：實現Nginx Ingress Controller組件的鏈路追蹤

    文件中心

    Container Service for Kubernetes：實現Nginx Ingress Controller組件的鏈路追蹤

    更新時間：Oct 10, 2026

    ACK提供了Nginx-Ingress-tracing鏈路追蹤功能，支援將叢集的Nginx Ingress Controller組件的鏈路資訊上報至Managed Service for OpenTelemetry。Managed Service for OpenTelemetry可以對鏈路資訊進行即時彙總計算和持久化，形成鏈路明細、即時拓撲等監控資料，以便您進行Nginx Ingress Controller組件的問題排查與診斷。

    重要

    由於Ingress NGINX開源專案於2026年3月後停止維護更新，Container Service for Kubernetes將停止Nginx Ingress Controller組件維護，請充分瞭解使用風險。更多詳細內容，請參見【產品公告】關於停止維護Nginx Ingress Controller組件的公告。

    前提條件

    版本說明

    在不同版本的Nginx Ingress Controller組件中，鏈路追蹤的支援情況各不相同，您需要根據對應版本選擇相應的配置方式。

    Nginx Ingress Controller版本

    OpenTelemetry

    OpenTracing

    ≥ v1.10.2-aliyun.1

    支援

    不支援

    v1.9.3-aliyun.1

    支援

    支援

    v1.8.2-aliyun.1

    支援

    支援

    < v1.8.2-aliyun.1

    不支援

    支援

    操作步驟

    您需要根據實際的Nginx Ingress Controller版本支援情況選擇相應的操作步驟。

    OpenTelemetry

    步驟一：在Managed Service for OpenTelemetry中擷取存取點資訊

    新版控制台

    1. 登入可觀測鏈路 OpenTelemetry 版控制台，在左側導覽列單擊接入中心。

    2. 在开源框架地區單擊OpenTelemetry卡片。

    3. 在彈出的OpenTelemetry面板中選擇資料需要上報的地區。

    4. 記錄gRPC上報方式的存取點資訊。選擇串連方式為阿里雲內網方式，上報方式為gRPC。在通過 gRPC 上報資料地區，擷取阿里雲VPC網路存取點地址（例如 http://tracing-analysis-dc-hz-internal.aliyuncs.com:8090）和鑒權Token。使用Golang語言上報資料時請刪除存取點中的 http://。

      說明

      因為Nginx Ingress Controller組件部署在阿里雲上，且組件所在地區與Managed Service for OpenTelemetry接入配置中的地區一致，所以使用阿里雲VPC網路存取點，否則選擇公網存取點。

    舊版控制台

    1. 登入可觀測鏈路 OpenTelemetry 版控制台。

    2. 在左側導覽列單擊叢集配置，然後在右側頁面單擊AccessPointFeature頁簽。

    3. 在頁面頂部選擇需要接入的地區。

    4. 在叢集資訊地區開啟顯示Token開關，在用戶端採集工具地區單擊OpenTelemetry，然後記錄gRPC上報方式的存取點資訊。

      在gRPC上報方式中，阿里雲VPC網路存取點地址為 http://tracing-analysis-dc-hz-internal.aliyuncs.com:8090，鑒權Token為存取點資訊中顯示的Token值。

      說明

      因為Nginx Ingress Controller組件部署在阿里雲上，且組件所在地區與Managed Service for OpenTelemetry接入配置中的地區一致，所以使用阿里雲VPC網路存取點，否則選擇公網存取點。

    步驟二：在ACK的Ingress中開啟Managed Service for OpenTelemetry服務

    1. 登入Container Service管理主控台，在左側導覽列選擇叢集列表。

    2. 在叢集列表頁面，單擊目的地組群名稱，然後在左側導覽列，選擇工作負載 > 無狀態。

    3. 在配置項頁面上方設定命名空間為kube-system，然後在名稱搜尋方塊中搜尋nginx-ingress-controller，然後單擊編輯。

    4. 在編輯頁面上方，選中nginx-ingress-controller容器，並在環境變數頁簽中單擊新增添加以下環境變數。

      類型

      變數名稱

      變數/變數引用

      描述

      自訂

      OTEL_EXPORTER_OTLP_HEADERS

      authentication=<鑒權Token>

      使用步驟一：在可觀測鏈路 OpenTelemetry 版中擷取存取點資訊中擷取的鑒權Token，例如authentication=bfXXXXXXXe@7bXXXXXXX1_bXXXXXe@XXXXXXX1。

      添加完成後，單擊編輯頁面右側欄的更新，然後在彈框中單擊確定。

    5. 在左側導覽列，選擇組態管理 > 配置項。

    6. 在配置項頁面上方設定命名空間為kube-system，然後在名稱搜尋方塊中搜尋nginx-configuration，然後單擊nginx-configuration操作列的編輯。

    7. 在編輯面板單擊添加，增加以下配置，然後單擊確定。

      名稱

      描述

      取值

      樣本值

      enable-opentelemetry

      是否啟用OpenTelemetry鏈路追蹤。

      • true：表示啟用。

      • false：表示不啟用。

      true

      main-snippet

      -

      env OTEL_EXPORTER_OTLP_HEADERS;

      env OTEL_EXPORTER_OTLP_HEADERS;

      otel-service-name

      服務名稱。

      自訂。

      nginx-ingress

      otlp-collector-host

      gRPC上報點網域名稱。

      使用步驟一：在可觀測鏈路 OpenTelemetry 版中擷取存取點資訊中擷取的阿里雲VPC網路存取點，並刪除http://和連接埠號碼，例如tracing-analysis-XX-XX-XXXXX.aliyuncs.com。

      tracing-analysis-XX-XX-XXXXX.aliyuncs.com

      otlp-collector-port

      gRPC上報點連接埠。

      根據實際值填寫。

      8090

      opentelemetry-trust-incoming-span

      是否信任來自其他服務或系統的調用鏈。

      • true：表示信任。

      • false：表示不信任。

      true

      opentelemetry-operation-name

      調用鏈Span格式。

      HTTP $request_method $service_name $uri

      HTTP $request_method $service_name $uri

      otel-sampler

      採樣規則。

      參數資訊，請參見opentelemetry。

      TraceIdRatioBased

      otel-sampler-ratio

      採樣率。

      取值為0～1之間，最多可設定到小數點後兩位。0表示不採樣，1表示全部採樣。

      更多參數資訊，請參見opentelemetry。

      0.1

      otel-sampler-parent-based

      是否繼承上遊採樣標識。

      • false：預設值，表示不繼承上遊採樣標識。otel-sampler和otel-sampler-ratio將會生效。

      • true：表示繼承上遊採樣標識。otel-sampler和otel-sampler-ratio不會生效，會複用上遊採樣標識。

      更多參數資訊，請參見opentelemetry。

      false

    步驟三：在Managed Service for OpenTelemetry上查看調用鏈路資料

    1. 登入可觀測鏈路 OpenTelemetry 版控制台，

    2. 在控制台左側導覽列中單擊應用列表。

    3. 在應用列表頁面頂部選擇地區，然後單擊應用程式名稱nginx-ingress。

    4. 在應用詳情頁面查看鏈路資訊。

      • 在应用概览頁簽，查看請求數、錯誤數等資訊。應用概覽-中.jpg

      • 在調用鏈分析頁簽，可查看調用次數、錯誤數、平均耗時等圖表，以及Trace列表資訊，列表包含TraceId、介面名稱、應用程式名稱、耗時、狀態、開始時間、主機地址等欄位。

      • 在調用鏈分析頁簽，單擊TraceId，查看Trace詳情。

    OpenTracing

    步驟一：在Managed Service for OpenTelemetry中擷取存取點資訊

    新版控制台

    1. 登入可觀測鏈路 OpenTelemetry 版控制台，在左側導覽列單擊接入中心。

    2. 在开源框架地區單擊Zipkin卡片。

      說明

      根據實際使用的用戶端採集工具擷取存取點資訊，本文以Zipkin為例。

    3. 在彈出的Zipkin面板中選擇需要上報資料的地區。

    4. 記錄存取點資訊。

      說明

      因為Nginx Ingress Controller組件部署在阿里雲上，且組件所在地區與Managed Service for OpenTelemetry接入配置中的地區一致，所以使用阿里雲VPC網路存取點，否則選擇公網存取點。

    舊版控制台

    1. 登入可觀測鏈路 OpenTelemetry 版控制台。

    2. 在左側導覽列單擊叢集配置，然後在右側頁面單擊AccessPointFeature頁簽。

    3. 在頁面頂部選擇需要接入的地區。

    4. 在叢集資訊地區開啟顯示Token開關，在用戶端採集工具地區單擊Zipkin，然後記錄存取點資訊。

      在 Zipkin 頁簽下，表格展示華東1（杭州）地區的存取點資訊，包含 v2 版本存取點和 v1 版本存取點，每個版本分別提供公網存取點和阿里雲VPC網路存取點 URL。請記錄 v1 版本的阿里雲VPC網路存取點地址（路徑以 /api/v1/spans 結尾）。底部提示：一般情況下請選擇 v2 介面，在 Istio、Molten 等特定情境下請選擇 v1 介面；使用 Sleuth 組件時，baseUrl 不包含 /api/v2/spans。

      說明

      因為Nginx Ingress Controller組件部署在阿里雲上，且組件所在地區與Managed Service for OpenTelemetry接入配置中的地區一致，所以使用阿里雲VPC網路存取點，否則選擇公網存取點。

    步驟二：在ACK的Ingress中開啟Managed Service for OpenTelemetry服務

    1. 登入Container Service管理主控台，在左側導覽列選擇叢集列表。

    2. 在叢集列表頁面，單擊目的地組群名稱，然後在左側導覽列，選擇組態管理 > 配置項。

    3. 在配置項頁面上方設定命名空間為kube-system，然後在名稱搜尋方塊中搜尋nginx-configuration，然後單擊nginx-configuration操作列的編輯。

    4. 在編輯面板單擊添加，增加以下配置，然後單擊確定。

      名稱

      描述

      取值

      樣本值

      enable-opentracing

      是否開啟鏈路追蹤。

      • true：開啟鏈路追蹤。

      • false：關閉鏈路追蹤。

      true

      zipkin-service-name

      服務名稱。

      自訂。

      nginx-ingress

      zipkin-collector-host

      上報點網域名稱。

      修改步驟一：在可觀測鏈路 OpenTelemetry 版中擷取存取點資訊中擷取的存取點資訊，去掉http://，並在末尾加上問號。樣本如下：

      • 原始存取點資訊為http://tracing-analysis-dc-hz-internal.aliyuncs.com/adapt_******_******/api/v1/spans。

      • 修改後並輸入值為tracing-analysis-dc-hz-internal.aliyuncs.com/adapt_******_******/api/v1/spans?。

      tracing-analysis-dc-hz-internal.aliyuncs.com/adapt_******_******/api/v1/spans?

      opentracing-trust-incoming-span

      是否信任來自其他服務或系統的調用鏈。

      • true：表示信任。

      • false：表示不信任。

      true

      zipkin-sample-rate

      採樣率。

      取值為0～1之間，最多可設定到小數點後兩位。0表示不採樣，1表示全部採樣。

      0.1

    步驟三：在Managed Service for OpenTelemetry上查看調用鏈路資料

    1. 登入可觀測鏈路 OpenTelemetry 版控制台。

    2. 在控制台左側導覽列中單擊應用列表。

    3. 在應用列表頁面頂部選擇地區，然後單擊應用程式名稱nginx。

    4. 在應用詳情頁面左側導覽列中單擊介面調用，然後在右側地區，查看鏈路資訊。

      • 在概覽頁簽中，展示了鏈路拓撲資訊。

      • 單擊調用鏈路頁簽，查看該應用耗時最長的至多100個調用鏈路。關於更多鏈路資料，請參見介面調用。調用鏈路列表展示以下資訊列：產生時間、Span名稱、主機/ip、耗時、狀態、TraceId、操作。可通過頂部篩選條件按耗時大於指定毫秒數或勾選異常進行過濾查詢，操作列提供查看日誌連結。

      • 在調用鏈路頁簽中，單擊TraceId，查看鏈路詳情。鏈路詳情頁展示該請求的完整調用鏈，包含6個Span的層級嵌套關係及各自耗時：

        • HTTP GET opentelemetry-demo-frontendproxy /api/currency（nginx-otlp, cpp）：15.12ms

        • ingress（frontendproxy）：13.82ms

        • router frontend egress（frontendproxy）：13.64ms

        • GET（frontend, nodejs）：8.84ms

        • grpc.oteldemo.CurrencyService/GetSupportedCurrencies（frontend, nodejs）：6.83ms

        • CurrencyService/GetSupportedCurrencies（currencyservice, cpp）：1.35ms

    切換OpenTelemetry透傳協議（可選）

    採取OpenTelemetry方式實現Nginx Ingress Controller鏈路追蹤時，OpenTelemetry預設識別並向下遊傳遞W3C Trace Context格式的Trace上下文。如果您的前端應用和後端應用採用了其他協議，例如Jaeger或者Zipkin，需要修改OpenTelemetry的透傳格式，才能使前端應用、Nginx Ingress以及後端應用的調用鏈串聯起來。下面介紹如何修改Nginx Ingress Controller所使用的OpenTelemetry透傳協議。

    1. 請在步驟二第4步：在環境變數中添加OTEL_EXPORTER_OTLP_HEADERS的基礎上添加OTEL_PROPAGATORS環境變數，儲存後重新部署nginx-ingress-controller。

      環境變數名

      值

      說明

      OTEL_PROPAGATORS

      tracecontext,baggage,b3,jaeger

      透傳格式。更多資訊，請參見OpenTelemetry指定透傳Header格式。

    2. 請在步驟二第7步：添加nginx-configuration配置的基礎上修改main-snippet配置，使OTEL_PROPAGATORS環境變數生效。

      配置名

      值

      說明

      main-snippet

      env OTEL_EXPORTER_OTLP_HEADERS; env OTEL_PROPAGATORS;

      載入環境變數。

    相關文檔