lecoffre-back-mini/docs/logs-backend.md

Logs backend – emplacements et points de contrôle

Emplacements des logs

• log courant: logs/backend.out
• PID du process Node: logs/backend.pid
• logs rotés: logs/backend_YYYYMMDD_HHMMSS.out
• logs de build (si utilisés): logs/build_YYYYMMDD_HHMMSS.out

Rotation simple (manuelle)

• Renommer logs/backend.out en logs/backend_YYYYMMDD_HHMMSS.out avant relance.

Démarrage / Arrêt

• Au démarrage, rechercher: Server started on port 8080 (ou le port configuré).
• En arrêt/redémarrage, s’assurer qu’aucun ancien process ne reste actif (voir logs/backend.pid).

Suivi temps réel

• Suivre logs/backend.out en continu pour les scénarios de test.
• Capturer la fenêtre incluant: callback → échange de token → appels Annuaire.

Points de contrôle à rechercher (IdNot)

• Réception du callback:
  • [IdNotCallback] incoming request avec code_present: true et state_present: true.
• Échange de token OIDC:
  • Token exchange successful avec hasAccessToken, hasIdToken.
• Décodage JWT:
  • JWT payload decoded avec hasProfileIdn, hasEntityIdn.
• Appels Annuaire (QUAL) – réponses JSON attendues:
  • Absence des erreurs:
    • IdNot non-JSON response
    • IdNot JSON parse failed
  • En cas d’erreur proxy, on peut voir No context (non-JSON).
• Erreur applicative agrégée:
  • IdNot authentication failed ou un objet d’erreur avec code: 'IDNOT_SERVICE_ERROR'.

Interprétation rapide

• Si No context apparaît:
  • Vérifier l’envoi des en-têtes: Accept: application/json et en-tête de contexte IdNot (config via IDNOT_CONTEXT_HEADER / IDNOT_CONTEXT_VALUE).
• Si Token exchange failed:
  • Vérifier IDNOT_TOKEN_URL, IDNOT_CLIENT_ID, IDNOT_CLIENT_SECRET, IDNOT_REDIRECT_URI.
• Si User not attached to an office:
  • Le JWT ou les données Annuaire ne satisfont pas les règles métier attendues.

Variables d’environnement utiles (rappel)

• Bases d’URL:
  • IDNOT_API_BASE_URL (données Annuaire, QUAL)
  • IDNOT_ANNUARY_BASE_URL (Annuaire, endpoints personnes/entités)
• Contexte QUAL (si requis par le proxy IdNot):
  • IDNOT_CONTEXT_HEADER (ex: X-Context)
  • IDNOT_CONTEXT_VALUE (valeur fournie par IdNot)
• Auth OIDC:
  • IDNOT_TOKEN_URL, IDNOT_CLIENT_ID, IDNOT_CLIENT_SECRET, IDNOT_REDIRECT_URI

Bonnes pratiques

• Toujours effectuer une rotation de logs/backend.out avant un test significatif.
• Conserver les logs datés pour l’investigation et la comparaison entre exécutions.

Nginx – emplacements et points de contrôle

Emplacements

• Access log Nginx (vhost): /var/log/nginx/dev3.4nkweb.com.access.log
• Error log Nginx (vhost): /var/log/nginx/dev3.4nkweb.com.error.log

Spécificités de configuration (fichier confs/nginx/dev3.4nkweb.com.conf)

• Ajout de access_log et error_log par vhost.
• Propagation d’un identifiant de requête: X-Request-Id: $request_id vers l’upstream.
• Ajout d’un en-tête X-Request-Id sur les réponses pour faciliter la corrélation.

Corrélation des requêtes

• Utiliser X-Request-Id pour faire le lien entre:
  • les entrées dans /var/log/nginx/dev3.4nkweb.com.access.log,
  • et les logs applicatifs dans logs/backend.out (recherchez requestId dans les logs Express s’il est présent, sinon corrélez via timestamp, méthode et chemin).

À surveiller côté Nginx

• Codes 4xx/5xx dans l’access log sur /idnot/callback, /api/..., /ws/.
• Délai ou timeouts (upstream timed out) dans l’error log.
• Cohérence du schéma (X-Forwarded-Proto) et du host (Host) vers l’upstream.

Commandes utiles (ops locales)

Backend Node

• Créer dossier logs (idempotent):

mkdir -p logs

• Rotation log backend courant:

if [ -f logs/backend.out ]; then mv -f logs/backend.out logs/backend_$(date +%Y%m%d_%H%M%S).out; fi

• Démarrage en arrière-plan avec redirection vers log et PID:

nohup node dist/server.js > logs/backend.out 2>&1 & echo $! > logs/backend.pid

• Arrêt du backend via PID:

kill $(cat logs/backend.pid)

• Suivi temps réel des logs backend:

tail -f logs/backend.out

Nginx (local serveur)

• Recharger la configuration après modification:

sudo nginx -t && sudo systemctl reload nginx

• Suivi des logs Nginx:

sudo tail -f /var/log/nginx/dev3.4nkweb.com.access.log /var/log/nginx/dev3.4nkweb.com.error.log

Dépannage

• Erreur lors de l’écriture de logs/backend.pid:
  • Assurez-vous que le dossier logs/ existe avant le démarrage (mkdir -p logs).
  • Vérifiez les droits d’écriture dans le répertoire du projet.
• Pas de corrélation évidente entre Nginx et backend:
  • Utilisez X-Request-Id (présent côté Nginx) et rapprochez par timestamp/méthode/chemin côté backend.
• Erreurs IdNot "No context":
  • Vérifier les en-têtes envoyés côté backend: Accept: application/json et les variables IDNOT_CONTEXT_HEADER / IDNOT_CONTEXT_VALUE.