How to trace the NGINX Ingress controller - Container Service for Kubernetes: Central de Documentação do Alibaba Cloud

O Container Service for Kubernetes (ACK) permite ativar o rastreamento do NGINX Ingress controller e enviar dados de rastreamento para o Managed Service for OpenTelemetry. O Managed Service for OpenTelemetry agrega, processa e armazena esses dados de rastreamento em tempo real. O serviço gera dados de monitoramento, como rastreamentos detalhados e um mapa de topologia em tempo real, para solucionar e diagnosticar problemas no NGINX Ingress controller.

Importante

O projeto open source Ingress-NGINX não receberá mais manutenção após março de 2026. Consequentemente, o Container Service for Kubernetes também descontinuará a manutenção do NGINX Ingress controller. Compreenda os riscos antes de prosseguir. Para mais detalhes, consulte o product announcement about discontinuing maintenance for the NGINX Ingress controller component.

Pré-requisitos

Ative o Managed Service for OpenTelemetry and granted the required permissions.
O NGINX Ingress controller está instalado. Para mais informações, consulte Gerencie o NGINX Ingress controller.

Compatibilidade de versões

O suporte ao rastreamento varia entre as diferentes versões do componente NGINX Ingress controller, portanto, selecione o método de configuração adequado para a sua versão.

Versão do NGINX Ingress controller	OpenTelemetry	OpenTracing
≥ v1.10.2-aliyun.1	Suportado	Não suportado
v1.9.3-aliyun.1	Suportado	Suportado
v1.8.2-aliyun.1	Suportado	Suportado
< v1.8.2-aliyun.1	Não suportado	Suportado

Procedimento

Escolha o procedimento correspondente à versão do seu NGINX Ingress controller.

OpenTelemetry

Etapa 1: Obter o endpoint doManaged Service for OpenTelemetry

Novo console

Acesse o console do Managed Service for OpenTelemetry. No painel de navegação à esquerda, clique em Integration Center.
Na seção Open Source Frameworks, clique no cartão OpenTelemetry.
No painel OpenTelemetry exibido, selecione a região para a qual deseja enviar dados.
Anote o endpoint do método grpc. Defina Connection Method como Alibaba Cloud Internal Network e Reporting Method como grpc. Na área Report Data via grpc, obtenha o endpoint de rede VPC da Alibaba Cloud, por exemplo http://tracing-analysis-dc-hz-internal.aliyuncs.com:8090, e o Authentication Token. Se for enviar dados usando Golang, remova http:// do endpoint.

Nota
Use o endpoint de VPC se o NGINX Ingress controller estiver implantado na mesma região da Alibaba Cloud da sua integração do Managed Service for OpenTelemetry. Caso contrário, use o endpoint público.

Console anterior

Acesse o console do Managed Service for OpenTelemetry.
No painel de navegação à esquerda, clique em Cluster Configurations. Na página exibida, clique na aba Access Point Information.
Na parte superior da página, selecione a região à qual deseja se conectar.
Na seção Cluster Information, ative a opção Show Token. Na seção Client, clique em OpenTelemetry e anote o endpoint do método grpc.

Para o método grpc, o endpoint de rede VPC da Alibaba Cloud é http://tracing-analysis-dc-hz-internal.aliyuncs.com:8090. O token de autenticação é o valor exibido nas informações do endpoint.

Nota
Use o endpoint de VPC se o NGINX Ingress controller estiver implantado na mesma região da Alibaba Cloud da sua integração do Managed Service for OpenTelemetry. Caso contrário, use o endpoint público.

Etapa 2: Configure o NGINX Ingress controllerManaged Service for OpenTelemetry

Acesse o console do ACK. No painel de navegação à esquerda, clique em Clusters.
Na página Clusters, clique no nome do seu cluster. No painel de navegação à esquerda, clique em Workloads > Deployments.
Na página Deployments, defina o Namespace como kube-system. Pesquise por nginx-ingress-controller e clique em Edite.

Na parte superior da página Edit, selecione o contêiner nginx-ingress-controller. Na aba Environment Variable, clique em Add para definir a seguinte variável de ambiente.

Type

Variable key

Value/value from

Descrição

Custom

OTEL_EXPORTER_OTLP_HEADERS

authentication=<authentication token>

Use o token de autenticação obtido em Step 1: Obtain the endpoint. Exemplo: authentication=bfXXXXXXXe@7bXXXXXXX1_bXXXXXe@XXXXXXX1.

Após adicionar a variável, clique em Edit no painel à direita da página Update. Na caixa de diálogo exibida, clique em OK.

No painel de navegação à esquerda, escolha Configurations > ConfigMaps.
Na página Configurations, defina o Namespace como kube-system. Pesquise por nginx-configuration e clique em Actions na coluna Edit do ConfigMap nginx-configuration.

No painel Edit, clique em Add, adicione a seguinte configuração e clique em OK.

Parâmetro	Descrição	Valor	Exemplo
enable-opentelemetry	Ativa o rastreamento do OpenTelemetry.	true: ativa o rastreamento. false: desativa o rastreamento.	`true`
main-snippet	-	`env OTEL_EXPORTER_OTLP_HEADERS;`	`env OTEL_EXPORTER_OTLP_HEADERS;`
otel-service-name	O nome do service.	Personalizado.	nginx-ingress
otlp-collector-host	O nome de domínio do endpoint de envio grpc.	Use o endpoint de VPC obtido em Step 1: Obtain the endpoint. Remova o prefixo http:// e o número da porta. Exemplo: `tracing-analysis-XX-XX-XXXXX.aliyuncs.com`.	`tracing-analysis-XX-XX-XXXXX.aliyuncs.com`
otlp-collector-port	A porta do endpoint de envio grpc.	Insira o valor real.	`8090`
opentelemetry-trust-incoming-span	Especifica se o sistema deve confiar em rastreamentos recebidos de outros services.	true: ativa a confiança. false: desativa a confiança.	`true`
opentelemetry-operation-name	O formato do span de rastreamento.	`HTTP $request_method $service_name $uri`	`HTTP $request_method $service_name $uri`
otel-sampler	A estratégia de amostragem.	Para mais informações sobre os parâmetros, consulte opentelemetry.	TraceIdRatioBased
otel-sampler-ratio	A taxa de amostragem.	O valor deve estar entre 0 e 1, com até duas casas decimais. Um valor de 0 significa que nenhuma requisição é amostrada, e 1 significa que todas são amostradas. Para mais informações sobre os parâmetros, consulte opentelemetry.	0.1
otel-sampler-parent-based	Especifica se deve herdar a decisão de amostragem do service upstream.	false (Padrão): Não herda a decisão de amostragem upstream. A amostragem baseia-se nos parâmetros otel-sampler e otel-sampler-ratio. true: Herda a decisão de amostragem upstream. Os parâmetros otel-sampler e otel-sampler-ratio são ignorados. Para mais informações sobre os parâmetros, consulte opentelemetry.	false

Etapa 3: Visualize dados de rastreamento do Managed Service for OpenTelemetry

Acesse o console do Managed Service for OpenTelemetry.
No painel de navegação à esquerda, clique em Applications.
Na parte superior da página Applications, selecione a região e clique no nome do aplicativo nginx-ingress.
- Na aba Application Overview, visualize métricas como contagem de requisições e contagem de erros.
- Na aba Trace Analysis, visualize gráficos como o número de chamadas, o número de erros e a duração média, além da lista de rastreamentos. A lista contém campos como TraceId, nome da interface, nome do aplicativo, duração, status, hora de início e endereço do host.
- Na aba Trace Analysis, clique em um Trace ID para visualizar os detalhes do rastreamento.

OpenTracing

Etapa 1: Obter o endpoint do Managed Service for OpenTelemetry

Novo console

Acesse o console do Managed Service for OpenTelemetry. No painel de navegação à esquerda, clique em Integration Center.
Na seção Open Source Frameworks, clique no cartão Zipkin.

Nota
O endpoint obtido depende do cliente utilizado. Este tópico usa o Zipkin como exemplo.
No painel Zipkin exibido, selecione a região para a qual deseja enviar dados.
Anote as informações do endpoint.

Nota
Use o endpoint de VPC se o NGINX Ingress controller estiver implantado na mesma região da Alibaba Cloud da sua integração do Managed Service for OpenTelemetry. Caso contrário, use o endpoint público.

Console anterior

Acesse o console do Managed Service for OpenTelemetry.
No painel de navegação à esquerda, clique em Cluster Configurations. Na página exibida, clique na aba Access Point Information.
Na parte superior da página, selecione a região à qual deseja se conectar.
Na seção Cluster Information, ative a opção Show Token. Na seção Client, clique em Zipkin e anote as informações do endpoint.

Na aba Zipkin, uma tabela exibe as informações do endpoint para a região China (Hangzhou). A tabela contém endpoints v2 e v1, e cada versão fornece uma url de endpoint público e uma url de endpoint de rede VPC da Alibaba Cloud. Anote o endereço do Alibaba Cloud VPC Network Endpoint da versão v1, cujo caminho termina com /api/v1/spans. Na maioria dos casos, selecione a interface v2. Em cenários específicos como Istio e Molten, selecione a interface v1. Ao usar o componente Sleuth, o baseUrl não inclui /api/v2/spans.

Nota
Use o endpoint de VPC se o NGINX Ingress controller estiver implantado na mesma região da Alibaba Cloud da sua integração do Managed Service for OpenTelemetry. Caso contrário, use o endpoint público.

Etapa 2: Configure o NGINX Ingress controllerManaged Service for OpenTelemetry

Acesse o console do ACK. No painel de navegação à esquerda, clique em Clusters.
Na página Clusters, clique no nome do seu cluster. No painel de navegação à esquerda, clique em Configurations > ConfigMaps.
Na página Configurations, defina o Namespace como kube-system. Pesquise por nginx-configuration e clique em Actions na coluna Edit do ConfigMap nginx-configuration.

No painel Edit, clique em Add, adicione a seguinte configuração e clique em OK.

Parâmetro	Descrição	Valor	Exemplo
enable-opentracing	Especifica se o rastreamento deve ser ativado.	true: ativa o rastreamento. false: desativa o rastreamento.	true
zipkin-service-name	O nome do service.	Personalizado.	nginx-ingress
zipkin-collector-host	O nome de domínio do endpoint de envio.	Modifique o endpoint obtido em Step 1: Obtain the endpoint. Remova o prefixo `http://` e adicione um ponto de interrogação `?` ao final. Por exemplo: Endpoint original: `http://tracing-analysis-dc-hz-internal.aliyuncs.com/adapt__/api/v1/spans` Valor modificado: `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	Especifica se o sistema deve confiar em rastreamentos de outros services ou sistemas.	true: ativa a confiança. false: desativa a confiança.	true
zipkin-sample-rate	A taxa de amostragem.	O valor deve estar entre 0 e 1, com até duas casas decimais. Um valor de 0 significa que nenhuma requisição é amostrada, e 1 significa que todas são amostradas.	0.1

Etapa 3: Visualize dados de rastreamento doManaged Service for OpenTelemetry

Acesse o console do Managed Service for OpenTelemetry.
No painel de navegação à esquerda, clique em Applications.
Na parte superior da página Applications, selecione a região e clique no nome do aplicativo nginx.
No painel de navegação à esquerda da página de detalhes do aplicativo, clique em API Call. Na área à direita, visualize as informações de rastreamento.
- A aba Overview exibe a topologia de rastreamento.
- Clique na aba Traces para visualizar até 100 rastreamentos com a maior duração para o aplicativo. Para mais informações sobre dados de rastreamento, consulte Interface Calls. A lista de rastreamentos exibe as seguintes colunas: Generation Time, Span Name, Host/IP, Duration, Status, TraceId e Actions. Use as condições de filtro na parte superior para filtrar rastreamentos por Duration Greater Than um número especificado de milissegundos ou selecione Abnormal. A coluna Actions fornece o link Visualize Logs.
- Na aba Traces, clique em um Trace ID para visualizar os detalhes do rastreamento. A página de detalhes do rastreamento exibe a cadeia de chamadas completa da requisição, incluindo a relação de aninhamento hierárquico e a duração de seis spans:
  - HTTP GET opentelemetry-demo-frontendproxy /api/currency (nginx-otlp, cpp): 15,12 ms
  - ingress (frontendproxy): 13,82 ms
  - router frontend egress (frontendproxy): 13,64 ms
  - GET (frontend, nodejs): 8,84 ms
  - grpc.oteldemo.CurrencyService/GetSupportedCurrencies (frontend, nodejs): 6,83 ms
  - CurrencyService/GetSupportedCurrencies (currencyservice, cpp): 1,35 ms

Alterar o protocolo de propagação de rastreamento (Opcional)

Ao usar o OpenTelemetry para o rastreamento do NGINX Ingress controller, o OpenTelemetry reconhece e propaga o contexto de rastreamento downstream no formato W3C Trace Context por padrão. Se as suas aplicações frontend e backend usarem outros protocolos, como Jaeger ou Zipkin, modifique o protocolo de propagação de rastreamento do OpenTelemetry para vincular os rastreamentos do aplicativo frontend, do NGINX Ingress controller e do aplicativo backend. Este tópico descreve como modificar o protocolo de propagação de rastreamento do OpenTelemetry usado pelo NGINX Ingress controller.

Além da configuração em Step 2, substep 4, adicione a variável de ambiente OTEL_PROPAGATORS. Salve a alteração e implante novamente o nginx-ingress-controller.

Variable key

Value

Description

OTEL_PROPAGATORS

tracecontext,baggage,b3,jaeger

O formato de propagação. Para mais informações, consulte Especifique the propagation header format for OpenTelemetry.

Além da configuração em Step 2, substep 7, modifique a configuração main-snippet para aplicar a variável de ambiente OTEL_PROPAGATORS.

Parâmetro

Valor

Descrição

main-snippet

env OTEL_EXPORTER_OTLP_HEADERS; env OTEL_PROPAGATORS;

Carrega as variáveis de ambiente.

Referências

Para mais informações sobre o Managed Service for OpenTelemetry, consulte What is Managed Service for OpenTelemetry?
Para mais informações sobre o ACK, consulte What is Container Service for Kubernetes (ACK)?
Os campos obrigatórios no ConfigMap nginx-configuration variam dependendo da solução de rastreamento (como Zipkin, Jaeger ou SkyWalking). Para mais informações sobre como integrar essas soluções ao Managed Service for OpenTelemetry, consulte Preparations.