Sentry в Next.js App Router: серверные и клиентские ошибки, source maps без PII
何が起こるべきか
サーバー コンポーネント、ルート ハンドラー、サーバー アクション、またはブラウザーでのエラーは、読み取り可能なスタック (圧縮されたバンドルではなくファイル名とソース行) とともに、リリース表示とともに、イベント内の個人ユーザー データなしで Sentry に送られます。
インストール
npx @sentry/wizard@latest -i nextjs
ウィザードはファイルを作成し、next.config を編集します。彼が何をしたかを理解してから、あなたは彼らをサポートします。
instrumentation-client.ts(SDK の古いバージョンでは -sentry.client.config.ts) - ブラウザでの初期化。sentry.server.config.tsおよびsentry.edge.config.ts- Node.js および Edge ランタイム用。instrumentation.tsは、サーバーの起動時に Next.js が呼び出すエントリ ポイントです。app/global-error.tsx— ルート レイアウトのエラー制限。
// 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 は、ルート ハンドラーとサーバー アクションのレンダリング エラー時に呼び出される Next.js 15 フックです。この行がないと、サーバー エラーが Sentry に到達しないことがよくあります。Next.js 自体がエラーをインターセプトし、ユーザーにエラー ページを表示します。
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(これがデフォルトですが、明示的な方が良いです) - SDK は IP アドレス、Cookie、およびユーザー データ ヘッダーを添付しません。beforeSend- 最後の行: 統合または独自のコンテキストを通じて取得できるものを削除します。リクエストの本文 (request.data) は特に危険です。ログイン フォームと支払いデータのパスワードが含まれています。- ユーザーは識別子のみで指定します:
Sentry.setUser({ id: user.id })。エラー イベント内の電子メールと名前はデバッグには必要ありませんが、サードパーティによって保存されます。 tracesSampleRate: 0.1- パフォーマンス トレースのリクエストの 10%。本番環境で値 1.0 を指定すると、すぐにクォータが使い果たされてしまいます。
エラーテキストも確認してください。 `throw new Error(ユーザー ${email} が見つかりません) отправит адрес в Sentry в сообщении, и никакой sendDefaultPii` では停止しません。
クライアントとセッションのリプレイ
// 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 はページの DOM を書き込みます。 maskAllText および blockAllMedia はデフォルトで有効になっています。ページに個人情報が含まれていないことを確認せずに無効にしないでください。失敗したセッション (replaysOnErrorSampleRate) のみを記録すると、ユーザーを常に監視することなく、デバッグ用のコンテキストが提供されます。
ブラウザーの DSN は本質的にパブリックであり、イベントの送信のみを許可します。他の人のサイトがプロジェクトを妨害しないように、Sentry プロジェクト設定 (許可されたドメイン) で許可されるドメインを制限します。
ソースマップ
// 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 },
});next build 中に、プラグインはソース マップを Sentry にロードします。 deleteSourcemapsAfterUpload は、ソース コードがサイト上の全員と共有されないように、アップロード後にビルドから .map ファイルを削除します。デプロイ後の確認: /_next/static/chunks/ からの任意の .js.map へのリクエストは 404 を返すはずです。
SENTRY_AUTH_TOKEN は、プロジェクトへの書き込み権限を持つシークレットです。これはビルド段階の CI でのみ必要であり、実行時や NEXT_PUBLIC_ プレフィックスが付いた変数では必要ありません。
診断
- スタックは縮小されています。 ソース マップがロードされていないか、イベント リリースがダウンロード リリースと一致しません。
sentry-cli sourcemaps explain <event_id>コマンドは、特定のイベントがシンボル化されなかった理由を説明します。 - サーバーエラーは発生しません。
instrumentation.tsにonRequestErrorが存在しないか、ファイルがプロジェクトルートにありません (src/がある場合 -src/内)。 - 一部のユーザーではブラウザ エラーが発生しません。 広告ブロッカーは Sentry へのリクエストをカットします。
withSentryConfigのtunnelRoute: "/monitoring"オプションは、ドメイン経由でイベントをプロキシします。サイトに厳密な CSP がある場合は、受信ドメインをconnect-srcに追加します。 - 何も届きません。
Sentry.initのdebug: trueを一時的に有効にして、サーバー ログとブラウザ コンソールを確認します。
ノイズとクォータ
すべてのミスがイベントに値するわけではありません。予想されるもの (キャンセルされたリクエスト、ブラウザ拡張エラー、ボットからの 404) をフィルタリングします。既知のメッセージには ignoreErrors を使用し、拡張スクリプトには denyUrls を使用します。毎日同じ重要でないエラーが 1,000 件発生するプロジェクトでは、チームは Sentry をまったく見てはいけないと教えられます。
Sentry が冗長な場合
小規模な内部サービスの場合は、error レベルの構造化ログとその数のアラートで十分な場合があります。 Sentry は、クライアント側 JavaScript があり、ユーザーが多く、エラーをグループ化し、どのリリースでエラーが発生したかを確認する必要がある場合に効果を発揮します。