Surveillance de NGINX

NGINX Le capteur et le traçage d' NGINX s ont des exigences différentes en matière de système d'exploitation.

Pour le capteur d' NGINX, les systèmes d'exploitation pris en charge correspondent aux exigences des agents hôtes; vous pouvez les consulter dans la section « Systèmes d'exploitation pris en charge » de chaque agent hôte, par exemple « Systèmes d'exploitation pris en charge pour Linux ».

Pour le traçage d' NGINX, les systèmes d'exploitation suivants sont pris en charge :

La version 1.12.0 et les versions ultérieures du capteur CPP ne prennent plus en charge Debian 10 et Ubuntu 20.04.

Les versions 1.11.0 et ultérieures de CPP Sensor ne prennent plus en charge CentOS 7, CentOS 8, CentOS Stream 8, Alpine 3.10 et RHEL 7.

NGINX Le capteur et le traçage d' NGINX s ont des exigences différentes en matière de version et de plateforme. Pour plus d'informations, consultez la section « Versions et plateformes prises en charge d' NGINX ».

Le tableau suivant présente la dernière version prise en charge et la politique d'assistance :

Pour plus d'informations sur la politique d'assistance, consultez la section « Stratégie d'assistance pour les capteurs ».

Les images de conteneurs Docker suivantes sont prises en charge pour le traçage d' NGINX :

À partir de la version 1.12.0, le capteur CPP ne prend plus en charge les images de openresty/openresty CentOS basedconteneur.

Pour que Instana collecte et surveille automatiquement les processus de votre NGINX, vous devez activer la collecte des métriques comme suit :

• PID
• Nombre de processus worker
• Nombre de connexions worker
• Démarré à
• Version
• Génération (*)
• Adresse (*)
• Génération (*)
• PPID (*)

• Demande
• Connexions
• Processus (*)
• SSL (*)
• Caches (*)
• Zones de serveur (*)
• Flux amont (*)

Chaque détecteur dispose d'une base de connaissances organisée de signatures de santé qui sont évaluées en continu par rapport aux métriques entrantes et qui sont utilisées pour signaler des problèmes ou des incidents qui dépendent de l'impact sur l'utilisateur.

Les événements intégrés déclenchent des problèmes ou des incidents en cas de non-conformité des signatures de santé des entités, tandis que les événements personnalisés déclenchent des problèmes ou des incidents en fonction des seuils d'une métrique spécifique à une entité donnée.

Pour plus d'informations sur les événements intégrés du capteur « NGINX », consultez la référence sur les événements intégrés.

Pour utiliser le traçage d' NGINX, vous devez définir les valeurs de configuration suivantes :

• Ajoutez les éléments suivants dans le fichier « ConfigMap » pour l'entrée « NGINX » :

    data:
      enable-opentracing: "true"
      zipkin-collector-host: $HOST_IP
      zipkin-collector-port: "42699"
   

• Ajoutez les variables d'environnement suivantes dans la spécification du pod « NGINX » (celle-ci devrait déjà POD_NAME contenir et POD_NAMESPACE) :

  env:
     - name: HOST_IP
       valueFrom:
       fieldRef:
           fieldPath: status.hostIP
   

Remarques :

• L' NGINX d'Ingress définit automatiquement les variables d'environnement POD_NAMEPOD_NAMESPACE et. Vous n'avez donc pas besoin d'ajouter les variables d'environnement POD_NAMEPOD_NAMESPACE et à la spécification du pod NGINX.

• Cette configuration utilise Kubernetes DownwardAPI pour rendre l'adresse IP de l'hôte disponible en tant que variable d'environnement (HOST_IP), et ConfigMap la prend en compte.

• Le port peut être défini sur 42699, qui est le port de l'agent d' Instana.

• Le service est nommé nginx par défaut ou doit être remplacé par le paramètre zipkin-service-name, qui peut être configuré dans ConfigMap.

Pour plus d'informations sur Ingress d' NGINX, consultez la documentation d'Ingress d' Kubernetes NGINX.

Pour installer le suivi « NGINX » dans votre configuration, procédez comme suit :

1. Téléchargez les fichiers binaires adaptés à votre version d' NGINX.
2. Copiez les fichiers binaires à un emplacement accessible par votre serveur d' NGINX.
3. Modifiez les paramètres d' NGINX.
4. Redémarrez le processus « NGINX » ou provoquez un rafraîchissement de la configuration en envoyant une reload commande

Pour configurer le traçage sans serveur pour l' NGINX, procédez comme suit :

1. Téléchargez les fichiers binaires d' Instana s pour le traçage sans serveur, en fonction de la version d' NGINX dont vous disposez. Les modules de traçage de l' NGINX HTTP s'appuient sur le nginx-opentracing module. La variante « Instana » a été personnalisée pour offrir une meilleure ergonomie, des corrections de bogues spécifiques et davantage de fonctionnalités. Pour les fichiers binaires d' Instana, consultez la page « Fichiers binaires de traçage distribué » à l'adresse NGINX.

2. Copier les fichiers binaires pour serverless-tracing :

   1. À partir des fichiers binaires téléchargés et extraits à l'étape 1, sélectionnez la variante OpenSSL du module " libinstana_sensor.so en fonction de la version. Récupérez la version d'OpenSSL en utilisant la commande 'openssl version. Un exemple de sortie d'OpenSSL 3.0.2 est présenté dans l'exemple suivant :

      # openssl version
      OpenSSL 3.0.2 15 Mar 2022 (Library: OpenSSL 3.0.2 15 Mar 2022)
       

      Pour OpenSSL 3.x.x, sélectionnez le module " libinstana_sensor_ssl3x.so.

      • Un exemple de sortie d'OpenSSL 1.1.1f est présenté dans l'exemple suivant :

        # openssl version
        OpenSSL 1.1.1f  31 Mar 2020
         

        Pour OpenSSL 1.1.x, sélectionnez le module " libinstana_sensor_ssl1.1x.so.

   2. Placez-le sur un système de fichiers accessible au processus « NGINX ». Le processus « NGINX » nécessite un droit de lecture sur libinstana_sensor.so.

   3. Si NGINX s'exécute directement sur le système d'exploitation hôte, et non dans un conteneur, copiez les deux binaires Instana dans le répertoire contenant les autres modules d' NGINX.

   4. Déterminez l'emplacement dans lequel NGINX recherche les modules, exécutez la nginx -V commande et recherchez l'option --modules-path de configuration.

   5. Effectuez l'une des étapes suivantes :

      • Dans un environnement conteneurisé, ajoutez ces fichiers à l'image du conteneur ou montez-les en tant que volumes dans votre conteneur.
      • Pour les points de montage d' docker, consultez la page Docker consacrée aux montages liés.
      • Pour plus d' Kubernetes s, consultez la section « Monter des volumes dans des pods » sur Kubernetes.

3. Définissez les variables d'environnement.

   1. Recherchez le fichier de service « NGINX » qui apparaît dans la sortie de la systemctl show -p FragmentPath nginx commande. Un exemple de sortie est présenté dans l'exemple suivant :

      # systemctl show -p FragmentPath nginx
      FragmentPath=/lib/systemd/system/nginx.service
       

   2. Dans le fichier de service d' NGINX, ajoutez les variables d'environnement INSTANA_ENDPOINT_URL et INSTANA_AGENT_KEY dans la Service section. Pour plus d'informations sur les variables d'environnement, consultez la section « Variables d'environnement pour la surveillance sans serveur ».

   3. Remplacez " INSTANA_ENDPOINT_URL et " INSTANA_AGENT_KEY par les valeurs réelles, comme indiqué dans l'exemple suivant :

      [Service]
      Environment="INSTANA_ENDPOINT_URL=https://XXX.instana.io/serverless/"
      Environment="INSTANA_AGENT_KEY=*****"
       

4. Modifiez la configuration d' NGINX pour le traçage sans serveur :

   1. Renommez " libinstana_sensor_ssl1.1x.so ou " libinstana_sensor_ssl3x.so en " libinstana_sensor.so ou mettez à jour la ligne " opentracing_load_tracer /usr/local/lib/libinstana_sensor.so /etc/instana-config.json; dans le fichier " nginx.conf en fonction du nom du module extrait requis.

   2. Ajoutez les lignes 'env INSTANA_ENDPOINT_URL; et 'env INSTANA_AGENT_KEY; dans le fichier 'nginx.conf pour autoriser ces variables d'environnement.

      # The following line adds the basic module Instana uses to get tracing data.
      # It is required that you use the version of this module built by Instana,
      # rather than the one shipped in many NGINX distros, as there are some
      # modifications in the Instana version that are required for tracing to work
      load_module modules/ngx_http_opentracing_module.so;
      
      # Whitelists environment variables used for tracer configuration to avoid
      # that NGINX wipes them. This is only needed if instana-config.json
      # should contain an empty configuration with "{}" inside to do the
      # configuration via these environment variables instead.
      env INSTANA_SERVICE_NAME;
      env INSTANA_AGENT_HOST;
      env INSTANA_AGENT_PORT;
      env INSTANA_MAX_BUFFERED_SPANS;
      env INSTANA_DEV;
      # Serverless tracing:
      env INSTANA_ENDPOINT_URL;
      env INSTANA_AGENT_KEY;
      
      events {}
      
      error_log /dev/stdout info;
      
      http {
      error_log /dev/stdout info;
      
      # The following line loads the Instana libsinstana_sensor library, that
      # gets the tracing data from ngx_http_opentracing_module.so and converts
      # them to Instana AutoTrace tracing data.
      # The content of instana-config.json is discussed as follows.
      opentracing_load_tracer /usr/local/lib/libinstana_sensor.so /etc/instana-config.json;
       

5. Redémarrez le processus « NGINX » ou provoquez un rechargement de la configuration en exécutant la reload commande.

Le webhook Instana AutoTrace permet de configurer automatiquement le traçage distribué pour NGINX sur Kubernetes et Red Hat OpenShift, avec les restrictions suivantes :

• Instana AutoTrace Webhook ne prend en charge que la version NGINX 1.19 ou une version ultérieure.
• Instana AutoTrace Le webhook ne prend pas encore en charge l' OpenResty.
• Instana AutoTrace Webhook ne prend pas en charge l'utilisation d'un ConfigMap avec NGINX en mode autonome.

Pour plus d'informations, consultez la section « Activation de l'instrumentation des webhooks pour NGINX et ingress-nginx ».

Le webhook Instana AutoTrace permet de configurer automatiquement le traçage distribué pour les points d'entrée NGINX et NGINX sur Kubernetes et Red Hat OpenShift. Le webhook intègre automatiquement les extraits de configuration et les binaires de traçage mentionnés précédemment dans la configuration des conteneurs NGINX et Ingress NGINX lorsque la fonctionnalité de traçage automatique pour NGINX est activée.

L'interface d'entrée Kubernetes NGINX permet le traçage distribué via le projet OpenTracing. Comme l'agent Instana est capable d'ingérer également des traces Jaeger et Zipkin, il est possible de configurer NGINX Ingress de sorte que les traces soient transmises à Instana.

Pour désactiver le traçage d' NGINX, supprimez les directives load_module, opentracing_load_traceropentracing_propagate_context , et, ainsi que les variables d'environnement liées à Instana, telles que INSTANA_SERVICE_NAME ou INSTANA_AGENT_HOST, du fichier de configuration d' NGINX. De plus, supprimez les bibliothèques de traçage et le instana-config.json fichier du répertoire correspondant.

load_module modules/ngx_http_opentracing_module.so;

env INSTANA_SERVICE_NAME;
env INSTANA_AGENT_HOST;
env INSTANA_AGENT_PORT;
env INSTANA_MAX_BUFFERED_SPANS;
env INSTANA_DEV;

opentracing_load_tracer /usr/local/lib/libinstana_sensor.so /etc/instana-config.json;

opentracing_propagate_context;

Le traceur « Instana » envoie ses lignes de journal vers la sortie d'erreur standard de « NGINX ». Ces lignes ont le préfixe [lis].

En cas d'auto-instrumentation avec le webhook « autotrace-mutating-webhook », utilisez les journaux des fichiers binaires impliqués dans l'auto-traçage d' NGINX pour résoudre un problème. Vous pouvez également transmettre ces journaux au service d'assistance d' IBM afin d'obtenir des informations plus détaillées et un meilleur contexte. Deux fichiers binaires interviennent dans l'instrumentation automatique : une bibliothèque libinstana_init et un exécutable watcher_nginx.

• Le fichier journal de libinstana_sensor se trouve dans /tmp/instana/lii_logs/$PID.log.
• Le fichier journal de watcher_nginx se trouve dans /tmp/instana/iwn_logs/$PID.log.

où $PID représente l'ID de processus du processus impliqué.

Le niveau de journalisation est défini sur error par défaut. Pour déployer NGINX avec un niveau de journalisation différent, modifiez ce niveau en configurant les variables d'environnement.

Pour la bibliothèque libinstana_init , définissez la variable d'environnement suivante:

INSTANA_LII_LOG_LEVEL=debug
 

Pour l'exécutable watcher_nginx , définissez la variable d'environnement suivante:

INSTANA_IWN_LOG_LEVEL=debug
 

Vous trouverez les avertissements et les erreurs du capteur « NGINX » dans les journaux du service de l'agent « Instana ». Pour afficher les dernières entrées de journal, exécutez la commande suivante:

systemctl status instana-agent
 

Pour afficher le journal complet du service de l'agent d' Instana, exécutez la commande suivante :

sudo journalctl -xeu instana-agent.service
 

Type de problème de surveillance : nginx_api_not_accessible

Pour résoudre ce problème, suivez les étapes décrites dans la section « Activation de la collecte des métriques » afin de configurer l'agent Instana pour qu'il collecte toutes les métriques d' NGINX.

Type de problème de surveillance : nginx_status_not_accessible

Pour résoudre ce problème, suivez les étapes décrites dans la section « Activation de la collecte des métriques » afin de configurer l'agent Instana pour qu'il collecte toutes les métriques d' NGINX.

Type de problème de surveillance : nginx_api_not_found

Pour résoudre ce problème, suivez les étapes décrites dans la section « Activation de la collecte des métriques » afin de configurer l'agent Instana pour qu'il collecte toutes les métriques d' NGINX.

Type de problème de surveillance : nginx_status_not_found

Pour résoudre ce problème, suivez les étapes décrites dans la section « Activation de la collecte des métriques » afin de configurer l'agent Instana pour qu'il collecte toutes les métriques d' NGINX.

Type de problème de surveillance : nginx_config_location_not_discovered

Pour résoudre ce problème, suivez les étapes décrites dans la section « Activation de la collecte des métriques » afin de configurer l'agent Instana pour qu'il collecte toutes les métriques d' NGINX.

Problème : les requêtes d' HTTP s personnalisées émises à partir du code Lua ne peuvent pas être tracées automatiquement.

$http_traceparentSolution : Pour garantir la continuité de la trace, l'en-tête « W3Ctraceparent » de la requête sortante doit être propagé à partir de la variable « NGINX » correspondante. NGINX Tracer met automatiquement à jour l'identifiant de segment.

Modifiez votre code client HTTP Lua, tel que lua-resty-http, pour inclure la sortie traceparent en-tête de ngx.var.http_traceparent si l'en-tête n'est pas déjà défini et que la variable NGINX est disponible. Pour plus d'informations, consultez le PR 340 de lua-resty-http, le fichier README de lua-resty-http, le fichier README de ngx_core_module et le fichier README de lua-nginx-module.

Voir l'exemple de code Lua suivant:

local http = require "resty.http"
local http_c = http.new()
local response, error = http_c:request_uri(request_url, {
    method = "GET",
})

Ce code peut rester inchangé si la lua-resty-http fonction send_request() (par exemple, située à /usr/local/openresty/luajit/share/lua/5.1/resty/http.lua) est modifiée comme suit :

--- a/http.lua
+++ b/http.lua
@@ -738,6 +738,10 @@ function _M.send_request(self, params)
     if params.version == 1.0 and not headers["Connection"] then
         headers["Connection"] = "Keep-Alive"
     end
+    -- OpenTelemetry support with NGINX tracer in propagation mode
+    if not headers["traceparent"] and ngx.var.http_traceparent then
+        headers["traceparent"] = ngx.var.http_traceparent
+    end

     params.headers = headers
 

Si votre client d' HTTP s Lua est propriétaire et ne prend pas en charge cette fonctionnalité, utilisez la solution de secours suivante :

local http = require "resty.http"
local http_c = http.new()
local req_headers = {}
if ngx.var.http_traceparent then
    req_headers["traceparent"] = ngx.var.http_traceparent
end
local response, error = http_c:request_uri(request_url, {
    method = "GET",
    headers = req_headers,
})

Problème : le capteur « NGINX » détecte un lua-resty-http fichier http.lua qui n'est pas ngx.var.http_traceparent pris en charge.

Solution : appliquez le lua-resty-http correctif décrit dans la section précédente de la documentation et supprimez les solutions de contournement précédemment mises en place pour définir X-INSTANA-T/-S/-L les en-têtes dans votre code Lua.

Problème : les appels vers NGINX ne sont pas tracés, et le fichier d'erreurs NGINX affiche l'erreur suivante :

/etc/nginx/modules/ngx_http_opentracing_module.so: failed to map segment from shared object: Permission denied

Solution : SELinux empêche le processus « NGINX » de lire et de mapper la mémoire du module « OpenTracing », qui est un objet partagé. Pour vérifier que SELinux est responsable de l'erreur, vous pouvez effectuer un test de fumée comme suit:

1. Désactiver SELinux momentanément
2. Redémarrer l' NGINX

En désactivant SELinux et en redémarrant NGINX, le message d'erreur disparaît du journal d'erreurs d' NGINX, ce qui permet à Instana de tracer les appels.

La désactivation de SELinux n'est pas une solution à long terme. Une approche correcte et sûre consiste à créer une politique SELinux qui autorise le processus ` NGINX ` à lire et à mapper la mémoire à partir du module ` OpenTracing `. Vous pouvez trouver le module « OpenTracing » dans le répertoire de configuration « NGINX ». Si le répertoire de configuration d' NGINX est /etc/nginx, alors le module se trouve dans le /etc/nginx/modules répertoire. Votre service d' DevOps s ou informatique doit configurer SELinux. Pour plus d'informations, consultez les ressources en ligne suivantes qui décrivent la configuration de SELinux pour certaines distributions d' Linux s prises en charge par Instana :

• SELinux sur Red Hat
• SELinux sur Debian
• SELinux sur Ubuntu

Pour plus d'informations sur l'intégration d' NGINX s et de SELinux, consultez les pages « Utilisation d' NGINX s » et « NGINX Plus avec SELinux ».

Problème : la propagation du contexte d' OpenTracing ne fonctionne pas pour FastCGI, configuré dans NGINX.

Solution: Remplacez la directive opentracing_propagate_context par la directive opentracing_fastcgi_propagate_context dans chaque bloc de configuration FastCGI .

nginx:1.24.0Problème : certaines images d' NGINX, telles que l'image docker.io, ne sont pas compatibles avec les environnements OpenShift qui utilisent le contexte de sécurité restricted-v2.

Raison :

OpenShift restricted-v2 Ces environnements présentent les limitations suivantes :

• 0Autorisations d'écriture de groupe manquantes : le processus « NGINX » s'exécute sous un utilisateur standard (non root) (par exemple, ID 1000650000 utilisateur et ID groupe ). Par conséquent, tous les fichiers et répertoires devant être modifiés doivent disposer de droits d'écriture pour le groupe. Cela inclut le /etc/nginx/nginx.conf fichier, qui est modifié par le watcher_nginx composant d'autotracing.

• L'escalade des privilèges est bloquée : OpenShift Les environnements restricted-v2 n'autorisent pas l'escalade des privilèges. Étant donné que le pod « NGINX » s'exécute déjà sous un utilisateur standard, la directive user nginx; « NGINX » qui génère un identifiant 101 utilisateur doit être supprimée de la configuration de « NGINX ».

• Toutes les fonctionnalités d' Linux s sont désactivées : par conséquent, l'écoute sur des ports inférieurs à 1024, comme le port 80, entraîne une erreur bind() error 13: permission denied en raison de l'absence de CAP_NET_BIND_SERVICE.

Solution : Pour garantir le bon fonctionnement du traçage automatique d' NGINX :

• Accordez des droits d'écriture au groupe pour chmod -R g+w les données d'exécution et nginx.conf.
• userÉvitez la directive ` NGINX `.
• Évitez d'utiliser des ports inférieurs à 1024.