Maîtriser l'analyse des journaux Nginx pour un dépannage efficace
Nginx est le point d'entrée critique pour des millions de services web, gérant tout, de la diffusion de contenu statique aux opérations complexes de proxy inverse. Lorsque les performances se dégradent ou que les services tombent en panne, les journaux générés par Nginx sont l'outil de diagnostic le plus important. Ils fournissent un historique précis de chaque requête et de chaque accroc opérationnel interne.
Maîtriser l'analyse des journaux Nginx ne consiste pas seulement à visualiser des fichiers ; il s'agit de comprendre les formats de journal, d'identifier les variables clés et d'utiliser des outils efficaces pour corréler les événements et isoler les causes profondes. Ce guide complet vous accompagnera dans l'interprétation des journaux Nginx pour diagnostiquer rapidement des problèmes comme les erreurs 502, les goulots d'étranglement de performance et les schémas de trafic suspects.
1. Fondamentaux des journaux Nginx : Accès vs Erreur
Nginx gère deux types distincts de journaux, chacun remplissant une fonction essentielle et séparée :
1.1 Le journal d'accès (access.log)
Le journal d'accès enregistre les détails de chaque requête traitée par Nginx. Il est vital pour comprendre le comportement des utilisateurs, surveiller le flux de trafic et évaluer les temps de réponse.
Emplacement par défaut : Généralement /var/log/nginx/access.log
Objectif : Suivi des interactions client (requêtes réussies, erreurs client (4xx)).
1.2 Le journal d'erreurs (error.log)
Le journal d'erreurs suit les problèmes internes, les défaillances opérationnelles et les problèmes de communication qui surviennent pendant le cycle de traitement de Nginx. Ce journal est la source définitive pour le dépannage des problèmes de connectivité backend et des erreurs de configuration du serveur.
Emplacement par défaut : Généralement /var/log/nginx/error.log
Objectif : Suivi des erreurs côté serveur, des avertissements et des événements système (erreurs 5xx, échecs d'analyse du fichier de configuration).
Niveaux de gravité du journal d'erreurs
Nginx utilise huit niveaux de gravité. Lors du dépannage, vous voudrez généralement commencer au niveau error ou supérieur. Le niveau de gravité est configuré à l'aide de la directive error_log :
# Set minimum severity level to 'warn'
error_log /var/log/nginx/error.log warn;
| Niveau | Description | Priorité |
|---|---|---|
| crit | Conditions critiques (par exemple, défaillance du système) | La plus élevée |
| error | Une erreur s'est produite qui a empêché le traitement d'une requête | Élevée |
| warn | Quelque chose d'inattendu s'est produit, mais les opérations continuent | Moyenne |
| notice | Condition normale mais significative (par exemple, redémarrage du serveur) | Faible |
| info | Messages informatifs | La plus faible |
2. Personnalisation des journaux d'accès pour l'analyse des performances
Le format de journal d'accès Nginx par défaut, souvent appelé combined, est utile mais manque de variables cruciales de chronométrage des performances. Pour dépanner efficacement la lenteur, vous devez définir un format personnalisé qui capture le temps passé par Nginx à traiter la requête et le temps pris par le serveur amont (upstream).
2.1 Définir un format de journal de performance
Utilisez la directive log_format (généralement définie dans nginx.conf) pour créer un format personnalisé, par exemple timing_log :
log_format timing_log '$remote_addr - $remote_user [$time_local] '
'"$request" $status $body_bytes_sent '
'"$http_referer" "$http_user_agent" '
'$request_time $upstream_response_time';
server {
listen 80;
server_name example.com;
# Apply the custom format here
access_log /var/log/nginx/timing_access.log timing_log;
# ... rest of configuration
}
| Variable | Description | Valeur pour le dépannage |
|---|---|---|
| $request_time | Temps total écoulé entre le premier octet reçu et le dernier octet envoyé. | Les valeurs élevées indiquent un réseau lent, Nginx lent ou un backend lent. |
| $upstream_response_time | Temps passé à attendre la réponse du serveur amont (par exemple, serveur d'application). | Les valeurs élevées ici désignent l'application backend comme le goulot d'étranglement. |
| $status | Code d'état HTTP renvoyé au client. | Essentiel pour filtrer les erreurs (4xx, 5xx). |
Meilleure pratique : Envisagez d'utiliser le formatage de journal JSON. Bien que légèrement plus difficile à lire manuellement, les journaux JSON sont triviaux à analyser pour les systèmes de gestion de journaux centralisés (comme la pile ELK ou Splunk), améliorant considérablement la vitesse de dépannage.
3. Interprétation des entrées du journal d'accès
Une entrée typique utilisant le format personnalisé pourrait ressembler à ceci (avec les valeurs de chronométrage ajoutées à la fin) :
192.168.1.10 - - [10/May/2024:14:30:05 +0000] "GET /api/data HTTP/1.1" 200 450 "-" "Mozilla/5.0" 0.534 0.528
Diagnostic :
- Code d'état (200) : Succès.
- Temps de requête (0,534 s) : Le temps total est d'une demi-seconde.
- Temps amont (0,528 s) : Presque tout le temps a été passé à attendre l'application backend (
0,534 - 0,528 = 0,006 spassés par la surcharge Nginx).
Conclusion : L'application backend est la source de la latence de 500 ms. La configuration Nginx elle-même est efficace.
Dépannage à l'aide des codes d'état
| Plage de codes d'état | Signification | Action typique/Source du journal |
|---|---|---|
| 4xx (Erreurs client) | Le client a envoyé une requête invalide ou non autorisée. | Vérifiez la fréquence élevée dans les journaux d'accès. Recherchez 404 Not Found (fichiers manquants) ou 403 Forbidden (problèmes de permission). |
| 5xx (Erreurs serveur) | Nginx ou un serveur amont n'a pas réussi à satisfaire une requête valide. | Vérifiez immédiatement le journal d'erreurs pour les entrées correspondantes. |
| 502 Bad Gateway | Nginx n'a pas pu obtenir de réponse de l'application amont. | Le journal d'erreurs affichera les détails (Connection Refused, Timeout). |
| 504 Gateway Timeout | Le serveur amont a mis trop de temps à répondre dans les limites de proxy configurées. | Le journal d'erreurs affichera des avertissements de délai d'attente. Ajustez proxy_read_timeout. |
4. Diagnostic des problèmes critiques dans le journal d'erreurs
Lorsqu'une requête entraîne une erreur 5xx, le journal d'accès vous indique seulement que l'erreur s'est produite. Le journal d'erreurs vous dit pourquoi.
Étude de cas : 502 Bad Gateway
Une erreur 502 est l'un des problèmes les plus courants lors de l'utilisation de Nginx comme proxy inverse. Elle indique presque toujours que l'application backend est en panne, surchargée ou inaccessible.
Recherchez ces messages spécifiques dans le journal d'erreurs :
4.1 Connection Refused (Backend Down)
Cela indique que Nginx a essayé de se connecter au port backend, mais que rien n'écoutait, ce qui signifie que le serveur d'application (par exemple, PHP-FPM, Gunicorn) est arrêté ou mal configuré.
2024/05/10 14:35:10 [error] 12345#0: *1 connect() failed (111: Connection refused) while connecting to upstream, client: 192.168.1.10, server: example.com, request: "GET /test"
- Action : Redémarrez le serveur d'application backend ou vérifiez sa configuration (paramètre de port/socket).
4.2 Upstream Prematurely Closed Connection (Plantages du Backend)
Cela se produit lorsque Nginx établit une connexion, mais que le serveur backend la termine avant d'envoyer une réponse HTTP complète. Cela suggère souvent une erreur fatale ou un plantage dans le code de l'application.
2024/05/10 14:38:22 [error] 12345#0: *2 upstream prematurely closed connection while reading response header from upstream, client: 192.168.1.10, server: example.com, request: "POST /submit"
- Action : Vérifiez les journaux d'erreurs natifs du serveur d'application (par exemple, journaux PHP-FPM, journaux Node.js) pour l'erreur fatale spécifique.
Avertissement : Si Nginx ne parvient pas à lire son fichier de configuration au démarrage, l'erreur sera souvent directement affichée sur l'erreur standard ou un fichier de journal de démarrage (bootstrap), et non à l'emplacement
error.logconfiguré. Vérifiez toujoursjournalctl -xeou les journaux système si Nginx ne démarre pas.
5. Commandes Shell pratiques pour l'analyse des journaux
Bien que des systèmes robustes de surveillance des journaux soient recommandés pour la production, la ligne de commande Linux fournit des outils puissants pour un dépannage rapide et en temps réel.
5.1 Surveillance en temps réel
Surveillez les journaux au fur et à mesure que les requêtes arrivent (particulièrement utile après le déploiement d'un correctif ou le test d'une nouvelle fonctionnalité) :
tail -f /var/log/nginx/access.log
# Ou, pour les erreurs uniquement
tail -f /var/log/nginx/error.log
5.2 Filtrage et décompte des erreurs
Trouvez et comptez rapidement les erreurs 5xx les plus fréquentes de l'heure ou de la journée passée :
# Trouver toutes les requêtes 5xx
grep '" 50[0-9] ' /var/log/nginx/access.log | less
# Compter la distribution des erreurs 5xx (par exemple, combien de 502s vs 504s)
grep '" 50[0-9] ' /var/log/nginx/access.log | awk '{print $9}' | sort | uniq -c | sort -nr
Explication : awk '{print $9}' isole le code d'état HTTP (en supposant un format de journal par défaut ou combiné où l'état est le 9ème champ).
5.3 Identification des requêtes lentes (nécessite un format de journal personnalisé)
Si vous avez implémenté le format timing_log (où $request_time est l'avant-dernier champ, ou le champ 16 dans notre exemple) :
# Trouver les 10 requêtes les plus lentes (par exemple, requêtes prenant plus d'1 seconde)
awk '($16 > 1.0) {print $16, $7}' /var/log/nginx/timing_access.log | sort -nr | head -10
Explication : Cette commande affiche le temps de requête et l'URI ($7) pour toute requête qui a pris plus de 1,0 seconde, triées par ordre décroissant.
5.4 Identification des adresses IP qui demandent le plus de requêtes
Utile pour repérer les tentatives potentielles de DoS, les pics de trafic ou les activités suspectes :
# Trouver les 20 premières adresses IP effectuant des requêtes
awk '{print $1}' /var/log/nginx/access.log | sort | uniq -c | sort -nr | head -20
Conclusion
Les journaux Nginx sont la principale ressource de diagnostic pour maintenir une haute disponibilité et performance. En allant au-delà du format de journal par défaut et en intégrant des métriques de performance comme $request_time et $upstream_response_time, vous transformez de simples enregistrements en données de dépannage puissantes. Corrélez toujours les résultats dans le journal d'accès (ce qui s'est passé) avec les détails du journal d'erreurs (pourquoi cela s'est passé) pour obtenir une résolution rapide et efficace des problèmes de serveur.