Next.jsプロジェクトにSentryを統合してエラーモニタリングとパフォーマンス監視を行う方法

はじめに

Next.jsの監視ツールとしてSentryをピックアップしてどのように監視の仕組みを導入するかまとめて見ました。

Next.jsはクライアントサイド、サーバーサイドで動くプログラムとなっておりますのでその辺りも考慮しつつ動作検証を行なっていきます。

監視もエラーのログだけでなくパフォーマンスのチェックも可能ですのでそれぞれどのような情報を確認できるかもお伝えできたらと思います。

Sentryについて

Sentryは、アプリケーションのエラー監視やパフォーマンス監視を行うためのサービスです。主に開発者向けに提供されており、エラーやパフォーマンスの問題をリアルタイムで検出し、迅速に対応するためのツールとして非常に人気があります。

主な特徴と機能

1.エラー追跡 (Error Monitoring)

• アプリケーションで発生するエラーをキャッチし、どこで発生したのかを詳細にレポートします。
• スタックトレースや関連するメタデータ（ユーザー情報、リクエスト内容など）を収集して、問題の特定を容易にします。
• エラーが発生すると通知を受け取れる（メール、Slack、PagerDutyなどに連携）。

2.パフォーマンス監視 (Performance Monitoring)

• アプリケーションのパフォーマンス（レスポンス時間、スループット、API呼び出しのボトルネックなど）を可視化します。
• 各リクエストやトランザクションごとの詳細データを収集し、遅延の原因を突き止めやすくします。

3.リアルタイム監視

• デプロイ後のコードで即座に問題を発見でき、ユーザーへの影響を最小限に抑えることが可能です。

4.多言語・多フレームワーク対応

• フロントエンド（JavaScript、React、Vueなど）やバックエンド（Node.js、Python、Ruby、Java、Goなど）、モバイル（iOS、Android）など幅広い技術スタックをサポートしています。

5.統合とカスタマイズ

• GitHubやGitLabと統合することで、エラーがどのコミットから発生したかを追跡。
• カスタムタグやコンテキストを追加して、エラーの状況をさらに詳しく分析。

6.リリース管理

• リリースごとのエラーやパフォーマンスデータを追跡して、新しいバージョンで問題が発生しているかを確認できます。

利用シーン

• エラーの即時把握: ユーザーに影響を与える前に問題を修正する。
• パフォーマンスの最適化: レスポンス時間やボトルネックを特定して改善。
• デプロイ後の安定性確認: リリース後にどのような影響が出ているかを監視。

メリット

• 開発者が迅速に問題を修正できるため、ユーザー体験の向上に貢献。
• チーム全体でエラーやパフォーマンスデータを共有でき、効率的なデバッグが可能。
• 煩雑なログの確認作業を減らし、問題の特定にかかる時間を短縮。

Next.jsのプロジェクト作成

まずはNext.jsのプロジェクトを作成します。

作成手順についてはこちらにも記載がありますのでこちらをご参考頂けたらと思います。

こちらの手順通りに進めて頂いて、ローカル環境で起動できるところまで確認できましたら終了です。

https://shinagawa-web.com/blogs/nextjs-microcms-blog-tutorial#next.jsプロジェクトの作成

Sentryにアカウント登録

それではSentryにアカウント登録をして使える状態にします。

Developerとして一人で使う分には無料となっておりますのでご安心ください。

https://sentry.io/pricing/

サインアップには名前、メールアドレス、組織名を入力します。

あとは監視結果を保存するロケーションを選択します。US or EUとなっているため、どちらでもいいかと思います。

登録が完了しましたら早速Sentryをローカル環境でセットアップしていきます。

先ほどの主な特徴と機能にも記載しましたが様々な言語やフレームワークに対応しておりまして今回は「Next.js』を選択します。

するとNext.jsのプロジェクトにインストールするコマンドが表示されます。

コピーして実行します。

私の場合はコミットしていないファイルが残っていたので警告が出ました。

気にせず先に進みます。

Sentryのアカウントを持っていますか？ → Yes

するとコマンドプロンプトからSentryにアクセスし認証を行います。

認証が通ればパッケージをインストールし先に進みます。

セットアップに関して4つ質問が出てきます。

1つ目の質問

Do you want to route Sentry requests in the browser through your Next.js server to avoid ad blockers?

ブラウザで発生したエラーレポートを直接Sentryに送信するか、それとも一旦Next.jsのサーバー経由で送信するかを選択するものとなります。

サーバー経由で送信する場合のメリットとしては

• AdBlockなどの広告ブロッカーに引っかかりにくくなるため、エラーレポートが確実に送信されやすい。
• ユーザーのIPアドレスなどが直接Sentryに渡らない（プライバシー保護が強化される可能性）。

ただし懸念点としては、

• サーバーの負荷が増える。
• 送信回数が多い場合、ホスティングコストが上昇する。

などが挙げられます。

今回は検証なので「サーバー経由で送信する」（Yes）を選択します。

2つ目の質問

Do you want to enable React component annotations to make breadcrumbs and session replays more readable?

「Reactコンポーネントの注釈（annotations）を有効にしますか？これを有効にすると、SentryのBreadcrumbs（パンくずリスト）やセッションリプレイ（ユーザー操作の再現）が、より読みやすく・分かりやすくなります。」

このメッセージは、SentryをReactアプリに統合する際の設定オプションに関するものです。

意味：
「Reactコンポーネントの注釈（annotations）を有効にしますか？
これを有効にすると、SentryのBreadcrumbs（パンくずリスト）やセッションリプレイ（ユーザー操作の再現）が、より読みやすく・分かりやすくなります。」ということです。

React Component Annotationsとは？

• Sentryがエラーをキャプチャした際、Reactコンポーネントの名前や階層をエラーログに含めることで、どのコンポーネントで問題が発生したかが分かりやすくなる機能です。
• Breadcrumbs（パンくずリスト）:ユーザーの操作履歴やイベント（クリック、ナビゲーションなど）を記録する機能。どのReactコンポーネントでどの操作が行われたのかを明確に表示できます。
• Session Replays（セッションリプレイ）：ユーザーのセッション（操作内容）を録画・再現する機能。再現時にReactコンポーネントの情報を含めることで、操作がどの部分で発生したのかを把握しやすくなります。

デバッグが簡単になるため「Yes」を選択します。

3つ目の質問

Do you want to enable Tracing to track the performance of your application?

SentryにおけるTracing（トレーシング）機能を有効にしますか？

有効化する利点としては下記が挙げられます。

• パフォーマンスのボトルネックを特定できる:例えば、「ページの読み込みが遅いのはどこか？」や「このAPIコールが遅い原因は？」といった問題を素早く見つけられる。
• ユーザー体験を向上できる:アプリがどのように動作しているかを把握し、問題箇所を改善することでUXの向上に繋がる。
• フロントエンドとバックエンドの両方を追跡:フロントエンド（React、Next.js）だけでなく、APIやデータベースなどのバックエンドもトレース可能。
• エラーとパフォーマンスの関連付け:エラーがどのリクエストやトランザクションに影響を与えているかを可視化できる。

トレーシングデータはログよりもデータ量が大きい場合が多く、Sentryの利用料が増えることがありますが検証のため今回は「Yes」にします。

4つ目の質問

Do you want to enable Sentry Session Replay to get a video-like reproduction of errors during a user
session?

Sentry Session Replay 機能を有効にするかどうか？

2つ目の質問と若干似ていますが、今回は検証のため「Yes」にします。

質問はさらに続きます。

サンプルページを作成しますか？という質問が出ますが、こちらは「No」とします。

理由は2つありまして、1つはこの処理に関する不具合が存在するという点です。

https://github.com/getsentry/sentry-wizard/issues/436

（もう解消されているようですが。。。）

もう一つはSentry公式のチュートリアルにサンプルのコードが用意してあるのでそちらで動作検証が可能だからとのなります。

「No」を設定したあとさらに質問が続きます。

Warning: The Sentry SDK doesn't yet fully support Turbopack in dev mode. ...

Next.js 15からTurbopackが安定版としてリリースされておりますが、Sentryではまだサポート外のようです。

後ほどTurbopackは使わないよう設定変更をします。

Are you using a CI/CD tool to build and deploy your application ?

こちらも「Yes」とします。

そうすると画面上にSENTRY_AUTH_TOKENが表示されます。

その内容をコピーして、.env.development.localを作成した上でペーストします。

SENTRY_AUTH_TOKEN=xxxxxxxx

あとは先ほど警告が出ていたNext.js 15のTurbopackの設定を変更します。

  "scripts": {
-     "dev": "next dev --turbopack",
+     "dev": "next dev",
    "build": "next build",
    "start": "next start",
    "lint": "next lint"
  },

Sentryのダッシュボードを確認

Sentryは便利なのかアカウント登録からローカル環境のセットアップまでを一気に行うことができます。

そのためまだダッシュボードを確認できていませんでした。

まずはダッシュボードを確認します。

プロジェクト一覧が表示されるのでプロジェクトを選択します。

私の環境ではエラーを1件発生させたので既にグラフ上に表示されています。。。

動作検証

Next.jsプロジェクトにSentryのセットアップが完了しましたので実際にエラーを発生させてSentryにログが送信されているか確認していきます。

クライアントサイドの動作検証

エラーを発生させるためのコンポーネントをcomponents/button.tsxとして作成します。

Sentry公式のチュートリアルを参考にしています。

https://docs.sentry.io/platforms/javascript/guides/nextjs/#install

export const Button = () => {
  return (
    <button
      type="button"
      onClick={() => {
        throw new Error("Sentry Frontend Error");
      }}
    >
      Throw error
    </button>
  );
}

作成したコンポーネントをトップページから呼び出すようにします。

Next.jsのプロジェクトを作成したタイミングではサンプルのコードが書いてあるので消した上で下記のコードを書いていきます。

import { Button } from "@/components/button";

export default function Home() {
  return (
   <div>
      <h1>Home</h1>
      <Button />
   </div>
  );
}

Next.jsを起動し「Throw error」と書いてあるボタンをクリックします。

するとエラーが表示されるかと思いますので、ダッシュボードを確認します。

1件エラーがありました。

Sentry Frontend Errorとなっています。クリックして詳細を確認します。

エラーの発生した時間（UTC）やURLなどが確認できます。

またエラーが発生した該当のコードも確認できるようになっています。

先ほど作成したコンポーネントのthrow new Errorでエラーが発生していることがわかります。

発生したコードがわかると、開発エンジニアとしては調査が非常にスムーズになりますね。

上記のエラー詳細画面でReplaysというタブがあるのでクリックすると動画でクライアントサイドの操作をみることができます。

利用者がどのようにしてエラーを発生させたかを確認することができるのでこちらも調査が非常にスムーズになる便利な機能かと思います。

サーバーサイドの動作確認

次はサーバーサイドで動く処理でエラーが発生した時のログを確認します。

まずはエラーを発生させるコードを書いていきます。

/app/api/error/route.tsファイルを作成し以下のコードを書いていきます。

export function GET() {
  throw new Error("API throw error test");
};

作成できましたらAPIにアクセスしてエラーを発生させます。

ブラウザで下記のURLを入力するとアクセス可能です。

http://localhost:3000/api/error

サーバーサイドですのでローカルで起動したコンソール上にエラーメッセージが表示されます。

想定通りエラーを発生させることができました。

Sentryのダッシュボードでエラーのログを取得できているか確認します。

API throw error testというエラーが発生していることを確認できました。

リンクをクリックし詳細を確認します。

エラーの発生日時、URLが確認できます。

あとはどのコードでエラーが発生したかも確認可能となっています。

先ほど作成したファイルでエラーが発生したことが確認できます。

https://docs.sentry.io/platforms/javascript/guides/nextjs/#install

パフォーマンスに関する動作確認

Sentryではエラーだけでなくパフォーマンスに関しても様々な情報を確認できます。

表示に時間がかかるページを用意してテストをしてみます。

/app/slow/page.tsxファイルを作成し下記のコードを書いていきます。

export default async function SlowPage() {
  await new Promise((resolve) => setTimeout(resolve, 3000))
  return (
    <div>
      <h1>Slow Page</h1>
    </div>
  );
}

サーバーサイドで3秒間スリープした後にレンダリングするよう設定しました。

http://localhost:3000/slow

にアクセスすると少し間を置いてから画面が表示されるかと思います。

左メニューのPerformanceから情報を見ることが出来ます。

/slowというトランザクションが表示されます。表示までに5秒ぐらいかかっていることを確認できます。

クリックすると詳細を確認できます。

（ログが表示されるまで少し時間がかかるかもしれません）

1回だけアクセスしたので1行表示されています。

TRACE IDをクリックします。

該当の処理の詳細な内容が表示されます。

• pageload: ページを表示するまでのトータルの時間(5.76秒)
• http.server: ブラウザからリクエストを送って結果が返ってくるまでの時間(4.97秒)
• function.nextjs - Page Server Component: 今回スリープを入れたサーバーアクションの処理時間(3秒)
• ui.long-animation-frame: UI表示のメインスレッドの処理時間(0.244秒)

どこでどの程度処理に時間がかかったかを確認することができます。

これでパフォーマンス改善をする際にはどこから着手したらいいかの目安がつきそうです。

補足: Sentry関連設定のファイルについて

プロジェクトのセットアップは下記コマンドで実施しました。

npx @sentry/wizard@latet -i nextjs --saas --org shinagawa-web --project javascript-nextjs

このコマンドでSentryへログを送るためのいくつかのファイルが作成されます。

それらについて解説します。

sentry.client.config.ts

このファイルは Sentry を Next.js のクライアントサイドで初期化するための設定ファイル です。
Sentry は、アプリケーションのエラーロギングやパフォーマンス監視を行うツールで、この設定によりブラウザ側で発生したエラーを自動でキャプチャできます。

import * as Sentry from "@sentry/nextjs";

Sentry.init({
  dsn: "https://xxx@xxx.ingest.us.sentry.io/4508520017494016",
  integrations: [
    Sentry.replayIntegration(),
  ],
  tracesSampleRate: 1,
  replaysSessionSampleRate: 0.1,
  replaysOnErrorSampleRate: 1.0,
  debug: false,
});

• replayIntegration()

  • Sentry の Session Replay 機能を有効にする。
  • ユーザーの操作を動画のように記録し、エラー発生時の状況を可視化できる（デバッグの際に便利）。

• tracesSampleRate

  • トレースデータのサンプリング率 を設定。
  • 1 にすると 100% のリクエストをトレース する（すべてのリクエストを記録）。
  • 適切な値に調整することで、Sentry のデータ使用量を抑えることができる。

• replaysSessionSampleRate

  • 通常時のセッションリプレイのサンプリング率 を設定。
  • 0.1 に設定しているため、10% のユーザーセッションが記録される。
  • 開発中は 1 にするとデバッグしやすい。

• replaysOnErrorSampleRate

  • エラーが発生したときのセッションリプレイのサンプリング率 を設定。
  • 1.0 にしているため、エラー発生時はすべてのセッションが記録される。

• debug

  • true にすると、Sentry の初期化やエラーキャプチャの動作が詳細にコンソールに表示される。

デフォルトでも動くのですがパフォーマンスやセキュリティを考慮するといくつか改善点があります。

改善後

import * as Sentry from "@sentry/nextjs";

Sentry.init({
  dsn: process.env.NEXT_PUBLIC_SENTRY_DSN,
  integrations: [
    Sentry.replayIntegration(),
  ],
  tracesSampleRate: process.env.NODE_ENV === "production" ? 0.2 : 1,
  replaysSessionSampleRate: process.env.NODE_ENV === "production" ? 0.05 : 1,
  replaysOnErrorSampleRate: 1.0,
  debug: process.env.NODE_ENV !== "production",
});

ポイント

• DSN を環境変数にする（セキュリティ対策）
• 本番環境ではサンプリング率を適切な値にすることで、不要なデータ送信を抑えられる。
• デバッグモードは開発環境のみ true にしてデバッグ し、本番環境では false にするのが推奨

sentry.server.config.ts

このファイルは Sentry を Next.js のサーバーサイドで初期化するための設定ファイル です。
Next.js の API Routes や getServerSideProps、middleware などのサーバーサイド処理で発生したエラーを Sentry に送信するための設定になります。

import * as Sentry from "@sentry/nextjs";

Sentry.init({
  dsn: "https://xxx@xxx.ingest.us.sentry.io/4508520017494016",
  tracesSampleRate: 1,
  debug: false,
});

こちらもクライアントサイドの設定ファイル同様、サンプリング率やデバックモードは本番環境と開発環境で設定を変えた方がいいと思います。

sentry.edge.config.ts

このファイルは Sentry を Next.js の Edge 機能（Middleware、Edge Routes など）向けに初期化する設定ファイル です。
Edge 環境でのエラーログ取得やパフォーマンス監視を可能にします。

import * as Sentry from "@sentry/nextjs";

Sentry.init({
  dsn: "https://xxx@xxx.ingest.us.sentry.io/4508520017494016",
  tracesSampleRate: 1,
  debug: false,
});

こちらもサーバーサイドの設定ファイル同様、サンプリング率やデバックモードは本番環境と開発環境で設定を変えた方がいいと思います。

next.config.ts

このファイルは Next.js の Sentry 設定を withSentryConfig を使って統合するための設定ファイル です。
withSentryConfig は Sentry の Webpack プラグインを設定し、ビルド時に適切な処理を追加する ためのラッパー関数です。

import {withSentryConfig} from "@sentry/nextjs";
import type { NextConfig } from "next";

const nextConfig: NextConfig = {
  /* config options here */
};

export default withSentryConfig(nextConfig, {
  org: "shinagawa-web",
  project: "javascript-nextjs",
  silent: !process.env.CI,
  widenClientFileUpload: true,
  reactComponentAnnotation: {
    enabled: true,
  },
  tunnelRoute: "/monitoring",
  hideSourceMaps: true,
  disableLogger: true,
  automaticVercelMonitors: true,
});

上記コードについて詳しく解説します。

export default withSentryConfig(nextConfig, {

nextConfig を withSentryConfig でラップし、Sentry の設定を組み込んだ Next.js の設定ファイルとしてエクスポート。

  silent: !process.env.CI,

• CI 環境でのログ制御
  • ソースマップのアップロード時のログ出力を制御。
  • CI 環境 (process.env.CI が true の場合) ではログを出力、それ以外では抑制する。
  • 不要なログを減らし、ビルド時のノイズを軽減できる。

  reactComponentAnnotation: {
    enabled: true,
  },

• React コンポーネントのアノテーション
  • React コンポーネント名を Sentry のログに含める設定。
  • コンポーネント名が 記録される ため、エラーの原因をより特定しやすくなる。

  hideSourceMaps: true,

• クライアントバンドルのソースマップ非表示
  • 生成されたバンドル内にソースマップ (.map ファイル) を含めない。
  • メリット
    • ソースコードの漏洩を防ぐ（特に本番環境でセキュリティ向上）。
    • クライアント側のバンドルサイズを減らす。
  • デメリット
    • 開発中はデバッグしにくくなる
    • 例えば、開発環境では false にする

      hideSourceMaps: process.env.NODE_ENV === "production",
      

最後に

これで、Next.jsアプリケーションでのSentryの導入と動作確認が完了しました。Sentryを活用することで、エラー監視やパフォーマンス最適化が飛躍的に簡単になります。

ぜひ今回の手順を参考に、実際のプロジェクトに取り入れてみてください！