Tutoriel : configurez OpenTelemetry pour vos applications avec NGINX

Akash AnanthanarayananResponsable marketing technique | F5 NGINX

Si vous recherchez un outil permettant de tracer plus efficacement les applications web et l’infrastructure, OpenTelemetry pourrait bien répondre à vos besoins. En instrumentant votre serveur NGINX avec le module communautaire OpenTelemetry pour NGINX existant, vous pouvez collecter des métriques, des traces et des journaux afin de mieux surveiller l’état de votre serveur. Vous pouvez ainsi résoudre les problèmes et optimiser vos applications web pour améliorer leurs performances. Toutefois, ce module communautaire peut également ralentir les temps de réponse de votre serveur en raison de la surcharge de performances nécessaire au traçage. Ce processus peut aussi consommer des ressources supplémentaires, augmentant ainsi l’utilisation du processeur et de la mémoire. En outre, 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 requêtes et les réponses des applications, offrant ainsi des capacités de suivi améliorées. Il peut être facilement installé et configuré dans les fichiers de configuration NGINX, ce qui le rend particulièrement simple d’utilisation. 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 de NGINX est un module dynamique qui ne nécessite aucun package supplémentaire avec NGINX Plus. Il offre diverses fonctionnalités, notamment les modules d’API et de stockage clé-valeur. Ensemble, ces fonctionnalités constituent une solution complète pour surveiller et optimiser les performances de votre instance NGINX Plus. En utilisant ngx_otel_module, vous pouvez obtenir de précieuses informations sur les performances de votre application web et prendre des mesures pour les améliorer. Nous vous recommandons vivement d’explorer ngx_otel_module afin de découvrir comment il peut vous aider à obtenir de meilleurs résultats.

Remarque : Vous pouvez consulter notre page GitHub pour obtenir des instructions détaillées sur l’installation de nginx_otel_module et sa prise en main.

Présentation du tutoriel

Dans cet article, vous trouverez un guide détaillé expliquant comment configurer OpenTelemetry dans NGINX Plus et utiliser l’outil Jaeger pour collecter et visualiser les traces. OpenTelemetry est un outil puissant qui offre une vue complète du parcours d’une requête, avec notamment des informations précieuses sur la latence, les détails de la requête et les données de réponse. Cela peut s’avérer extrêmement utile pour optimiser les performances et détecter d’éventuels problèmes. Pour simplifier les choses, nous avons installé le module OpenTelemetry, l’application et Jaeger sur une seule et même instance, comme l’illustre le schéma ci-dessous.

Figure 1 : vue d’ensemble de l’architecture OpenTelemetry de NGINX

Suivez les étapes décrites dans ces sections pour terminer le tutoriel :

• 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
• Connaissances de base de la ligne de commande Linux et de JavaScript
• Docker
• Node.js 19.x ou version ultérieure
• cURL

Déployer NGINX Plus et installer le module OpenTelemetry

Le choix d’un environnement approprié est essentiel pour réussir le déploiement d’une instance NGINX. Ce tutoriel vous guidera dans le déploiement de NGINX Plus et l’installation des modules dynamiques NGINX.

1. Installer 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 de NGINX pour activer OpenTelemetry :

load_module modules/ngx_otel_module.so;

1. Rechargez NGINX pour activer le module :

nginx -t && nginx -s reload

Déployer Jaeger et l’application « echo »

Plusieurs options permettent de consulter 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 la 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 le répertoire de votre choix.

version: '3'

Services:
  jaeger:
    image: jaegertracing/all-in-one:1.41
    container_name: jaeger
    ports:
      - "16686:16686"
      - "4317:4317"
      - "4318:4318"
    environment:
      COLLECTOR_OTLP_ENABLED: true

  http-echo:
    image: mendhak/http-https-echo
    environment:
        - HTTP_PORT=8888
        - HTTPS_PORT=9999
    ports:
        - "4500:8888" 
        - "8443:9999"

1. Pour installer la solution de traçage tout-en-un Jaeger et l’application « http-echo », exécutez cette commande :

'docker-compose up -d'

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

$docker ps -a
CONTAINER ID   IMAGE                           COMMAND                  CREATED        STATUS
PORTS                                                                                                                                                                   NAMES

5cb7763439f8   jaegertracing/all-in-one:1.41   "/go/bin/all-in-one-…"   30 hours ago   Up 30 hours   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…"   11 days ago    Up 30 hours   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 saisissant simplement l’adresse http://localhost:16686 dans votre navigateur. Notez qu’il est possible qu’aucune donnée de traçage du système ne s’affiche immédiatement, car elle est actuellement envoyée à la console. Mais pas d’inquiétude ! Nous pouvons rapidement résoudre ce problème en exportant les traces au format OpenTelemetry Protocol (OTLP). Vous apprendrez à le faire dans la section suivante, lorsque nous configurerons NGINX pour envoyer les traces à Jaeger.

Configurer OpenTelemetry dans NGINX pour le traçage

Cette section vous expliquera pas à pas comment configurer la directive OpenTelemetry dans NGINX Plus à l’aide d’un magasin clé-valeur. Cette configuration puissante permet de surveiller et d’analyser précisément le trafic afin d’optimiser les performances de votre application. À la fin de cette section, vous saurez comment utiliser le module OpenTelemetry de NGINX pour suivre les performances de votre application.

La mise en place et la configuration de la collecte des données de télémétrie sont très simples avec les fichiers de configuration NGINX. Grâce à ngx_otel_module, les utilisateurs disposent d’un outil de traçage robuste et sensible aux protocoles, qui permet d’identifier et de résoudre rapidement les problèmes dans les applications. Ce module constitue un ajout précieux à votre ensemble d’outils de développement et de gestion des 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 consulter la documentation de ngx_otel_module documentation.

Directives et variables OpenTelemetry

NGINX propose de nouvelles directives qui peuvent vous aider à optimiser davantage votre déploiement OpenTelemetry en l’adaptant à 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, notamment le point de terminaison, l’intervalle, la taille des lots et le nombre de lots. Ces paramètres sont essentiels à la bonne exportation des données et doivent être définis avec précision.
2. otel_service_name – Définit l’attribut de nom de service de votre ressource OpenTelemetry afin d’en améliorer l’organisation et le suivi.
3. otel_trace – Pour activer ou désactiver le traçage OpenTelemetry, vous pouvez désormais spécifier une variable. Vous bénéficiez ainsi d’une plus grande souplesse dans la gestion de vos paramètres de traçage.
4. otel_span_name – Par défaut, le nom du segment OpenTelemetry correspond au nom de l’emplacement associé à une requête. Il convient de noter que ce nom est personnalisable et peut inclure des variables selon les besoins.

Exemples de configuration

Voici quelques exemples de configuration d’OpenTelemetry dans NGINX à l’aide du magasin clé-valeur de NGINX Plus. Le module de magasin clé-valeur de NGINX Plus offre un cas d’usage particulièrement utile en permettant la configuration dynamique des spans et d’autres attributs OpenTelemetry, ce qui simplifie le traçage et le débogage.

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

http {
      keyval "otel.trace" $trace_switch zone=name;

      server {
          location / {
              otel_trace $trace_switch;
              otel_trace_context inject;
              proxy_pass http://backend;
          }

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

Voici maintenant un exemple de désactivation dynamique du traçage OpenTelemetry à l’aide d’un magasin clé-valeur :

location /api {
              api write=off;
          } 

Voici un exemple de configuration des attributs de span OpenTelemetry pour NGINX :

user  nginx;
worker_processes  auto;
load_module modules/ngx_otel_module.so;
error_log /var/log/nginx debug;
pid   /var/run/nginx.pid;


events {
    worker_connections  1024;
}

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

    log_format  main  '$remote_addr - $remote_user [$time_local] "$request" '
                      '$status $body_bytes_sent "$http_referer" '
                      '"$http_user_agent" "$http_x_forwarded_for"';
    include       mime.types;
    default_type  application/json;
    upstream echo {
        server localhost:4500;
        zone echo 64k;
    }
    otel_service_name nginx;
    otel_exporter {
           endpoint localhost:4317;
        }

    server {
       listen       4000;
       otel_trace on;
       otel_span_name otel;
       location /city {
            proxy_set_header   "Connection" "" ;
            proxy_set_header Host $host;
            otel_span_attr demo $trace_attr;
            otel_trace_context inject;
            proxy_pass http://echo;
       }
       location /api {
           api write=on;
       }
       location = /dashboard.html {
        root /usr/share/nginx/html;
    }
       
  }

}

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

nginx -s reload

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

curl -X POST -d '{"otel.span.attr": "<span attribute name>"}' http://localhost:4000/api/6/http/keyvals/<zone name>

Tester la configuration

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

1. Pour générer les données de traçage, commencez par ouvrir une fenêtre de terminal. Saisissez ensuite la commande suivante pour créer les données : $ curl -i localhost:4000/city Le résultat ressemblera à ceci :

                      HTTP/1.1 200 OK
Server: nginx/1.25.3
Date: Wed, 29 Nov 2023 20:25:04 GMT
Content-Type: application/json; charset=utf-8
Content-Length: 483
Connection: keep-alive
X-Powered-By: Express
ETag: W/"1e3-2FytbGLEVpb4LkS9Xt+KkoKVW2I"

{
"path": "/city",
"headers": {
"host": "localhost",
"connection": "close",
"user-agent": "curl/7.81.0",
"accept": "*/*",
"traceparent": "00-66ddaa021b1e36b938b0a05fc31cab4a-182d5a6805fef596-00"
},
"method": "GET",
"body": "",
"fresh": false,
"hostname": "localhost",
"ip": "::ffff:172.18.0.1",
"ips": [],
"protocol": "http",
"query": {},
"subdomains": [],
"xhr": false,
"os": {
"hostname": "e55d9c00a158"
},
"connection": {}

1. Vous devez maintenant vérifier que l’exportateur OTLP fonctionne correctement et que vous pouvez accéder à la trace. Commencez par ouvrir un navigateur et accéder à l’interface utilisateur de Jaeger à l’adresse http://localhost:16686. Une fois la page chargée, cliquez sur le bouton « Rechercher » situé dans la barre de titre. Sélectionnez ensuite le service dont le nom commence par « NGINX » dans le menu déroulant du champ « Service ». Puis, sélectionnez l’opération nommée « Otel » dans le menu déroulant « Opération ». Pour faciliter l’identification d’éventuels problèmes, cliquez sur le bouton « Rechercher des traces » afin de visualiser la trace.

Figure 2 : tableau de bord Jaeger

1. Pour accéder à une analyse plus détaillée et complète d’une trace spécifique, cliquez sur l’une des traces disponibles. Vous obtiendrez ainsi de précieuses informations sur la trace sélectionnée. Dans la trace ci-dessous, vous pouvez examiner à la fois l’attribut de span de la directive OpenTelemetry et celui de la partie sans directive de la trace, afin de mieux comprendre les données présentées.
   • demo – OTel – nom de l’attribut de span OpenTelemetry
   • Champ http.status_code – 200 – Indique que la création a réussi
   • otel.library.name – nginx – Nom du service OpenTelemetry

Figure 3 : analyse détaillée de la trace OpenTelemetry

Sous « Tags », vous pouvez voir les attributs suivants :

Conclusion

NGINX prend désormais en charge OpenTelemetry de manière native, une avancée majeure pour le traçage des requêtes et des réponses dans les environnements applicatifs complexes. Cette fonctionnalité simplifie le processus et garantit une intégration fluide, ce qui permet aux développeurs de surveiller et d’optimiser leurs applications beaucoup plus facilement.

Bien que le module OpenTracing, introduit dans NGINX Plus R18, soit désormais obsolète et qu’il soit supprimé à partir de NGINX Plus R34, il restera disponible dans toutes les versions de NGINX Plus jusque-là. Il est toutefois recommandé d’utiliser le module OpenTelemetry, qui a été introduit dans NGINX Plus R29.

Si vous découvrez NGINX Plus, vous pouvez commencer votre essai gratuit de 30 jours dès aujourd’hui ou nous contacter pour discuter de vos cas d’utilisation.

À propos de l’auteur

Akash AnanthanarayananResponsable marketing technique | F5 NGINX

Autres articles de Akash Ananthanarayanan