How to trace the NGINX Ingress controller - Container Service for Kubernetes

Container Service for Kubernetes (ACK) vous permet d'activer le traçage pour le contrôleur NGINX Ingress et d'envoyer les données de trace vers Managed Service for OpenTelemetry. Managed Service for OpenTelemetry agrège, traite et stocke ces données de trace en temps réel. Le service génère des données de surveillance, telles que des traces détaillées et une carte topologique en temps réel, afin de faciliter le dépannage et le diagnostic des problèmes liés au contrôleur NGINX Ingress.

Important

Le projet open source Ingress-NGINX ne sera plus maintenu après mars 2026. Par conséquent, Container Service for Kubernetes cessera également de maintenir le contrôleur NGINX Ingress. Prenez connaissance des risques avant de poursuivre. Pour plus de détails, consultez l'annonce produit concernant l'arrêt de la maintenance du composant NGINX Ingress controller.

Prérequis

Vous avez activé Managed Service for OpenTelemetry et accordé les autorisations requises.
Le contrôleur NGINX Ingress est installé. Pour plus d'informations, consultez Gérer le contrôleur NGINX Ingress.

Compatibilité des versions

La prise en charge du traçage varie selon les versions du composant contrôleur NGINX Ingress. Vous devez donc sélectionner la méthode de configuration appropriée à votre version.

Version du contrôleur NGINX Ingress

OpenTelemetry

OpenTracing

≥ v1.10.2-aliyun.1

Prise en charge

Non pris en charge

v1.9.3-aliyun.1

Prise en charge

v1.8.2-aliyun.1

Prise en charge

< v1.8.2-aliyun.1

Non pris en charge

Prise en charge

Instructions

Procédure

Sélectionnez la procédure correspondant à la version de votre contrôleur d'entrée NGINX.

OpenTelemetry

Étape 1 : Obtenir l'endpointManaged Service for OpenTelemetry

New console

Connectez-vous à la console Managed Service for OpenTelemetry. Dans le volet de navigation de gauche, cliquez sur Integration Center.
Dans la section Open Source Frameworks, cliquez sur la carte OpenTelemetry.
Dans le panneau OpenTelemetry qui s'affiche, sélectionnez la région dans laquelle vous souhaitez envoyer les données.
Notez l'endpoint pour la méthode de reporting gRPC. Définissez Connection Method sur Alibaba Cloud Internal Network et Reporting Method sur gRPC. Dans la zone Report Data via gRPC, récupérez l'endpoint du réseau VPC Alibaba Cloud, par exemple http://tracing-analysis-dc-hz-internal.aliyuncs.com:8090, ainsi que le Authentication Token. Si vous envoyez des données en utilisant le langage Golang, supprimez http:// de l'endpoint.

Remarque
Utilisez l'endpoint VPC si le contrôleur d'entrée NGINX est déployé dans la même région Alibaba Cloud que votre intégration Managed Service for OpenTelemetry. Sinon, utilisez l'endpoint public.

Previous console

Connectez-vous à la console Managed Service for OpenTelemetry.
Dans le volet de navigation de gauche, cliquez sur Cluster Configurations. Sur la page qui s'affiche, cliquez sur l'onglet Access Point Information.
En haut de la page, sélectionnez la région à laquelle vous souhaitez vous connecter.
Dans la section Cluster Information, activez l'interrupteur Show Token. Dans la section Client, cliquez sur OpenTelemetry, puis notez l'endpoint pour la méthode de reporting gRPC.

Pour la méthode de reporting gRPC, l'endpoint du réseau VPC Alibaba Cloud est http://tracing-analysis-dc-hz-internal.aliyuncs.com:8090. Le jeton d'authentification correspond à la valeur du jeton affichée dans les informations de l'endpoint.

Remarque
Utilisez l'endpoint VPC si le contrôleur d'entrée NGINX est déployé dans la même région Alibaba Cloud que votre intégration Managed Service for OpenTelemetry. Sinon, utilisez l'endpoint public.

Étape 2 : Configurer le contrôleur d'entrée NGINXManaged Service for OpenTelemetry

Connectez-vous à la console ACK. Dans le volet de navigation de gauche, cliquez sur Clusters.
Sur la page Clusters, cliquez sur le nom de votre cluster. Dans le volet de navigation de gauche, cliquez sur Workloads > Deployments.
Sur la page Deployments, définissez Namespace sur kube-system. Recherchez nginx-ingress-controller, puis cliquez sur Edit.

En haut de la page Edit, sélectionnez le conteneur nginx-ingress-controller. Dans l'onglet Environment Variable, cliquez sur Add pour définir la variable d'environnement suivante.

Type

Variable key

Value/value from

Description

Custom

OTEL_EXPORTER_OTLP_HEADERS

authentication=<authentication token>

Utilisez le jeton d'authentification obtenu à l'Étape 1 : Obtenir l'endpoint. Exemple : authentication=bfXXXXXXXe@7bXXXXXXX1_bXXXXXe@XXXXXXX1.

Après avoir ajouté la variable, cliquez sur Edit dans le panneau de droite de la page Update. Dans la boîte de dialogue qui s'affiche, cliquez sur OK.

Dans le volet de navigation de gauche, choisissez Configurations > > > ConfigMaps.
Sur la page Configurations, définissez Namespace sur kube-system. Recherchez nginx-configuration, puis cliquez sur Actions dans la colonne Edit pour le ConfigMap nginx-configuration.

Dans le panneau Edit, cliquez sur Add, ajoutez la configuration suivante, puis cliquez sur OK.

Parameter	Description	Value	Example
enable-opentelemetry	Active le traçage OpenTelemetry.	true : active le traçage. false : désactive le traçage.	`true`
main-snippet	-	`env OTEL_EXPORTER_OTLP_HEADERS;`	`env OTEL_EXPORTER_OTLP_HEADERS;`
otel-service-name	Le nom du service.	Personnalisé.	nginx-ingress
otlp-collector-host	Le nom de domaine de l'endpoint de reporting gRPC.	Utilisez l'endpoint VPC obtenu à l'Étape 1 : Obtenir l'endpoint. Supprimez le préfixe http:// et le numéro de port. Exemple : `tracing-analysis-XX-XX-XXXXX.aliyuncs.com`.	`tracing-analysis-XX-XX-XXXXX.aliyuncs.com`
otlp-collector-port	Le port de l'endpoint de reporting gRPC.	Saisissez la valeur réelle.	`8090`
opentelemetry-trust-incoming-span	Indique s'il faut faire confiance aux traces entrantes provenant d'autres services.	true : la confiance est activée. false : la confiance est désactivée.	`true`
opentelemetry-operation-name	Le format du span de trace.	`HTTP $request_method $service_name $uri`	`HTTP $request_method $service_name $uri`
otel-sampler	La stratégie d'échantillonnage.	Pour plus d'informations sur les paramètres, consultez opentelemetry.	TraceIdRatioBased
otel-sampler-ratio	Le taux d'échantillonnage.	La valeur doit être comprise entre 0 et 1, avec jusqu'à deux décimales. Une valeur de 0 signifie qu'aucune requête n'est échantillonnée, et 1 signifie que toutes les requêtes sont échantillonnées. Pour plus d'informations sur les paramètres, consultez opentelemetry.	0.1
otel-sampler-parent-based	Indique s'il faut hériter de la décision d'échantillonnage du service en amont.	false (par défaut) : n'hérite pas de la décision d'échantillonnage en amont. L'échantillonnage est basé sur les paramètres otel-sampler et otel-sampler-ratio. true : hérite de la décision d'échantillonnage en amont. Les paramètres otel-sampler et otel-sampler-ratio sont ignorés. Pour plus d'informations sur les paramètres, consultez opentelemetry.	false

Étape 3 : Consulter les données de trace Managed Service for OpenTelemetry

Connectez-vous à la console Managed Service for OpenTelemetry.
Dans le volet de navigation de gauche, cliquez sur Integration Center.
En haut de la page Open Source Frameworks, sélectionnez la région, puis cliquez sur le nom de l'application nginx-ingress.
- Sous l'onglet Cluster Configurations, consultez les métriques telles que le nombre de requêtes et le nombre d'erreurs.
- Sous l'onglet Access Point Information, vous pouvez visualiser des graphiques (nombre d'appels, nombre d'erreurs, durée moyenne) ainsi que la liste des traces. Cette liste inclut des champs tels que TraceId, nom de l'interface, nom de l'application, durée, statut, heure de début et adresse hôte.
- Sous l'onglet Cluster Information, cliquez sur un ID de trace pour afficher les détails de la trace.

OpenTracing

Étape 1 : Obtenir le point de terminaison Managed Service for OpenTelemetry

Nouvelle console

Connectez-vous à la console Managed Service for OpenTelemetry. Dans le volet de navigation de gauche, cliquez sur Integration Center.
Dans la section Clusters, cliquez sur la carte Zipkin.

Remarque
Le point de terminaison que vous obtenez dépend du client utilisé. Cette rubrique prend Zipkin comme exemple.
Dans le panneau Zipkin qui s'affiche, sélectionnez la région dans laquelle vous souhaitez envoyer les données.
Notez les informations relatives au point de terminaison.

Remarque
Utilisez le point de terminaison VPC si le contrôleur NGINX Ingress est déployé dans la même région Alibaba Cloud que votre intégration Managed Service for OpenTelemetry. Sinon, utilisez le point de terminaison public.

Ancienne console

Connectez-vous à la console Managed Service for OpenTelemetry.
Dans le volet de navigation de gauche, cliquez sur Workloads. Sur la page qui s'affiche, cliquez sur l'onglet Deployments.
En haut de la page, sélectionnez la région à laquelle vous souhaitez vous connecter.
Dans la section Edit, activez l'option Show Token. Dans la section Client, cliquez sur Zipkin, puis notez les informations relatives au point de terminaison.

Sous l'onglet Zipkin, un tableau affiche les informations de point de terminaison pour la région Chine (Hangzhou). Le tableau contient des points de terminaison v2 et v1 ; chaque version propose une URL de point de terminaison public et une URL de point de terminaison réseau VPC Alibaba Cloud. Notez l'adresse du Alibaba Cloud VPC Network Endpoint de la version v1, dont le chemin se termine par /api/v1/spans. Dans la plupart des cas, sélectionnez l'interface v2. Pour des scénarios spécifiques tels qu'Istio et Molten, sélectionnez l'interface v1. Lorsque vous utilisez le composant Sleuth, le baseUrl n'inclut pas /api/v2/spans.

Remarque
Utilisez le point de terminaison VPC si le contrôleur NGINX Ingress est déployé dans la même région Alibaba Cloud que votre intégration Managed Service for OpenTelemetry. Sinon, utilisez le point de terminaison public.

Étape 2 : Configurer le contrôleur NGINX IngressManaged Service for OpenTelemetry

Connectez-vous à la console ACK. Dans le volet de navigation de gauche, cliquez sur Clusters.
Sur la page Add, cliquez sur le nom de votre cluster. Dans le volet de navigation de gauche, cliquez sur Edit > Update.
Sur la page OK, définissez le paramètre Namespace sur kube-system. Recherchez nginx-configuration, puis cliquez sur Configurations dans la colonne ConfigMaps pour le ConfigMap nginx-configuration.

Dans le panneau Configurations, cliquez sur Actions, ajoutez la configuration suivante, puis cliquez sur OK.

Paramètre	Description	Valeur	Exemple
enable-opentracing	Indique s'il faut activer le traçage.	true : active le traçage. false : désactive le traçage.	true
zipkin-service-name	Nom du service.	Personnalisé.	nginx-ingress
zipkin-collector-host	Nom de domaine du point de terminaison de rapport.	Modifiez le point de terminaison obtenu à l'étape 1 : Obtenir le point de terminaison. Supprimez le préfixe `http://` et ajoutez un point d'interrogation `?` à la fin. Par exemple : Point de terminaison d'origine : `http://tracing-analysis-dc-hz-internal.aliyuncs.com/adapt__/api/v1/spans` Valeur modifiée : `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	Indique s'il faut faire confiance aux traces provenant d'autres services ou systèmes.	true : la confiance est activée. false : la confiance est désactivée.	true
zipkin-sample-rate	Taux d'échantillonnage.	La valeur doit être comprise entre 0 et 1, avec au maximum deux décimales. Une valeur de 0 signifie qu'aucune requête n'est échantillonnée, et 1 signifie que toutes les requêtes sont échantillonnées.	0.1

Étape 3 : Consulter les données de traceManaged Service for OpenTelemetry

Connectez-vous à la console Managed Service for OpenTelemetry.
Dans le volet de navigation de gauche, cliquez sur Edit.
En haut de la page Edit, sélectionnez la région, puis cliquez sur le nom de l'application nginx.
Dans le volet de navigation de gauche de la page des détails de l'application, cliquez sur Add. Dans la zone de droite, consultez les informations de trace.
- L'onglet OK affiche la topologie des traces.
- Cliquez sur l'onglet Traces pour afficher jusqu'à 100 traces ayant la durée la plus longue pour l'application. Pour plus d'informations sur les données de trace, consultez la rubrique Appels d'interface. La liste des traces affiche les colonnes suivantes : Generation Time, Span Name, Host/IP, Duration, Status, TraceId et Actions. Vous pouvez utiliser les conditions de filtre en haut pour filtrer les traces selon une Duration Greater Than (durée supérieure à) un nombre spécifié de millisecondes ou en sélectionnant Abnormal. La colonne Actions fournit le lien View Logs.
- Sous l'onglet Traces, cliquez sur un ID de trace pour afficher les détails de la trace. La page des détails de la trace affiche la chaîne d'appel complète de la requête, y compris la relation d'imbrication hiérarchique et la durée de six 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

Modifier le protocole de propagation des traces (facultatif)

Lorsque vous utilisez OpenTelemetry pour la collecte de traces du contrôleur d'entrée NGINX, OpenTelemetry reconnaît et propage par défaut le contexte de trace en aval au format W3C Trace Context. Si vos applications frontend et backend utilisent d'autres protocoles, tels que Jaeger ou Zipkin, vous devez modifier le protocole de propagation des traces d'OpenTelemetry afin de relier les traces issues de l'application frontend, du contrôleur d'entrée NGINX et de l'application backend. Cette rubrique explique comment modifier le protocole de propagation des traces OpenTelemetry utilisé par le contrôleur d'entrée NGINX.

En plus de la configuration décrite à l'étape 2, sous-étape 4 (voir Étape 2, sous-étape 4), ajoutez la variable d'environnement OTEL_PROPAGATORS. Enregistrez la modification et redéployez nginx-ingress-controller.

Clé de variable

Valeur

Description

OTEL_PROPAGATORS

tracecontext,baggage,b3,jaeger

Format de propagation. Pour plus d'informations, consultez la section Spécifier le format d'en-tête de propagation pour OpenTelemetry.

En plus de la configuration décrite à l'étape 2, sous-étape 7 (voir Étape 2, sous-étape 7), modifiez la configuration main-snippet pour appliquer la variable d'environnement OTEL_PROPAGATORS.

Paramètre

Valeur

Description

main-snippet

env OTEL_EXPORTER_OTLP_HEADERS; env OTEL_PROPAGATORS;

Charge les variables d'environnement.

Références

Pour plus d'informations sur Managed Service for OpenTelemetry, consultez la page Présentation de Managed Service for OpenTelemetry
Pour plus d'informations sur ACK, consultez la page Présentation de Container Service for Kubernetes (ACK)
Les champs requis dans la ConfigMap nginx-configuration varient selon la solution de traçabilité utilisée (Zipkin, Jaeger ou SkyWalking, par exemple). Pour plus d'informations sur l'intégration de ces solutions avec Managed Service for OpenTelemetry, consultez la section Préparatifs.