> 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/error-monitoring.md). # Surveillance des erreurs (Sentry) MyIP est livré avec une instrumentation facultative [Sentry](https://sentry.io/) sur les deux moitiés de l’application. Elle est entièrement pilotée par l’environnement. {% hint style="success" %} **Si vous ne définissez aucune de ces variables, votre déploiement se comporte exactement comme une version qui n’a jamais eu Sentry.** Aucun code Sentry n’est inclus dans le bundle du frontend, `@sentry/node` n’est jamais importé par le backend, et la route tunnel n’est pas montée. Rien n’est envoyé nulle part. {% endhint %} | Variable | Moitié | Lorsqu’il est lu | | -------------------------- | --------------------- | ---------------------------------------------------------------------------- | | `VITE_SENTRY_DSN_FRONTEND` | Frontend + backend | **Au moment de la compilation** pour le bundle, à l’exécution pour le tunnel | | `SENTRY_DSN_BACKEND` | Backend | Exécution | | `SENTRY_ENVIRONMENT` | Backend | À l’exécution (et au moment de la compilation, pour les cartes source) | | `SENTRY_ORG` | Outils de compilation | Au moment de la compilation | | `SENTRY_PROJECT_FRONTEND` | Outils de compilation | Au moment de la compilation | | `SENTRY_AUTH_TOKEN` | Outils de compilation | Au moment de la compilation | Les deux moitiés sont indépendantes. Activer uniquement la surveillance du backend est une configuration parfaitement normale, et la plus simple pour les utilisateurs de Docker. ## Comment les pièces s’assemblent ``` Navigateur (SPA Vue) │ erreurs, traces, replays ▼ POST /api/monitoring ← tunnel de première partie, même origine │ (le backend valide le DSN de l’enveloppe, puis la relaie) ▼ Sentry ◀── connexion directe ── backend Express (erreurs, traces, journaux warn+) ``` ## Backend — `SENTRY_DSN_BACKEND` Définissez le DSN et redémarrez. C’est toute la configuration. {% code title=".env" %} ```bash SENTRY_DSN_BACKEND="https://@oNNNNN.ingest.sentry.io/" ``` {% endcode %} Ce qui s’active : * **Erreurs non capturées et réponses 5xx** depuis n’importe quelle `/api/*` route, via le gestionnaire d’erreurs Express de Sentry. * **Traçage des performances** avec un échantillonnage à 100 % — latence, débit et taux d’erreur par route. * **Transfert des journaux.** Le logger pino partagé répercute `warn` et au-dessus dans Sentry Logs ; `JSON` et au-dessus deviennent aussi un Incident groupé et déclenchable. Ainsi, les `logger.error({ err }, '…')` dans tout le code `api/` sont des signaux délibérés, pas de simples lignes de log. Voir [Journalisation](/developer/fr/configuration/logging.md). * **Surveillance Cron** pour les tâches planifiées du jeu de données (mise à jour automatique de MaxMind, actualisation de CAIDA, sondage de l’état des services). Les moniteurs sont créés au premier check-in — rien à précréer dans l’interface Sentry. Le SDK est amorcé via `node --import ./sentry-instrument.js`, qui enregistre les hooks du chargeur avant le chargement d’Express. Les `dev`, `démarrer`, et les commandes pm2 start transmettent déjà ce drapeau, donc il n’y a rien à ajouter. {% hint style="info" %} Le démarrage affiche `🛰️ Surveillance du backend Sentry activée` lorsque le DSN a été pris en compte. Aucune ligne signifie qu’aucun DSN n’a été vu. {% endhint %} ## Frontend — `VITE_SENTRY_DSN_FRONTEND` Celle-ci est une variable **au moment de la compilation** . Vite l’intègre en dur comme constante, et l’import dynamique du module Sentry se trouve derrière cette constante. Sans elle, l’élimination du code mort supprime la branche et le chunk du SDK n’est même jamais généré. ```bash VITE_SENTRY_DSN_FRONTEND="https://@oNNNNN.ingest.sentry.io/" pnpm run build ``` Ce qui s’active : * Exceptions non capturées et `appels console.error()` , regroupés par message. * Traçage des performances au niveau des routes avec un échantillonnage de 10 %, avec Web Vitals. * Session Replay uniquement pour les erreurs — rien n’est enregistré tant qu’aucune erreur ne se produit. {% hint style="warning" %} **La même valeur doit aussi être présente à l’exécution.** Le backend lit `VITE_SENTRY_DSN_FRONTEND` pour décider s'il faut monter `/api/monitoring` et pour savoir quel DSN il est autorisé à relayer. Compilez avec, mais oubliez de le transmettre au processus en cours d’exécution, et le SDK du navigateur envoie vers un `404`. {% endhint %} ### Replays et confidentialité Le texte de la page est délibérément **défiler** masqué dans les replays : toute l’interface de cette application est constituée des informations réseau du visiteur, précisément le contexte nécessaire pour la déboguer. Le texte saisi reste masqué. Sur l’instance publique IPCheck.ing, cela est indiqué dans la politique de confidentialité — si vous activez la surveillance du frontend pour vos propres utilisateurs, indiquez-le aussi. Les deux moitiés fonctionnent avec `sendDefaultPii: false`, donc les IP et en-têtes des visiteurs ne sont pas attachés automatiquement par les SDK. Les paramètres de requête qui ressemblent à des identifiants (`key`, `api_key`, `token`, `secret`, `password`, `auth`) sont supprimés des breadcrumbs, des spans et des contextes de requête avant tout envoi — les URL amont transportent vos clés API, et Sentry enregistre les URL à plusieurs endroits. ## Le `/api/monitoring` tunnel Les bloqueurs de publicité et les extensions de confidentialité bloquent les requêtes vers `*.ingest.sentry.io`. Pour un public habitué aux réseaux, cela représente une grande partie des visiteurs, et cela supprime silencieusement la majeure partie de vos données d’erreur. Donc le SDK du navigateur ne parle pas directement à Sentry. Il POSTe ses enveloppes vers `/api/monitoring` sur votre propre origine, et le backend les relaie. Voici le comportement de la route : * **Monté uniquement lorsque `VITE_SENTRY_DSN_FRONTEND` est défini** à l’exécution. Sinon, le chemin est un simple `404`. * **Pas un relais ouvert.** L’en-tête de l’enveloppe contient le DSN avec lequel le SDK du navigateur a été configuré. S’il ne correspond pas exactement à `VITE_SENTRY_DSN_FRONTEND`, la requête est rejetée avec `403`. Sans cette vérification, n’importe qui pourrait utiliser votre serveur pour publier dans des comptes Sentry arbitraires. * **Sa propre limite de débit**: 600 requêtes par IP toutes les 20 minutes, et il est **exempté du `/api` limiteur**global. La télémétrie qui partage le quota de l’application est la façon dont le reporting s’éteint silencieusement — un `429` et le SDK du navigateur ignore chaque événement pendant la minute suivante. * **Apposition de l’IP du visiteur**: une fois qu’une enveloppe quitte le relais, Sentry ne voit plus que l’adresse de votre serveur. Le backend inscrit la véritable IP du visiteur (depuis `CF-Connecting-IP`, lorsqu’elle est présente et valide) dans les éléments d’événement avant le transfert. * **Les échecs sont non bloquants**: une erreur de relais renvoie `502` et journalise un `warn`. Cela ne casse jamais la page. ## `SENTRY_ENVIRONMENT` Étiquette les événements du backend pour que vous puissiez filtrer la production du développement dans l’interface Sentry. * Non défini signifie `production`. * Set `SENTRY_ENVIRONMENT="development"` sur les machines de développement. Cela désactive aussi les check-ins cron, donc fermer votre ordinateur portable ne vous envoie pas d’alertes « manquées ». * Le frontend s’étiquette automatiquement à partir du mode de build Vite — rien à configurer. {% hint style="info" %} « Pourquoi n’y a-t-il aucune donnée dans Sentry ? » est, le plus souvent, le filtre d’environnement dans l’interface Sentry plutôt qu’une configuration défaillante. Vérifiez-le avant de vérifier votre config. {% endhint %} ## Cartes source — `SENTRY_ORG` / `SENTRY_PROJECT_FRONTEND` / `SENTRY_AUTH_TOKEN` Sans cartes source, les traces de pile du frontend pointent vers des offsets du bundle minifié. Le build peut les envoyer à Sentry afin que les traces soient résolues vers les vrais fichiers source. {% code title=".env" %} ```bash SENTRY_ORG="your-org-slug" SENTRY_PROJECT_FRONTEND="your-frontend-project-slug" SENTRY_AUTH_TOKEN="sntrys_..." ``` {% endcode %} L’envoi ne s’exécute que lorsque **les deux** les conditions suivantes sont remplies : 1. `SENTRY_AUTH_TOKEN` est défini, et 2. `SENTRY_ENVIRONMENT` est `production` (ou non défini, ce qui signifie production). Les builds de développement et de test ne génèrent donc ni n’envoient de cartes. {% hint style="danger" %} `SENTRY_AUTH_TOKEN` est un vrai secret et uniquement à usage de compilation. Il n’est jamais intégré en dur dans le bundle et n’atteint jamais le navigateur. Gardez-le hors de votre image, hors de votre dépôt, et limité au téléversement des cartes source. {% endhint %} Les cartes sont générées sous forme de cartes source cachées, envoyées, puis supprimées de `dist/` — les visiteurs ne peuvent pas les télécharger. ## Docker La surveillance du backend est facile ; celle du frontend ne l’est pas, et la raison mérite d’être comprise. {% tabs %} {% tab title="Backend uniquement (recommandé)" %} ```bash docker run -d -p 18966:18966 \ -e SENTRY_DSN_BACKEND="https://@oNNNNN.ingest.sentry.io/" \\ -e SENTRY_ENVIRONMENT="production" \\ --name myip \ jason5ng32/myip:latest ``` Lu à l’exécution. Fonctionne avec l’image officielle précompilée, sans reconstruction. {% endtab %} {% tab title="Frontend (nécessite une compilation personnalisée)" %} `VITE_SENTRY_DSN_FRONTEND` est consommée par `pnpm run build` **à l’intérieur de** la construction de l’image. Le transmettre avec `docker run -e` ne peut donc pas injecter Sentry dans un bundle déjà compilé. L’image officielle est construite sans aucun DSN, donc son frontend est définitivement exempt de Sentry. Pour activer la surveillance du frontend, vous devez construire votre propre image et rendre la valeur visible à l’étape de build — par exemple en ajoutant une `ARG` / `ENV` paire au `Dockerfile` avant `RUN pnpm run build`. Passez ensuite le même DSN à l’exécution aussi, afin que la route tunnel soit montée : ```bash docker run -d -p 18966:18966 \ -e VITE_SENTRY_DSN_FRONTEND="https://@oNNNNN.ingest.sentry.io/" \\ --name myip \ your-image:latest ``` {% endtab %} {% endtabs %} {% hint style="info" %} `.env` est exclu du contexte de build Docker, donc un simple `docker build` n’y récupère jamais un DSN par accident. {% endhint %} ## Vérifier votre configuration * **Backend**: recherchez `🛰️ Surveillance du backend Sentry activée` dans le journal de démarrage. * **Tunnel**: `POST /api/monitoring` ne devrait pas renvoyer `404`. Un `404` signifie que l’exécution ne voit pas `VITE_SENTRY_DSN_FRONTEND`. * **Bundle frontend**: si vous avez compilé sans DSN, aucun chunk Sentry n’existe dans `dist/assets/` du tout. * **Rien n’arrive**: vérifiez le filtre d’environnement, le sélecteur de projet et la plage temporelle dans l’interface Sentry, dans cet ordre. ## Pages associées * [Journalisation](/developer/fr/configuration/logging.md) — les niveaux pino qui alimentent Sentry Logs et Issues * [Options de sécurité](/developer/fr/configuration/security-options.md) — pourquoi le tunnel est exempté du limiteur global * [Variables d'environnement](/developer/fr/reference/environment-variables.md) — la liste complète * [Déployer avec Docker](/developer/fr/getting-started/deploy-with-docker.md) — bases de la compilation et de l’exécution --- # 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/error-monitoring.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.