全部产品
Search

搜索本产品

    容器服务 Kubernetes 版 ACK：实现Nginx Ingress Controller组件的链路追踪

    文档中心

    容器服务 Kubernetes 版 ACK：实现Nginx Ingress Controller组件的链路追踪

    更新时间：Oct 10, 2026

    ACK提供了Nginx-Ingress-tracing链路追踪功能，支持将集群的Nginx Ingress Controller组件的链路信息上报至可观测链路 OpenTelemetry 版。可观测链路 OpenTelemetry 版可以对链路信息进行实时聚合计算和持久化，形成链路明细、实时拓扑等监控数据，以便您进行Nginx Ingress Controller组件的问题排查与诊断。

    重要

    由于Ingress NGINX开源项目于2026年3月后停止维护更新，容器服务 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

    步骤一：在可观测链路 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组件部署在阿里云上，且组件所在地域与可观测链路 OpenTelemetry 版接入配置中的地域一致，所以使用阿里云VPC网络接入点，否则选择公网接入点。

    旧版控制台

    1. 登录可观测链路 OpenTelemetry 版控制台。

    2. 在左侧导航栏单击集群配置，然后在右侧页面单击接入点信息页签。

    3. 在页面顶部选择需要接入的地域。

    4. 在集群信息区域打开显示Token开关，在客户端采集工具区域单击OpenTelemetry，然后记录gRPC上报方式的接入点信息。

      在gRPC上报方式中，阿里云VPC网络接入点地址为 http://tracing-analysis-dc-hz-internal.aliyuncs.com:8090，鉴权Token为接入点信息中显示的Token值。

      说明

      因为Nginx Ingress Controller组件部署在阿里云上，且组件所在地域与可观测链路 OpenTelemetry 版接入配置中的地域一致，所以使用阿里云VPC网络接入点，否则选择公网接入点。

    步骤二：在ACK的Ingress中开启可观测链路 OpenTelemetry 版服务

    1. 登录容器服务管理控制台，在左侧导航栏选择集群列表。

    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

    步骤三：在可观测链路 OpenTelemetry 版上查看调用链路数据

    1. 登录可观测链路 OpenTelemetry 版控制台，

    2. 在控制台左侧导航栏中单击应用列表。

    3. 在应用列表页面顶部选择地域，然后单击应用名称nginx-ingress。

    4. 在应用详情页面查看链路信息。

      • 在应用概览页签，查看请求数、错误数等信息。应用概览-中.jpg

      • 在调用链分析页签，可查看调用次数、错误数、平均耗时等图表，以及Trace列表信息，列表包含TraceId、接口名称、应用名称、耗时、状态、开始时间、主机地址等字段。

      • 在调用链分析页签，单击TraceId，查看Trace详情。

    OpenTracing

    步骤一：在可观测链路 OpenTelemetry 版中获取接入点信息

    新版控制台

    1. 登录可观测链路 OpenTelemetry 版控制台，在左侧导航栏单击接入中心。

    2. 在开源框架区域单击Zipkin卡片。

      说明

      根据实际使用的客户端采集工具获取接入点信息，本文以Zipkin为例。

    3. 在弹出的Zipkin面板中选择需要上报数据的地域。

    4. 记录接入点信息。

      说明

      因为Nginx Ingress Controller组件部署在阿里云上，且组件所在地域与可观测链路 OpenTelemetry 版接入配置中的地域一致，所以使用阿里云VPC网络接入点，否则选择公网接入点。

    旧版控制台

    1. 登录可观测链路 OpenTelemetry 版控制台。

    2. 在左侧导航栏单击集群配置，然后在右侧页面单击接入点信息页签。

    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组件部署在阿里云上，且组件所在地域与可观测链路 OpenTelemetry 版接入配置中的地域一致，所以使用阿里云VPC网络接入点，否则选择公网接入点。

    步骤二：在ACK的Ingress中开启可观测链路 OpenTelemetry 版服务

    1. 登录容器服务管理控制台，在左侧导航栏选择集群列表。

    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

    步骤三：在可观测链路 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;

      加载环境变量。

    相关文档