sentry-nestjs-sdk

すべてのスキル > SDK のセットアップ > NestJS SDK

Sentry NestJS SDK

NestJS プロジェクトをスキャンし、Sentry の完全なセットアップを案内する、意見の反映されたウィザードです。

このスキルを使用するタイミング

• ユーザーが NestJS アプリへの「Sentry の追加」や「Sentry のセットアップ」を依頼した場合
• ユーザーが NestJS でエラー監視、トレーシング、プロファイリング、ログ記録、メトリクス、または cron を利用したい場合
• ユーザーが @sentry/nestjs または Sentry と NestJS について言及した場合
• ユーザーが NestJS のコントローラー、サービス、ガード、マイクロサービス、またはバックグラウンドジョブを監視したい場合

注： 以下の SDK バージョンと API は @sentry/nestjs 10.x（NestJS 8～11 対応）に基づいています。 実装前に、必ず docs.sentry.io/platforms/node/guides/nestjs/ を確認してください。

---

フェーズ 1：検出

推奨を行う前に、以下のコマンドを実行してプロジェクトの状況を確認します。

# Confirm NestJS project
grep -E '"@nestjs/core"' package.json 2>/dev/null

# Check NestJS version
node -e "console.log(require('./node_modules/@nestjs/core/package.json').version)" 2>/dev/null

# Check existing Sentry
grep -i sentry package.json 2>/dev/null
ls src/instrument.ts 2>/dev/null
grep -r "Sentry.init\|@sentry" src/main.ts src/instrument.ts 2>/dev/null

# Check for existing Sentry DI wrapper (common in enterprise NestJS)
grep -rE "SENTRY.*TOKEN|SentryProxy|SentryService" src/ libs/ 2>/dev/null

# Check for config-class-based init (vs env-var-based)
grep -rE "class SentryConfig|SentryConfig" src/ libs/ 2>/dev/null

# Check if SentryModule.forRoot() is already registered in a shared module
grep -rE "SentryModule\.forRoot|SentryProxyModule" src/ libs/ 2>/dev/null

# Detect HTTP adapter (default is Express)
grep -E "FastifyAdapter|@nestjs/platform-fastify" package.json src/main.ts 2>/dev/null

# Detect GraphQL
grep -E '"@nestjs/graphql"|"apollo-server"' package.json 2>/dev/null

# Detect microservices
grep '"@nestjs/microservices"' package.json 2>/dev/null

# Detect WebSockets
grep -E '"@nestjs/websockets"|"socket.io"' package.json 2>/dev/null

# Detect task queues / scheduled jobs
grep -E '"@nestjs/bull"|"@nestjs/bullmq"|"@nestjs/schedule"|"bullmq"|"bull"' package.json 2>/dev/null

# Detect databases
grep -E '"@prisma/client"|"typeorm"|"mongoose"|"pg"|"mysql2"' package.json 2>/dev/null

# Detect AI libraries
grep -E '"openai"|"@anthropic-ai"|"langchain"|"@langchain"|"@google/generative-ai"|"ai"' package.json 2>/dev/null

# Check for companion frontend
ls -d ../frontend ../web ../client ../ui 2>/dev/null

確認事項：

• @sentry/nestjs はすでにインストールされていますか？インストールされている場合は、instrument.ts が存在し、Sentry.init() が呼び出されているかを確認します。機能の設定だけでよい可能性があります。
• Sentry DI ラッパーが検出されましたか？ → プロジェクトでは、テスト容易性のために Sentry を DI トークン（例：SENTRY_PROXY_TOKEN）の背後にラップしています。コントローラー、サービス、プロセッサーから @sentry/nestjs を直接インポートするのではなく、実行時の Sentry 呼び出し（startSpan、captureException、withIsolationScope）にはすべて、注入されたプロキシを使用してください。@sentry/nestjs を直接インポートするのは instrument.ts のみにしてください。
• 設定クラスが検出されましたか？ → プロジェクトでは、Sentry.init() のオプションに型付き設定クラス（例：YAML または @nestjs/config から読み込まれるもの）を使用しています。新しい SDK オプションは設定型に追加してください。環境ごとに設定可能にすべき値をハードコードしないでください。
• SentryModule.forRoot() はすでに登録されていますか？ → 共有モジュール（例：Sentry プロキシモジュール）に登録されている場合は、AppModule に再度追加しないでください。インターセプターが重複して登録されます。
• Express（デフォルト）アダプターですか、それとも Fastify アダプターですか？Express は完全にサポートされています。Fastify も動作しますが、既知のエッジケースがあります。
• GraphQL が検出されましたか？ → SentryGlobalFilter がネイティブに処理します。
• マイクロサービスが検出されましたか？ → RPC 例外フィルターを推奨します。
• タスクキューまたは @nestjs/schedule が検出されましたか？ → cron を推奨します。
• AI ライブラリが検出されましたか？ → 自動計装され、設定は不要です。
• Prisma が検出されましたか？ → prismaIntegration() が必要です。
• 対応するフロントエンドがありますか？ → フェーズ 4 のクロスリンクが開始されます。

---

フェーズ 2：推奨

調査結果に基づいて、具体的な提案を提示します。自由回答形式の質問はせず、推奨案を最初に示してください。

常に推奨（基本のカバー範囲）：

• ✅ エラー監視 — HTTP、GraphQL、RPC、WebSocket の各コンテキストで、未処理の例外を捕捉します
• ✅ トレーシング — ミドルウェア、ガード、パイプ、インターセプター、フィルター、ルートハンドラーを自動計装します

検出時に推奨：

• ✅ プロファイリング — CPU パフォーマンスが重要となる本番アプリ（@sentry/profiling-node）
• ✅ ロギング — 構造化 Sentry Logs と、オプションのコンソールログ捕捉
• ✅ Cron — @nestjs/schedule、Bull、または BullMQ が検出された場合
• ✅ メトリクス — ビジネス KPI または SLO の追跡
• ✅ AI 監視 — OpenAI／Anthropic／LangChain などが検出された場合（自動計装、設定不要）

推奨マトリックス：

機能	推奨する条件	リファレンス
エラー監視	常に — 譲れない基本要件	${SKILL_ROOT}/references/error-monitoring.md
トレーシング	常に — NestJS のライフサイクルを自動計装	${SKILL_ROOT}/references/tracing.md
プロファイリング	本番環境 ＋ CPU に敏感なワークロード	${SKILL_ROOT}/references/profiling.md
ロギング	常に推奨。構造化ログの集約でさらに強化	${SKILL_ROOT}/references/logging.md
メトリクス	カスタムビジネス KPI または SLO の追跡	${SKILL_ROOT}/references/metrics.md
Cron	@nestjs/schedule、Bull、または BullMQ が検出された場合	${SKILL_ROOT}/references/crons.md
AI 監視	OpenAI／Anthropic／LangChain などが検出された場合	${SKILL_ROOT}/references/ai-monitoring.md

提案： 「エラー監視＋トレーシング＋ロギングをおすすめします。プロファイリング、Cron、AI 監視も追加しますか？」

---

フェーズ 3：ガイド

インストール

# Core SDK (always required — includes @sentry/node)
npm install @sentry/nestjs

# With profiling support (optional)
npm install @sentry/nestjs @sentry/profiling-node

⚠️ @sentry/nestjs と一緒に @sentry/node をインストールしないでください — @sentry/nestjs は @sentry/node のすべてを再エクスポートします。両方をインストールすると、登録が重複します。

3 ファイルのセットアップ（必須）

Sentry SDK は、NestJS が Node.js モジュールを読み込む前に（OpenTelemetry 経由で）パッチを適用する必要があるため、NestJS では特定の 3 ファイル初期化パターンが必要です。

新しいファイルを作成する前に、フェーズ 1 の結果を確認してください。

• instrument.ts がすでに存在する場合 → 新しいファイルを作成せず、既存のファイルを変更します。
• 設定クラスが Sentry.init() を制御している場合 → 環境変数を直接埋め込まず、設定クラスからオプションを読み込みます。
• Sentry の DI ラッパーが存在する場合 → サービスやコントローラーで @sentry/nestjs を直接インポートせず、実行時の呼び出しにそのラッパーを使用します。

ステップ 1：src/instrument.ts を作成する

import * as Sentry from "@sentry/nestjs";
// Optional: add profiling
// import { nodeProfilingIntegration } from "@sentry/profiling-node";

Sentry.init({
  dsn: process.env.SENTRY_DSN,
  environment: process.env.SENTRY_ENVIRONMENT ?? "production",
  release: process.env.SENTRY_RELEASE,

  // Data collection (SDK ≥ 10.57.0 — replaces deprecated sendDefaultPii)
  dataCollection: {
    // To disable sending user data and HTTP bodies, uncomment the lines below. For more info visit:
    // https://docs.sentry.io/platforms/javascript/guides/nestjs/configuration/options/#dataCollection
    // userInfo: false,
    // httpBodies: [],
  },

  // Tracing — lower to 0.1–0.2 in high-traffic production
  tracesSampleRate: 1.0,

  // Profiling (requires @sentry/profiling-node)
  // integrations: [nodeProfilingIntegration()],
  // profileSessionSampleRate: 1.0,
  // profileLifecycle: "trace",

  // Structured logs (SDK ≥ 9.41.0)
  enableLogs: true,
});

設定駆動の Sentry.init()： フェーズ 1 で型付き設定クラス（例：SentryConfig）が見つかった場合は、生の process.env を使わず、その設定クラスからオプションを読み込みます。これは、@nestjs/config やカスタム設定ローダーを使用する NestJS アプリでよく使われる方法です。

import * as Sentry from "@sentry/nestjs";
import { loadConfiguration } from "./config";

const config = loadConfiguration();

Sentry.init({
  dsn: config.sentry.dsn,
  environment: config.sentry.environment ?? "production",
  release: config.sentry.release,
  dataCollection: config.sentry.dataCollection ?? {
    // To disable sending user data and HTTP bodies, uncomment the lines below. For more info visit:
    // https://docs.sentry.io/platforms/javascript/guides/nestjs/configuration/options/#dataCollection
    // userInfo: false,
    // httpBodies: [],
  },
  tracesSampleRate: config.sentry.tracesSampleRate ?? 1.0,
  profileSessionSampleRate: config.sentry.profilesSampleRate ?? 1.0,
  profileLifecycle: "trace",
  enableLogs: true,
});

dataCollection や profileSessionSampleRate などの新しい SDK オプションを追加する際は、環境ごとに設定できるように、設定の型にも追加してください。

ステップ 2：src/main.ts で instrument.ts を最初にインポートする

// instrument.ts MUST be the very first import — before NestJS or any other module
import "./instrument";

import { NestFactory } from "@nestjs/core";
import { AppModule } from "./app.module";

async function bootstrap() {
  const app = await NestFactory.create(AppModule);

  // Enable graceful shutdown — flushes Sentry events on SIGTERM/SIGINT
  app.enableShutdownHooks();

  await app.listen(3000);
}
bootstrap();

なぜ最初なのか？ OpenTelemetry は、http、express、データベースドライバーなどのモジュールが読み込まれる前に、それらへモンキーパッチを適用する必要があります。instrument.ts より先に読み込まれたモジュールは自動計装されません。

Step 3: src/app.module.ts に SentryModule と SentryGlobalFilter を登録する

import { Module } from "@nestjs/common";
import { APP_FILTER } from "@nestjs/core";
import { SentryModule, SentryGlobalFilter } from "@sentry/nestjs/setup";
import { AppController } from "./app.controller";
import { AppService } from "./app.service";

@Module({
  imports: [
    SentryModule.forRoot(), // Registers SentryTracingInterceptor globally
  ],
  controllers: [AppController],
  providers: [
    AppService,
    {
      provide: APP_FILTER,
      useClass: SentryGlobalFilter, // Captures all unhandled exceptions
    },
  ],
})
export class AppModule {}

各要素の役割：

• SentryModule.forRoot() — SentryTracingInterceptor をグローバルな APP_INTERCEPTOR として登録し、HTTP トランザクション名を設定できるようにします
• SentryGlobalFilter — BaseExceptionFilter を拡張し、HTTP、GraphQL（HttpException は報告せずに再スロー）、RPC の各コンテキストで例外をキャプチャします

⚠️ SentryModule.forRoot() を2回登録しないでください。 Phase 1 で共有ライブラリモジュール（SentryProxyModule や AnalyticsModule など）にすでにインポートされていることがわかった場合は、AppModule に再度追加しないでください。重複して登録すると、すべてのスパンが2回インターセプトされ、トレースデータが肥大化します。

⚠️ エントリーポイントは2つあり、インポート対象が異なります：

• @sentry/nestjs → SDK の初期化、キャプチャ API、デコレーター（SentryTraced、SentryCron、SentryExceptionCaptured）
• @sentry/nestjs/setup → NestJS の DI 構成要素（SentryModule、SentryGlobalFilter）

SentryModule をメインのエントリーポイントである @sentry/nestjs からインポートしないでください。OpenTelemetry によるパッチ適用前に @nestjs/common が読み込まれ、自動計測が機能しなくなります。

ESM のセットアップ（Node ≥ 18.19.0）

ESM アプリケーションでは、ファイルのインポートの代わりに --import を使用します。

// instrument.mjs
import * as Sentry from "@sentry/nestjs";

Sentry.init({
  dsn: process.env.SENTRY_DSN,
  tracesSampleRate: 1.0,
});

// package.json
{
  "scripts": {
    "start": "node --import ./instrument.mjs -r ts-node/register src/main.ts"
  }
}

または、環境変数で設定します。

NODE_OPTIONS="--import ./instrument.mjs" npm run start

例外フィルターのオプション

既存のアーキテクチャに合った方法を選択してください。

オプション A：既存のグローバルフィルターがない場合 — SentryGlobalFilter を使用する（推奨）

上記の Step 3 で説明した方法です。最もシンプルな選択肢です。

オプション B：既存のカスタムグローバルフィルターがある場合 — @SentryExceptionCaptured() デコレーターを追加する

import { Catch, ExceptionFilter, ArgumentsHost } from "@nestjs/common";
import { SentryExceptionCaptured } from "@sentry/nestjs";

@Catch()
export class YourExistingFilter implements ExceptionFilter {
  @SentryExceptionCaptured() // Wraps catch() to auto-report exceptions
  catch(exception: unknown, host: ArgumentsHost): void {
    // Your existing error handling continues unchanged
  }
}

オプション C：特定の例外型の場合 — 手動でキャプチャする

import { ArgumentsHost, Catch } from "@nestjs/common";
import { BaseExceptionFilter } from "@nestjs/core";
import * as Sentry from "@sentry/nestjs";

@Catch(ExampleException)
export class ExampleExceptionFilter extends BaseExceptionFilter {
  catch(exception: ExampleException, host: ArgumentsHost) {
    Sentry.captureException(exception);
    super.catch(exception, host);
  }
}

オプション D：マイクロサービスの RPC 例外

import { Catch, RpcExceptionFilter, ArgumentsHost } from "@nestjs/common";
import { Observable, throwError } from "rxjs";
import { RpcException } from "@nestjs/microservices";
import * as Sentry from "@sentry/nestjs";

@Catch(RpcException)
export class SentryRpcFilter implements RpcExceptionFilter<RpcException> {
  catch(exception: RpcException, host: ArgumentsHost): Observable<any> {
    Sentry.captureException(exception);
    return throwError(() => exception.getError());
  }
}

デコレーター

@SentryTraced(op?) — 任意のメソッドを計測する

import { Injectable } from "@nestjs/common";
import { SentryTraced } from "@sentry/nestjs";

@Injectable()
export class OrderService {
  @SentryTraced("order.process")
  async processOrder(orderId: string): Promise<void> {
    // Automatically wrapped in a Sentry span
  }

  @SentryTraced()  // Defaults to op: "function"
  async fetchInventory() { ... }
}

@SentryCron(slug, config?) — スケジュールされたジョブを監視する

import { Injectable } from "@nestjs/common";
import { Cron } from "@nestjs/schedule";
import { SentryCron } from "@sentry/nestjs";

@Injectable()
export class ReportService {
  @Cron("0 * * * *")
  @SentryCron("hourly-report", {
    // @SentryCron must come AFTER @Cron
    schedule: { type: "crontab", value: "0 * * * *" },
    checkinMargin: 2, // Minutes before marking missed
    maxRuntime: 10, // Max runtime in minutes
    timezone: "UTC",
  })
  async generateReport() {
    // Check-in sent automatically on start/success/failure
  }
}

バックグラウンドジョブのスコープ分離

バックグラウンドジョブはデフォルトの分離スコープを共有します。相互汚染を防ぐため、Sentry.withIsolationScope() でラップしてください。

import * as Sentry from "@sentry/nestjs";
import { Injectable } from "@nestjs/common";
import { Cron, CronExpression } from "@nestjs/schedule";

@Injectable()
export class JobService {
  @Cron(CronExpression.EVERY_HOUR)
  handleCron() {
    Sentry.withIsolationScope(() => {
      Sentry.setTag("job", "hourly-sync");
      this.doWork();
    });
  }
}

withIsolationScope は、@Cron()、@Interval()、@OnEvent()、@Processor() およびリクエストのライフサイクル外で実行されるすべてのコードに適用してください。

Sentry の DI ラッパーを使用する

一部の NestJS プロジェクトでは、テスト容易性と疎結合を実現するために、依存性注入トークン（例：SENTRY_PROXY_TOKEN）を介して Sentry をラップしています。Phase 1 でこのパターンが検出された場合は、実行時の Sentry 呼び出しにはすべて注入されたサービスを使用してください。コントローラー、サービス、プロセッサーで @sentry/nestjs を直接インポートしないでください。

import { Controller, Inject } from "@nestjs/common";
import { SENTRY_PROXY_TOKEN, type SentryProxyService } from "./sentry-proxy";

@Controller("orders")
export class OrderController {
  constructor(
    @Inject(SENTRY_PROXY_TOKEN) private readonly sentry: SentryProxyService,
    private readonly orderService: OrderService,
  ) {}

  @Post()
  async createOrder(@Body() dto: CreateOrderDto) {
    return this.sentry.startSpan(
      { name: "createOrder", op: "http" },
      async () => this.orderService.create(dto),
    );
  }
}

@sentry/nestjs の直接インポートが引き続き適切な箇所：

• instrument.ts — Sentry.init() には常に import * as Sentry from "@sentry/nestjs" を使用します
• DI コンテナーの外部で実行されるスタンドアロンスクリプトと例外フィルター

検証

イベントが Sentry に届くことを確認するため、テスト用エンドポイントを追加します。

import { Controller, Get } from "@nestjs/common";
import * as Sentry from "@sentry/nestjs";

@Controller()
export class DebugController {
  @Get("/debug-sentry")
  triggerError() {
    throw new Error("My first Sentry error from NestJS!");
  }

  @Get("/debug-sentry-span")
  triggerSpan() {
    return Sentry.startSpan({ op: "test", name: "NestJS Test Span" }, () => {
      return { status: "span created" };
    });
  }
}

GET /debug-sentry にリクエストを送信し、数秒以内に Sentry の Issues ダッシュボードを確認します。

合意した機能ごと

機能を1つずつ順に進めます。リファレンスを読み込み、手順に従い、次へ進む前に検証します。

機能	リファレンスファイル	読み込むタイミング
エラーモニタリング	${SKILL_ROOT}/references/error-monitoring.md	常に（基本設定）
トレーシング	${SKILL_ROOT}/references/tracing.md	常に（NestJS のルートは自動的にトレースされます）
プロファイリング	${SKILL_ROOT}/references/profiling.md	本番環境で CPU 負荷の高いアプリ
ロギング	${SKILL_ROOT}/references/logging.md	構造化ログの集約が必要な場合
メトリクス	${SKILL_ROOT}/references/metrics.md	カスタム KPI ／ SLO の追跡
Cron	${SKILL_ROOT}/references/crons.md	スケジュールされたジョブまたはタスクキューがある場合
AI モニタリング	${SKILL_ROOT}/references/ai-monitoring.md	OpenAI/Anthropic/LangChain が検出された場合

機能ごとに、Read ${SKILL_ROOT}/references/<feature>.md を実行し、手順に正確に従って、動作を検証します。

---

設定リファレンス

Sentry.init() の主要なオプション

オプション	型	デフォルト	目的
dsn	string	—	空の場合、SDK は無効になります。環境変数：SENTRY_DSN
environment	string	"production"	例："staging"。環境変数：SENTRY_ENVIRONMENT
release	string	—	例："[email protected]"。環境変数：SENTRY_RELEASE
dataCollection	object	以下を参照	SDK が収集するデータを制御します（SDK ≥ 10.57.0）
dataCollection.userInfo	boolean	true	IP アドレスとユーザーコンテキストを含めます
dataCollection.httpHeaders	object	以下を参照	リクエスト／レスポンスの HTTP ヘッダーを取得します
dataCollection.cookies	boolean|object	true	Cookie を取得します。フィルタリングには {allow: [...]} または {deny: [...]} を使用します
dataCollection.queryParams	boolean|object	true	URL クエリパラメーターを取得します。フィルタリングには {allow: [...]} または {deny: [...]} を使用します
dataCollection.genAI	object	以下を参照	AI の入力／出力の記録を制御します
sendDefaultPii	boolean	false	非推奨 — 代わりに dataCollection.userInfo を使用してください
tracesSampleRate	number	—	トランザクションのサンプルレート。undefined の場合、トレースは無効になります
tracesSampler	function	—	トランザクションごとのカスタムサンプリング（サンプルレートを上書きします）
tracePropagationTargets	Array<string|RegExp>	—	sentry-trace／baggage ヘッダーを伝播する URL
profileSessionSampleRate	number	—	継続的プロファイリングセッションのサンプルレート（SDK ≥ 10.27.0）
profileLifecycle	"trace"|"manual"	"trace"	"trace" = スパンとともにプロファイラーを自動起動します。"manual" = startProfiler()／stopProfiler() を呼び出します
enableLogs	boolean	false	構造化ログを Sentry に送信します（SDK ≥ 9.41.0）
ignoreErrors	Array<string|RegExp>	[]	抑制するエラーメッセージのパターン
ignoreTransactions	Array<string|RegExp>	[]	抑制するトランザクション名のパターン
beforeSend	function	—	エラーイベントを変更または破棄するフック
beforeSendTransaction	function	—	トランザクションイベントを変更または破棄するフック
beforeSendLog	function	—	ログイベントを変更または破棄するフック
debug	boolean	false	詳細な SDK デバッグ出力
maxBreadcrumbs	number	100	イベントごとのブレッドクラムの最大数
dataCollectionのデフォルト値：

• httpHeaders: { request: true, response: true }
• httpBodies: ["incomingRequest", "outgoingRequest", "incomingResponse", "outgoingResponse"]
• userInfo: true
• genAI: { inputs: true, outputs: true }

環境変数

変数	マッピング先	備考
SENTRY_DSN	dsn	init()にdsnが渡されていない場合に使用します
SENTRY_RELEASE	release	Git SHA、Heroku、CircleCIからも自動検出されます
SENTRY_ENVIRONMENT	environment	"production"にフォールバックします
SENTRY_AUTH_TOKEN	CLI/source maps	npx @sentry/wizard@latest -i sourcemaps用
SENTRY_ORG	CLI/source maps	組織のスラッグ
SENTRY_PROJECT	CLI/source maps	プロジェクトのスラッグ

自動的に有効になるインテグレーション

これらのインテグレーションはパッケージが検出されると自動的に有効になります。integrations: [...]は不要です。

自動的に有効になるインテグレーション	備考
httpIntegration	http／https／fetch経由の送信HTTP呼び出し
expressIntegration	Expressアダプター（NestJSのデフォルト）
nestIntegration	NestJSのライフサイクル（ミドルウェア、ガード、パイプ、インターセプター、ハンドラー）
onUncaughtExceptionIntegration	キャッチされない例外
onUnhandledRejectionIntegration	処理されないPromiseの拒否
openAIIntegration	OpenAI SDK（インストール時）
anthropicAIIntegration	Anthropic SDK（インストール時）
langchainIntegration	LangChain（インストール時）
graphqlIntegration	GraphQL（graphqlパッケージが存在する場合）
postgresIntegration	pgドライバー
mysqlIntegration	mysql／mysql2
mongoIntegration	MongoDB／Mongoose
redisIntegration	ioredis／redis

手動設定が必要なインテグレーション

インテグレーション	追加する場合	コード
nodeProfilingIntegration	プロファイリングが必要な場合	import { nodeProfilingIntegration } from "@sentry/profiling-node"
prismaIntegration	Prisma ORMを使用する場合	integrations: [Sentry.prismaIntegration()]
consoleLoggingIntegration	コンソール出力を取得する場合	integrations: [Sentry.consoleLoggingIntegration()]
localVariablesIntegration	エラー内のローカル変数値を取得する場合	integrations: [Sentry.localVariablesIntegration()]

---

検証

Sentry がイベントを受信していることをテストします。

// Add a test endpoint (remove before production)
@Get("/debug-sentry")
getError() {
  throw new Error("My first Sentry error!");
}

または、クラッシュせずにテストメッセージを送信します。

import * as Sentry from "@sentry/nestjs";
Sentry.captureMessage("NestJS Sentry SDK test");

何も表示されない場合：

1. Sentry.init() で debug: true を設定します — SDK の内部情報が標準出力に表示されます
2. 実行中のプロセスで SENTRY_DSN 環境変数が設定されていることを確認します
3. import "./instrument" が main.ts の先頭行にあることを確認します
4. SentryModule.forRoot() が AppModule にインポートされていることを確認します
5. DSN の形式を確認します：https://<key>@o<org>.ingest.sentry.io/<project>

---

フェーズ 4：相互リンク

NestJS のセットアップが完了したら、Sentry が未導入の関連フロントエンドがないか確認します。

ls -d ../frontend ../web ../client ../ui 2>/dev/null
cat ../frontend/package.json ../web/package.json 2>/dev/null \
  | grep -E '"react"|"svelte"|"vue"|"next"|"nuxt"'

Sentry が導入されていないフロントエンドがある場合は、対応するスキルを提案します。

検出されたフロントエンド	提案するスキル
Next.js	sentry-nextjs-sdk
React	sentry-react-sdk
Svelte / SvelteKit	sentry-svelte-sdk
Vue / Nuxt	@sentry/vue を使用します — docs.sentry.io/platforms/javascript/guides/vue/ を参照してください
React Native / Expo	sentry-react-native-sdk

---

トラブルシューティング

問題	解決策
イベントが表示されない	debug: true を設定し、SENTRY_DSN を確認して、instrument.ts が最初にインポートされていることを確認します
DSN の形式が正しくないというエラー	形式：https://<key>@o<org>.ingest.sentry.io/<project>
例外がキャプチャされない	AppModule で APP_FILTER を通じて SentryGlobalFilter が登録されていることを確認します
自動計測が動作しない	instrument.ts は main.ts で 最初にインポートする必要があります。すべての NestJS のインポートより前に配置してください
プロファイリングが開始されない	tracesSampleRate > 0、profileSessionSampleRate > 0、および @sentry/profiling-node のインストールが必要です
enableLogs が動作しない	SDK ≥ 9.41.0 が必要です
トレースが表示されない	tracesSampleRate が設定されている（undefined ではない）ことを確認します
トランザクションが多すぎる	tracesSampleRate を下げるか、tracesSampler を使用してヘルスチェックを除外します
Fastify と GraphQL の問題	既知のエッジケースです。GitHub #13388 を参照してください。GraphQL には Express を推奨します
バックグラウンドジョブのイベントが混在する	ジョブ本体を Sentry.withIsolationScope(() => { ... }) で囲みます
Prisma のスパンがない	Sentry.init() に integrations: [Sentry.prismaIntegration()] を追加します
ESM の構文エラー	registerEsmLoaderHooks: false を設定します（ESM フックが無効になり、ESM モジュールの自動計測も無効になります）
SentryModule によって計測に問題が発生する	必ず @sentry/nestjs/setup からインポートしてください。@sentry/nestjs からはインポートしないでください
RPC の例外がキャプチャされない	専用の SentryRpcExceptionFilter を追加します（例外フィルターのセクションのオプション D を参照）
WebSocket の例外がキャプチャされない	ゲートウェイの handleConnection／handleDisconnect に @SentryExceptionCaptured() を使用します
@SentryCron が実行されない	デコレーターの順序が重要です。@SentryCron は必ず @Cron の後に配置してください
TypeScript のパスエイリアスの問題	tsconfig.json の paths が設定され、main.ts の場所から instrument を解決できることを確認します
import * as Sentry に関する ESLint エラー	多くのプロジェクトでは名前空間インポートが禁止されています。名前付きインポート（import { startSpan, captureException } from "@sentry/nestjs"）を使用するか、プロジェクトの DI プロキシを使用してください
profilesSampleRate と profileSessionSampleRate	profilesSampleRate は SDK 10.x で非推奨です。代わりに profileSessionSampleRate と profileLifecycle: "trace" を使用してください
すべてのリクエストでスパンが重複する	複数のモジュールで SentryModule.forRoot() が登録されています。一度だけ呼び出されていることを確認してください。共有モジュール／ライブラリモジュールを確認します
instrument.ts で設定プロパティが認識されない	型付きの設定クラスを使用する場合、新しい SDK オプションを設定型の定義に追加し、プロジェクトを再ビルドしてからでないと TypeScript に認識されません

バージョン要件

機能	SDK の最小バージョン
@sentry/nestjs パッケージ	8.0.0
@SentryTraced デコレーター	8.15.0
@SentryCron デコレーター	8.16.0
Event Emitter の自動計装	8.39.0
SentryGlobalFilter（統合版）	8.40.0
Sentry.logger API（enableLogs）	9.41.0
profileSessionSampleRate	10.27.0
Node.js の要件	≥ 18
ESM --import 用の Node.js	≥ 18.19.0
NestJS の互換性	8.x – 11.x