Sentry dans Next.js App Router : erreurs de serveur et de client, cartes sources sans PII
Que devrait-il se passer
Une erreur dans un composant serveur, Route Handler, Server Action ou dans le navigateur est transmise à Sentry avec une pile lisible (noms de fichiers et lignes sources, pas un bundle minifié), avec une indication de version et sans données utilisateur personnelles dans l'événement.
##Installation
npx @sentry/wizard@latest -i nextjs
L'assistant crée des fichiers et modifie next.config. Découvrez ce qu'il a fait, puis vous les soutenez :
instrumentation-client.ts(dans les anciennes versions du SDK -sentry.client.config.ts) - initialisation dans le navigateur.sentry.server.config.tsetsentry.edge.config.ts- pour l'exécution Node.js et Edge.instrumentation.tsest le point d'entrée que Next.js appelle au démarrage du serveur.app/global-error.tsx— limite d'erreur pour la disposition racine.
// instrumentation.ts
import * as Sentry from "@sentry/nextjs";
export async function register() {
if (process.env.NEXT_RUNTIME === "nodejs") await import("./sentry.server.config");
if (process.env.NEXT_RUNTIME === "edge") await import("./sentry.edge.config");
}
export const onRequestError = Sentry.captureRequestError;onRequestError est un hook Next.js 15 qui est appelé lors du rendu des erreurs dans les gestionnaires de routes et les actions du serveur. Sans cette ligne, les erreurs du serveur n'atteignent souvent pas Sentry : Next.js les intercepte lui-même et montre à l'utilisateur une page d'erreur.
Configuration du serveur sans PII
// sentry.server.config.ts
import * as Sentry from "@sentry/nextjs";
Sentry.init({
dsn: process.env.SENTRY_DSN,
environment: process.env.APP_ENV ?? "production",
release: process.env.SENTRY_RELEASE,
sendDefaultPii: false,
tracesSampleRate: 0.1,
beforeSend(event) {
if (event.request) {
delete event.request.cookies;
delete event.request.data;
if (event.request.headers) {
delete event.request.headers.authorization;
delete event.request.headers.cookie;
}
}
return event;
},
});sendDefaultPii: false(c'est la valeur par défaut, mais explicite c'est mieux) - Le SDK n'attache pas l'adresse IP, les cookies et les en-têtes de données utilisateur.beforeSend- dernière ligne : supprime ce qui pourrait passer par les intégrations ou votre propre contexte. Le corps de la requête (request.data) est particulièrement dangereux : il contient les mots de passe du formulaire de connexion et les données de paiement.- Précisez l'utilisateur uniquement par identifiant :
Sentry.setUser({ id: user.id }). L'e-mail et le nom dans les événements d'erreur ne sont pas nécessaires au débogage, mais sont stockés par un tiers. tracesSampleRate: 0.1- 10 % des demandes de traçage des performances. Une valeur de 1,0 en production épuisera rapidement le quota.
Vérifiez également les textes d'erreur. `throw new Error(Utilisateur ${email} introuvable) отправит адрес в Sentry в сообщении, и никакой sendDefaultPii` ne l'arrêtera pas.
Relecture du client et de la session
// instrumentation-client.ts
import * as Sentry from "@sentry/nextjs";
Sentry.init({
dsn: process.env.NEXT_PUBLIC_SENTRY_DSN,
tracesSampleRate: 0.1,
replaysSessionSampleRate: 0,
replaysOnErrorSampleRate: 0.2,
integrations: [Sentry.replayIntegration({ maskAllText: true, blockAllMedia: true })],
});Replay écrit le DOM de la page. maskAllText et blockAllMedia sont activés par défaut - ne les désactivez pas sans vous assurer que les pages ne contiennent pas d'informations personnelles. L'enregistrement uniquement des sessions ayant échoué (replaysOnErrorSampleRate) fournit un contexte pour le débogage sans surveiller constamment les utilisateurs.
Le DSN du navigateur est public par nature : il permet uniquement d'envoyer des événements. Limitez les domaines autorisés dans les paramètres du projet Sentry (domaines autorisés) afin que les sites d'autres personnes n'obstruent pas votre projet.
Cartes sources
// next.config.ts
import { withSentryConfig } from "@sentry/nextjs";
const nextConfig = { /* ... */ };
export default withSentryConfig(nextConfig, {
org: "my-org",
project: "web",
authToken: process.env.SENTRY_AUTH_TOKEN,
silent: !process.env.CI,
widenClientFileUpload: true,
sourcemaps: { deleteSourcemapsAfterUpload: true },
});Pendant next build, le plugin charge les cartes sources dans Sentry. deleteSourcemapsAfterUpload supprime les fichiers .map de la version après le téléchargement afin que le code source ne soit pas partagé avec tout le monde sur votre site. Vérifiez après le déploiement : une requête adressée à n'importe quel .js.map depuis /_next/static/chunks/ doit renvoyer 404.
SENTRY_AUTH_TOKEN est un secret avec une autorisation d'écriture sur le projet. Il n'est nécessaire que dans CI au stade de la construction, pas au moment de l'exécution ni dans les variables avec le préfixe NEXT_PUBLIC_.
Diagnostic
- La pile est réduite. Les cartes sources n'ont pas été chargées ou la version de l'événement ne coïncide pas avec la version téléchargée. La commande
sentry-cli sourcemaps explain <event_id>explique pourquoi un événement particulier n'a pas été symbolisé. - Les erreurs de serveur ne surviennent pas. Il n'y a pas de
onRequestErrordansinstrumentation.ts, ou le fichier n'est pas à la racine du projet (s'il y asrc/- à l'intérieur desrc/). - Les erreurs de navigateur ne se produisent pas pour certains utilisateurs. Les bloqueurs de publicités coupent les requêtes adressées à Sentry. L'option
tunnelRoute: "/monitoring"danswithSentryConfigtransmettra les événements via votre domaine. Si le site dispose d'un CSP strict, ajoutez le domaine de réception àconnect-src. - Rien n'arrive du tout. Activez temporairement
debug: truedansSentry.initet consultez les journaux du serveur et la console du navigateur.
Bruit et quotas
Toutes les erreurs ne valent pas l’événement. Filtrez celles attendues : requêtes annulées, erreurs d’extension de navigateur, 404 des robots. Utilisez ignoreErrors pour les messages connus et denyUrls pour les scripts d'extension. Un projet où il y a chaque jour mille erreurs identiques sans importance apprend à l'équipe à ne pas regarder du tout Sentry.
Quand Sentry est redondant
Pour un petit service interne, des logs structurés avec le niveau error et une alerte pour leur numéro peuvent suffire. Sentry est payant lorsqu'il existe du JavaScript côté client, de nombreux utilisateurs et que vous devez regrouper les erreurs et voir quelle version les a apportées.