Tutoriel : Configurer OpenTelemetry pour vos applications à l'aide de NGINX

Si vous recherchez un outil pour tracer plus efficacement les applications et l'infrastructure Web, OpenTelemetry pourrait être exactement ce dont vous avez besoin. En instrumentant votre serveur NGINX avec le module communautaire OpenTelemetry NGINX existant, vous pouvez collecter des métriques, des traces et des journaux et obtenir une meilleure visibilité sur la santé de votre serveur. Cela vous permet à son tour de résoudre les problèmes et d’optimiser vos applications Web pour de meilleures performances. Cependant, ce module communautaire existant peut également ralentir les temps de réponse de votre serveur en raison de la surcharge de performances qu'il nécessite pour le traçage. Ce processus peut également consommer des ressources supplémentaires, augmentant ainsi l’utilisation du processeur et de la mémoire. De plus, l’installation et la configuration du module peuvent s’avérer fastidieuses.

NGINX a récemment développé un module OpenTelemetry natif, ngx_otel_module , qui révolutionne le traçage des performances de traitement des requêtes. Le module utilise des appels de télémétrie pour surveiller les demandes et les réponses des applications, permettant ainsi des capacités de suivi améliorées. Le module peut être facilement installé et configuré dans les fichiers de configuration NGINX, ce qui le rend très convivial. Ce nouveau module répond aux besoins des utilisateurs de NGINX OSS et de NGINX Plus. Il prend en charge la propagation de contexte W3C et le protocole d'exportation OTLP/gRPC, ce qui en fait une solution complète pour optimiser les performances.

Le module OpenTelemetry natif NGINX est un module dynamique qui ne nécessite aucun packaging supplémentaire avec NGINX Plus. Il offre une gamme de fonctionnalités, notamment l'API et les modules de stockage clé-valeur. Ces fonctionnalités fonctionnent ensemble pour fournir une solution complète de surveillance et d’optimisation des performances de votre instance NGINX Plus. En utilisant ngx_otel_module , vous pouvez obtenir des informations précieuses sur les performances de votre application Web et prendre des mesures pour les améliorer. Nous vous recommandons vivement d'explorer ngx_otel_module pour découvrir comment il peut vous aider à obtenir de meilleurs résultats.

Note: Vous pouvez vous rendre sur notre page GitHub pour obtenir des instructions détaillées sur la façon d'installer nginx_otel_module et de commencer.

Présentation du didacticiel

Dans ce blog, vous pouvez suivre un guide étape par étape sur la configuration d'OpenTelemetry dans NGINX Plus et l'utilisation de l'outil Jaeger pour collecter et visualiser les traces. OpenTelemetry est un outil puissant qui offre une vue complète du chemin d'une requête, y compris des informations précieuses telles que la latence, les détails de la requête et les données de réponse. Cela peut être incroyablement utile pour optimiser les performances et identifier les problèmes potentiels. Pour simplifier les choses, nous avons configuré le module OpenTelemetry, l'application et Jaeger dans une seule instance, comme vous pouvez le voir dans le diagramme ci-dessous.

Suivez les étapes de ces sections pour terminer le didacticiel :

• Prérequis
• Déployer NGINX Plus et installer le module OpenTelemetry
• Déployer Jaeger et l'application echo
• Configurer OpenTelemetry dans NGINX pour le traçage
• Tester la configuration

Prérequis

• Un environnement Linux/Unix ou tout autre environnement compatible
• Un abonnement NGINX Plus
• Connaissance de base de la ligne de commande Linux et de JavaScript
• Docker
• Node.js 19.x ou version ultérieure
• Boucle

Déployer NGINX Plus et installer le module OpenTelemetry

La sélection d’un environnement approprié est essentielle pour déployer avec succès une instance NGINX. Ce didacticiel vous guidera dans le déploiement de NGINX Plus et l'installation des modules dynamiques NGINX.

1. Installez NGINX Plus sur un système d’exploitation pris en charge .
2. Installez ngx_otel_module . Ajoutez le module dynamique au répertoire de configuration NGINX pour activer OpenTelemetry :

charger_module modules/ngx_otel_module.so;

3. Rechargez NGINX pour activer le module :

nginx -t && nginx -s recharger

Déployer Jaeger et l'application echo

Différentes options sont disponibles pour visualiser les traces. Ce tutoriel utilise Jaeger pour collecter et analyser les données OpenTelemetry. Jaeger fournit une interface efficace et conviviale pour collecter et visualiser les données de traçage. Après la collecte des données, vous déploierez mendhak/http-https-echo , une application Docker simple. Cette application renvoie les attributs de requête pour JavaScript au format JSON.

1. Utilisez docker-compose pour déployer Jaeger et l'application http-echo . Vous pouvez créer un fichier docker-compose en copiant la configuration ci-dessous et en l'enregistrant dans un répertoire de votre choix.

    

   version: '3'
   
   Services :
   jaeger :
   image : jaegertracing/all-in-one:1.41
   nom_conteneur : jaeger
   ports :
   - « 16686 : 16686 »
   - « 4317 : 4317 »
   - « 4318 : 4318 »
   environnement :
         COLLECTOR_OTLP_ENABLED : true
   
   http-echo :
   image : mendhak/http-https-echo
   environnement :
   - HTTP_PORT=8888
   - HTTPS_PORT=9999
   ports :
   - « 4500:8888 » 
   - « 8443:9999 »
   

2. Pour installer l'application de traçage et d'écho http tout-en-un Jaeger. Exécutez cette commande :

'docker-compose up -d'

3. Exécutez la commande docker ps -a pour vérifier si le conteneur est installé.

$docker ps -a
ID CONTAINER IMAGE COMMANDE CRÉÉE STATUT
NOMS DES PORTS

5cb7763439f8 jaegertracing/all-in-one:1.41 "/go/bin/all-in-one-…" il y a 30 heures En ligne depuis 30 heures 5775/udp, 5778/tcp, 14250/tcp, 0.0.0.0:4317-4318->4317-4318/tcp, :::4317-4318->4317-4318/tcp, 0.0.0.0:16686->16686/tcp, :::16686->16686/tcp, 6831-6832/udp, 14268/tcp jaeger

e55d9c00a158 mendhak/http-https-echo "docker-entrypoint.s…" il y a 11 jours Up 30 heures 8080/tcp, 8443/tcp, 0.0.0.0:8080->8888/tcp, :::8080->8888/tcp, 0.0.0.0:8443->9999/tcp, :::8443->9999/tcp ubuntu-http-echo-1

Vous pouvez désormais accéder à Jaeger en tapant simplement le point de terminaison http://localhost:16686 dans votre navigateur. Notez que vous ne pourrez peut-être pas voir immédiatement les données de trace du système, car elles sont actuellement envoyées à la console. Mais ne vous inquiétez pas ! Nous pouvons résoudre rapidement ce problème en exportant les traces au format OpenTelemetry Protocol (OTLP). Vous apprendrez à faire cela dans la section suivante lorsque nous configurerons NGINX pour envoyer les traces à Jaeger.

Configurer OpenTelemetry dans NGINX pour le traçage

Cette section vous montrera étape par étape comment configurer la directive OpenTelemetry dans NGINX Plus à l'aide d'un magasin clé-valeur. Cette configuration puissante permet une surveillance et une analyse précises du trafic, vous permettant d'optimiser les performances de votre application. À la fin de cette section, vous aurez une solide compréhension de l’utilisation du module NGINX OpenTelemetry pour suivre les performances de votre application.

La configuration et l'installation de la collecte de télémétrie sont un jeu d'enfant avec les fichiers de configuration NGINX. Avec ngx_otel_module , les utilisateurs peuvent accéder à un outil de traçage robuste et compatible avec le protocole qui peut aider à identifier et à résoudre rapidement les problèmes dans les applications. Ce module est un ajout précieux à votre ensemble d'outils de développement et de gestion d'applications et vous aidera à améliorer les performances de vos applications. Pour en savoir plus sur la configuration d'autres exemples de configurations OpenTelemetry, veuillez vous référer à la documentation ngx_otel_module documentation .

Directives et variables OpenTelemetry

NGINX dispose de nouvelles directives qui peuvent vous aider à réaliser un déploiement OpenTelemetry encore plus optimisé, adapté à vos besoins spécifiques. Ces directives ont été conçues pour améliorer les performances de votre application et la rendre plus efficace que jamais.

Directives du module :

1. otel_exporter – Définit les paramètres des données OpenTelemetry, y compris le point de terminaison , l'intervalle , la taille du lot et le nombre de lots . Ces paramètres sont essentiels pour l’exportation réussie des données et doivent être définis avec précision.
2. otel_service_name – Définit l’attribut de nom de service pour votre ressource OpenTelemetry afin d’améliorer l’organisation et le suivi.
3. otel_trace – Pour activer ou désactiver le traçage OpenTelemetry, vous pouvez désormais le faire en spécifiant une variable. Cela offre une flexibilité dans la gestion de vos paramètres de traçage.
4. otel_span_name – Le nom de l’étendue OpenTelemetry est défini comme nom d’emplacement pour une demande par défaut. Il convient de noter que le nom est personnalisable et peut inclure des variables selon les besoins.

Exemples de configuration

Voici quelques exemples de façons dont vous pouvez configurer OpenTelemetry dans NGINX à l'aide du magasin de clés-valeurs NGINX Plus. Le module de stockage clé-valeur NGINX Plus offre un cas d'utilisation précieux qui permet la configuration dynamique de l'étendue OpenTelemetry et d'autres attributs OpenTelemetry, simplifiant ainsi le processus de traçage et de débogage.

Voici un exemple d'activation dynamique du traçage OpenTelemetry à l'aide d'un magasin clé-valeur :

http {
valeur clé "otel.trace" $trace_switch zone=nom;

serveur {
emplacement / {
otel_trace $trace_switch;
otel_trace_context inject;
proxy_pass http://backend;
}

emplacement /api {
api write=on;
} 
}
}

Ensuite, voici un exemple de désactivation dynamique du traçage OpenTelemetry à l’aide d’un magasin de clés-valeurs :

emplacement /api {
api write=off;
} 

Voici un exemple de configuration d’attribut span NGINX OpenTelemetry :

utilisateur nginx ;
processus_travailleurs auto ;
module_chargement modules/ngx_otel_module.so ;
journal_erreurs /var/log/nginx débogage ;
pid /var/run/nginx.pid ;

événements {
connexion_travailleur 1024 ;
}

http {
keyval "otel.span.attr" $trace_attr zone=demo ;
keyval_zone zone=demo:64k état=/var/lib/nginx/state/demo.keyval ;

format_journal principal '$remote_addr - $remote_user [$time_local] "$request" '
'$status $body_bytes_sent "$http_referer" '
'"$http_user_agent" "$http_x_forwarded_for"' ;
inclure mime.types ;
type_par_défaut application/json ;
echo en amont {
serveur localhost:4500;
zone echo 64k;
}
otel_service_name nginx;
otel_exporter {
endpoint localhost:4317;
}

serveur {
écoute 4000;
otel_trace activé;
otel_span_name otel;
emplacement /ville {
proxy_set_header "Connexion" "" ;
proxy_set_header Hôte $host;
otel_span_attr démo $trace_attr;
otel_trace_context inject;
proxy_pass http://echo;
}
emplacement /api {
api write=on;
}
emplacement = /dashboard.html {
racine /usr/share/nginx/html;
}

}

}

Pour enregistrer la configuration et redémarrer NGINX, saisissez ce code :

nginx -s recharger

Enfin, voici comment ajouter l’attribut span dans l’API NGINX Plus :

curl -X POST -d '{"otel.span.attr": "<nom de l'attribut span>"}' http://localhost:4000/api/6/http/keyvals/<nom de la zone>

Tester la configuration

Vous pouvez maintenant tester votre configuration en suivant les étapes ci-dessous.

1. Pour générer les données de trace, commencez par ouvrir votre fenêtre de terminal. Ensuite, tapez cette commande pour créer les données :

    

   $ curl -i localhost:4000/ville

   Le résultat ressemblera à ceci :

                         HTTP/1.1 200 OK
   Serveur : nginx/1.25.3
   Date : Mercredi 29 novembre 2023 20:25:04 GMT
   Content-Type: application/json; charset=utf-8
   Content-Length: 483
   Connexion : keep-alive
   X-Powered-By : Express
   ETag : W/"1e3-2FytbGLEVpb4LkS9Xt+KkoKVW2I"
   
   {
   "chemin": "/ville",
   "en-têtes": {
   "hôte": "localhost",
   "connexion": "fermer",
   "agent utilisateur": "curl/7.81.0",
   "accepter": "*/*",
   "traceparent": "00-66ddaa021b1e36b938b0a05fc31cab4a-182d5a6805fef596-00"
   },
   "méthode": "GET",
   "body": "",
   "fresh": false,
   "hostname": "localhost",
   "ip": "::ffff:172.18.0.1",
   "ips": [],
   "protocol": "http",
   "query": {},
   "subdomains": [],
   "xhr": false,
   "os": {
   "hostname": "e55d9c00a158"
   },
   "connection": {}
   

2. Vous souhaitez maintenant vous assurer que l’exportateur OTLP fonctionne correctement et que vous pouvez accéder à la trace. Commencez par ouvrir un navigateur et accédez à l'interface utilisateur Jaeger à l'adresse http://localhost:16686 . Une fois la page chargée, cliquez sur le bouton Rechercher , situé dans la barre de titre. À partir de là, sélectionnez le service qui démarre par NGINX dans le menu déroulant du champ Service . Sélectionnez ensuite l’opération nommée Hôtel dans le menu déroulant appelé Opération . Pour faciliter l’identification des problèmes, cliquez sur le bouton Rechercher des traces pour visualiser la trace.



3. Pour accéder à une analyse plus détaillée et complète d’une trace spécifique, cliquez sur l’une des traces individuelles disponibles. Cela vous fournira des informations précieuses sur la trace que vous avez sélectionnée. Dans la trace ci-dessous, vous pouvez consulter à la fois l'attribut span de la directive OpenTelemetry et la non-directive de la trace, vous permettant de mieux comprendre les données disponibles.
   • démo – OTel – Nom de l'attribut span d'OpenTelemetry
   • Champ http.status_code – 200 – Indique une création réussie
   • otel.library.name – nginx – nom du service OpenTelemetry

Sous Tags, vous pouvez voir les attributs suivants :

Conclusion

NGINX dispose désormais d'un support intégré pour OpenTelemetry, une évolution significative pour le traçage des requêtes et des réponses dans des environnements d'application complexes. Cette fonctionnalité rationalise le processus et garantit une intégration transparente, ce qui permet aux développeurs de surveiller et d'optimiser beaucoup plus facilement leurs applications.

Bien que le module OpenTracing introduit dans NGINX Plus R18 soit désormais obsolète et sera supprimé à partir de NGINX Plus R34, il sera toujours disponible dans toutes les versions de NGINX Plus jusqu'à cette date. Cependant, il est recommandé d'utiliser le module OpenTelemetry, qui a été introduit dans NGINX Plus R29 .

Si vous êtes nouveau sur NGINX Plus, vous pouvez démarrer votre essai gratuit de 30 jours dès aujourd'hui ou nous contacter pour discuter de vos cas d'utilisation .