How to enable tracing for NGINX Ingress Controller - Application Real-Time Monitoring Service

Container Service for Kubernetes (ACK) propose une fonctionnalité de traçage qui vous permet d'envoyer les traces du composant NGINX Ingress Controller de votre cluster ACK vers Managed Service for OpenTelemetry. Managed Service for OpenTelemetry

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 la rubrique 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 choisir la méthode de configuration adaptée à votre version.

Version du contrôleur NGINX Ingress

OpenTelemetry

OpenTracing

≥ v1.10.2-aliyun.1

Pris en charge

Non pris en charge

v1.9.3-aliyun.1

Pris en charge

v1.8.2-aliyun.1

Pris en charge

< v1.8.2-aliyun.1

Non pris en charge

Pris en charge

Procédure

OpenTelemetry

Étape 1 : Obtenir les informations sur l'endpoint

Connectez-vous à la console ARMS. Dans le volet de navigation de gauche, cliquez sur Integration Center.
Dans la zone Server-side Applications, 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 les informations sur l'endpoint. Dans la section Paramètres, définissez Connection Method sur Alibaba Cloud Intranet et Report Method sur gRPC. Ensuite, dans la section Endpoint Information, copiez l'adresse de l'endpoint gRPC (par exemple, http://tracing-analysis-dc-hz-internal.aliyuncs.com:8090) ainsi que le jeton d'authentification.

Remarque
Utilisez l'endpoint réseau VPC si votre NGINX Ingress Controller est déployé dans la même région Alibaba Cloud que Managed Service for OpenTelemetry. Sinon, utilisez l'endpoint public.

Étape 2 : Activer OpenTelemetry sur NGINX Ingress ControllerManaged 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 le déploiement nginx-ingress-controller et cliquez sur Edit dans la colonne Actions.

Sur la page Edit, sélectionnez le conteneur nginx-ingress-controller. Sous l'onglet Environment Variable, cliquez sur Add pour ajouter la variable d'environnement suivante.

Type

Nom de la variable

Valeur

Description

Custom

OTEL_EXPORTER_OTLP_HEADERS

authentication=<jeton d'authentification>

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

Une fois l'ajout terminé, cliquez sur Update à droite de la page Edit, puis cliquez sur OK dans la boîte de dialogue qui apparaît.

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

Dans le panneau Edit, cliquez sur Add pour ajouter les paires clé-valeur suivantes, puis cliquez sur OK.

Paramètre	Description	Valeur	Exemple
enable-opentelemetry	Indique si le traçage OpenTelemetry est activé.	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	Nom du service.	Un nom personnalisé.	nginx-ingress
otlp-collector-host	Nom de domaine de l'endpoint de rapport gRPC.	Utilisez l'endpoint réseau VPC obtenu à l'étape 1 : Obtenir les informations sur 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	Port de l'endpoint de rapport gRPC.	Numéro de port réel.	`8090`
opentelemetry-trust-incoming-span	Indique s'il faut faire confiance aux traces entrantes provenant d'autres services ou systèmes.	true : fait confiance aux traces entrantes. false : ne fait pas confiance aux traces entrantes.	`true`
opentelemetry-operation-name	Format de la span de trace.	`HTTP $request_method $service_name $uri`	`HTTP $request_method $service_name $uri`
otel-sampler	Règle d'échantillonnage.	Pour plus d'informations, consultez la documentation NGINX Ingress Controller.	TraceIdRatioBased
otel-sampler-ratio	Taux d'échantillonnage.	Une valeur comprise entre 0,0 et 1,0, avec un maximum de deux décimales. Une valeur de 0,0 désactive l'échantillonnage, tandis qu'une valeur de 1,0 échantillonne chaque trace. Pour plus d'informations, consultez la documentation NGINX Ingress Controller.	0.1
otel-sampler-parent-based	Indique s'il faut hériter de la décision d'échantillonnage du service amont.	false : (Par défaut) n'hérite pas de la décision d'échantillonnage amont. Les paramètres `otel-sampler` et `otel-sampler-ratio` prennent effet. true : hérite et réutilise la décision d'échantillonnage amont. Les paramètres `otel-sampler` et `otel-sampler-ratio` ne prennent pas effet. Pour plus d'informations, consultez la documentation NGINX Ingress Controller.	false

Étape 3 : Consulter les traces dans la console ARMS

Connectez-vous à la console ARMS. Dans le volet de navigation de gauche, choisissez Application Monitoring > Application List.
Sur la page Application List, sélectionnez une région dans la liste déroulante en haut de la page. Cliquez ensuite sur le nom de l'application nginx-ingress.
Explorez les informations de traçage sur la page des détails de l'application.
- Sous l'onglet Application Overview, consultez les métriques telles que le nombre de requêtes et d'erreurs.
- Sous l'onglet Trace Explorer, vous pouvez visualiser des graphiques relatifs au nombre d'appels, aux erreurs et à la durée en haut de la page. Sous les graphiques, une liste de traces s'affiche avec des colonnes telles que TraceId, nom de la span, nom de l'application, Duration et Status (par exemple, 200 ou 404).
- Depuis la liste des traces sous l'onglet Trace Explorer, cliquez sur un TraceId pour ouvrir sa page de détails. Cette page présente une vue chronologique et des informations détaillées pour chaque span, y compris le nom de l'application (par exemple, nginx-ingress), le nom de l'opération (par exemple, HTTP GET my-nginx-svc /), les heures de début et de fin, ainsi que la durée. L'onglet Attributes affiche les attributs HTTP tels que http.method, http.status_code, http.host et http.user_agent, ainsi que les informations réseau comme net.host.port.

OpenTracing

Étape 1 : Obtenir les informations sur l'endpoint

Connectez-vous à la console ARMS. Dans le volet de navigation de gauche, cliquez sur Integration Center.
Dans la zone Server-side Applications, cliquez sur la carte Zipkin.

Remarque
Cet exemple utilise Zipkin.
Dans le panneau Zipkin qui s'affiche, sélectionnez la région dans laquelle vous souhaitez envoyer les données.
Notez les informations sur l'endpoint. Pour Connection Method, sélectionnez Alibaba Cloud Intranet. La page affiche deux URL d'endpoints réseau VPC : un endpoint v2 et un endpoint v1. Copiez l'URL de l'endpoint v1 pour une utilisation ultérieure.

Remarque
Utilisez l'endpoint réseau VPC si votre NGINX Ingress Controller est déployé dans la même région Alibaba Cloud que Managed Service for OpenTelemetry. Sinon, utilisez l'endpoint public.

Étape 2 : Activer OpenTracing sur NGINX Ingress ControllerManaged 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 Configurations > ConfigMaps.
Sur la page ConfigMaps, définissez Namespace sur kube-system. Recherchez le ConfigMap nginx-configuration et cliquez sur Actions dans la colonne Edit.

Dans le panneau Edit, cliquez sur Add pour ajouter les paires clé-valeur suivantes, puis cliquez sur OK.

Paramètre	Description	Valeur	Exemple
enable-opentracing	Indique si le traçage est activé.	true : active le traçage. false : désactive le traçage.	true
zipkin-service-name	Nom du service.	Un nom personnalisé.	nginx-ingress
zipkin-collector-host	Nom de domaine de l'endpoint de rapport.	Modifiez l'URL de l'endpoint obtenue à l'étape 1 : Obtenir les informations sur l'endpoint. Supprimez le préfixe `http://` et ajoutez un point d'interrogation (?) à la fin. Par exemple : Endpoint 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 entrantes provenant d'autres services ou systèmes.	true : fait confiance aux traces entrantes. false : ne fait pas confiance aux traces entrantes.	true
zipkin-sample-rate	Taux d'échantillonnage.	Une valeur comprise entre 0 et 1, avec un maximum de deux décimales. Une valeur de 0 signifie qu'aucun échantillonnage n'est effectué, et une valeur de 1 signifie que toutes les données sont échantillonnées.	0.1

Étape 3 : Consulter les traces dans la console ARMS

Connectez-vous à la console ARMS. Dans le volet de navigation de gauche, cliquez sur Application Monitoring > Application List.
Sur la page Application List, sélectionnez une région dans la liste déroulante en haut de la page. Cliquez ensuite 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 Interface Invocation.
- L'onglet Overview affiche la topologie du service et les relations d'appel pour l'application actuelle. Les autres onglets disponibles incluent Upstream, Downstream et Traces.
- L'onglet Traces répertorie jusqu'à 100 des traces les plus longues de l'application. Pour plus d'informations sur les données de trace, consultez la rubrique Interface Invocation. Le tableau comprend des colonnes telles que Time, span name, Host/IP, Duration, Status, TraceId et Actions. Vous pouvez filtrer les résultats par Duration greater than et Exception.
- Sous l'onglet Traces, cliquez sur un TraceId pour afficher les détails de la trace. La page Trace Details montre le TraceId, l'heure de début et la durée totale. Elle affiche également un graphique en cascade qui visualise la hiérarchie et la durée relative de chaque span. Par exemple, une requête vers /api/currency peut passer par des services tels que nginx-otlp, frontendproxy, frontend et currencyservice, avec une durée totale d'environ 15 ms. Chaque span est représentée par une barre horizontale indiquant sa durée par rapport à l'ensemble de la trace.

(Facultatif) Changer le propagateur OpenTelemetry

Par défaut, lors de l'utilisation de la méthode OpenTelemetry, le contrôleur NGINX Ingress propage le contexte de trace au format W3C Trace Context. Si vos applications frontend et backend utilisent d'autres formats de contexte, tels que B3 (utilisé par Zipkin) ou Jaeger, vous devez modifier le propagateur afin de garantir que les traces soient correctement liées entre tous les services. Cette section explique comment changer le propagateur pour le contrôleur NGINX Ingress.

Ajoutez la variable d'environnement OTEL_PROPAGATORS en utilisant la même méthode décrite à l'étape 2.4 de la procédure OpenTelemetry. Enregistrez ensuite la configuration et redéployez nginx-ingress-controller.

Variable d'environnement

Valeur

Description

OTEL_PROPAGATORS

tracecontext,baggage,b3,jaeger

Liste de propagateurs à utiliser, séparés par des virgules. Pour plus d'informations, consultez la rubrique Spécifier le format des en-têtes de propagation pour OpenTelemetry.

Ensuite, modifiez la configuration main-snippet comme décrit à l'étape 2.7 de la procédure OpenTelemetry 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 rubrique Qu'est-ce que Managed Service for OpenTelemetry ?.
Pour plus d'informations sur ACK, consultez la rubrique Qu'est-ce que Container Service for Kubernetes (ACK) ?.
Les clés requises dans le ConfigMap nginx-configuration varient selon l'outil de traçage utilisé (par exemple, Zipkin, Jaeger ou SkyWalking). Pour plus d'informations sur la connexion à Managed Service for OpenTelemetry, consultez la rubrique Préparatifs.