> For the complete documentation index, see [llms.txt](https://docs.ipcheck.ing/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.ipcheck.ing/developer/fr/configuration/logging.md). # Journalisation Les deux processus Node — l'API backend et le serveur de fichiers statiques — écrivent tous deux dans un logger partagé [pino](https://getpino.io/) logger. Trois variables d'environnement le contrôlent. Elles sont toutes facultatives. | Variable | Valeurs | Par défaut | | ------------ | ---------------------------------- | ---------- | | `LOG_LEVEL` | `debug` / `info` / `warn` / `JSON` | `info` | | `LOG_FORMAT` | `json`, ou autre chose | pretty | | `LOG_HTTP` | `"true"` | depuis | Tout est envoyé vers stdout. Il n'y a pas de fichier journal intégré — votre gestionnaire de processus (pm2, systemd, Docker) s'en charge. ## `LOG_LEVEL` Définit la sévérité minimale qui est écrite. Tout ce qui est en dessous est écarté avant le formatage, donc un niveau discret est vraiment peu coûteux. * `debug` — tout, y compris les bavardages verbeux de mise à jour des jeux de données. Utile lorsqu'un téléchargement MaxMind ou CAIDA se comporte mal. * `info` — la valeur par défaut. Lignes de démarrage, chargements de jeux de données, plans des tâches planifiées. * `warn` — uniquement les dégradations : IP limitées par le débit, défaillances partielles en amont, timeouts. * `JSON` — uniquement les échecs de gestionnaires. {% hint style="info" %} `LOG_LEVEL` contrôle aussi ce qui parvient à Sentry. Le pont Sentry est installé à l'intérieur du logger, donc une ligne supprimée par le niveau ne devient jamais un événement Sentry ni un problème. Voir [Surveillance des erreurs](/developer/fr/configuration/error-monitoring.md). {% endhint %} ## `LOG_FORMAT` ### Affichage lisible (par défaut) Laissez `LOG_FORMAT` vide et la sortie passe par `pino-pretty`: colorisé, une ligne par événement, horodatage local à l'hôte avec un décalage UTC, `pid` et `nom d'hôte` omis. ``` [2026-07-14 10:23:45.221 +0800] INFO: 🚀 Serveur backend prêt sur http://localhost:11966 ``` C'est ce que vous voulez pour `pnpm dev` et pour lire `pm2 logs` ou `docker logs` à l'œil nu. ### JSON ```bash LOG_FORMAT="json" ``` La sortie devient un objet JSON brut par ligne — le format natif de pino — sans couleurs ni séquences d'échappement ANSI : ```json {"level":30,"time":1752459825221,"msg":"🚀 Serveur backend prêt sur http://localhost:11966"} {"level":40,"time":1752460013887,"ip":"203.0.113.45","msg":"IP limitée par le débit"} {"level":50,"time":1752460101044,"err":{"type":"Error","message":"L'amont a répondu 429"},"ip":"1.1.1.1","msg":"Le gestionnaire ipinfo-io a échoué"} ``` Notes sur les champs : * `level` est numérique : `20` debug, `30` info, `40` warn, `50` error. * `time` est exprimé en millisecondes depuis l'époque. * `msg` est le message lisible par l'humain. * Les autres clés correspondent au contexte structuré que le site d'appel a ajouté — `ip`, `asn`, `préfixe`, `err`, et ainsi de suite. Utilisez JSON chaque fois que quelqu'un d'autre qu'un humain lit les journaux. Les codes de couleur ANSI en mode lisible perturbent la plupart des analyseurs. ## `LOG_HTTP` ```bash LOG_HTTP="true" ``` Active la journalisation par requête pour `/api/*` les routes uniquement. Désactivé par défaut pour garder les journaux du gestionnaire de processus lisibles. ``` INFO: GET /api/ipinfo?ip=1.1.1.1 → 200 WARN: GET /api/report/abc → 404 ``` Détails à connaître : * Chaque requête journalise la méthode, l'URL, le code de statut et le temps de réponse. * Le niveau correspond au résultat : `5xx` ou une erreur levée → `JSON`, `4xx` → `warn`, tout le reste → `info`. * Le middleware est monté **avant** le limiteur de débit, donc `429` les réponses sont aussi journalisées. Voir [Options de sécurité](/developer/fr/configuration/security-options.md). * Les échecs au niveau du gestionnaire sont journalisés quoi qu'il arrive — `LOG_HTTP` ajoute les requêtes réussies, pas les erreurs. {% hint style="warning" %} Les URL de requête contiennent des paramètres de requête, y compris les adresses IP que les visiteurs recherchent. Sur une instance publique, cela constitue une donnée personnelle. Activez `LOG_HTTP` pour le débogage, puis désactivez-le à nouveau — ou assurez-vous que votre politique de conservation le couvre. {% endhint %} ## Lire un démarrage sain Les lignes de démarrage sont préfixées par des émojis, afin que vous puissiez parcourir un démarrage d'un coup d'œil. | Ligne | Signification | | ---------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- | | `📝 Journalisation HTTP activée (LOG_HTTP=true)` | `LOG_HTTP` est activé | | `🛡️ Limiteur de débit activé — N requêtes par …` | `SECURITY_RATE_LIMIT` est défini | | `🐢 Limiteur de vitesse activé — ralentit après N requêtes` | `SECURITY_DELAY_AFTER` est défini | | `📥 Bases de données MaxMind manquantes ; tentative de téléchargement initiale …` | Premier démarrage, GeoLite2 est en cours de récupération | | `📦 Bases de données MaxMind chargées (…)` | La géolocalisation est prête | | `📦 CAIDA as2org chargé (…)` / `📦 CAIDA as-rel chargé (…)` | Les noms d'organisations ASN et le graphe de connectivité sont prêts | | `🗓️ … plan de mise à jour automatique : prochaine vérification à …` | Un rafraîchissement planifié des jeux de données est armé | | `📦 Cache d'état du service prérempli` | La page d'état du service contient des données | | `🛰️ Surveillance du backend Sentry activée` | `SENTRY_DSN_BACKEND` est défini | | `🚀 Backend server ready on http://localhost:11966` | L'API accepte le trafic | | `🚀 Static file server ready on http://localhost:18966` | La SPA est servie | | `❌ L’API MaxMind renverra 503 jusqu’à ce que les bases de données soient chargées avec succès` | **Problème** — voir [Configuration de MaxMind](/developer/fr/getting-started/maxmind-setup.md) | Les deux `🚀` indiquent `localhost` car c'est l'adresse sur laquelle le processus se lie à l'intérieur de son propre hôte ou conteneur. Ce n'est pas une indication de votre URL publique. ## Diffusion de journaux JSON Set `LOG_FORMAT="json"` et laissez votre plateforme collecter stdout. Rien d'autre dans l'application n'a besoin d'être modifié. {% tabs %} {% tab title="Docker" %} ```bash docker run -d -p 18966:18966 \ -e LOG_FORMAT="json" \ -e LOG_LEVEL="info" \\ --log-driver=json-file \ --name myip \ jason5ng32/myip:latest ``` À partir de là, n'importe quel pilote de journalisation Docker ou collecteur sidecar (Vector, Fluent Bit, Promtail, l'agent Datadog) récupère les lignes. Chaque ligne est déjà un JSON valide, donc aucun traitement multiligne ou par regex n'est nécessaire. {% endtab %} {% tab title="pm2" %} {% code title=".env" %} ```bash LOG_FORMAT="json" LOG_LEVEL="info" ``` {% endcode %} pm2 écrit stdout dans ses propres fichiers journaux ; pointez votre collecteur vers ces chemins (`pm2 info ` les affiche). {% hint style="warning" %} pm2 prend un instantané des variables d'environnement lorsqu'un processus est lancé pour la première fois. `pm2 restart` rejoue l'ancien instantané. Après avoir changé `.env`, faites `pm2 delete && pm2 start ecosystem.config.cjs && pm2 save`. {% endhint %} {% endtab %} {% tab title="À la volée / jq" %} ```bash # Erreurs uniquement, les plus récentes d'abord docker logs myip 2>&1 | jq -c 'select(.level >= 50)' # Quelles IP ont été limitées par le débit docker logs myip 2>&1 | jq -r 'select(.msg == "IP limitée par le débit") | .ip' | sort | uniq -c # Reformatez un flux JSON pour la lecture humaine docker logs myip 2>&1 | npx pino-pretty ``` {% endtab %} {% endtabs %} Une base de production raisonnable : `LOG_FORMAT="json"`, `LOG_LEVEL="info"`, `LOG_HTTP` désactivé. Ajoutez `LOG_HTTP="true"` temporairement lorsque vous avez besoin d'une visibilité par requête. ## Pages associées * [Surveillance des erreurs](/developer/fr/configuration/error-monitoring.md) — comment `warn` et `JSON` les lignes atteignent Sentry * [Options de sécurité](/developer/fr/configuration/security-options.md) — les événements derrière les `IP soumise à une limitation de débit` avertissements * [Variables d'environnement](/developer/fr/reference/environment-variables.md) — la liste complète * [Backend](/developer/fr/architecture/backend.md) — l'endroit où le logger se situe dans le chemin de la requête --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.ipcheck.ing/developer/fr/configuration/logging.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.