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

Sentry NestJS SDK

NestJSプロジェクトをスキャンして、完全なSentryセットアップをガイドする意見主張型ウィザード。

このスキルを呼び出すタイミング

• ユーザーがNestJSアプリで「Sentryを追加する」または「Sentryをセットアップする」と尋ねた場合
• ユーザーがNestJSでエラー監視、トレーシング、プロファイリング、ロギング、メトリクス、またはcronsを希望している場合
• ユーザーが @sentry/nestjs またはSentry + NestJSに言及した場合
• ユーザーがNestJSコントローラー、サービス、ガード、マイクロサービス、またはバックグラウンドジョブを監視したい場合

注： 以下のSDKバージョンとAPIは @sentry/nestjs 10.x（NestJS 8–11サポート）を反映しています。 実装前に必ず docs.sentry.io/platforms/node/guides/nestjs/ で確認してください。

---

フェーズ 1: 検出

推奨を行う前にプロジェクトを理解するために、以下のコマンドを実行します：

# NestJSプロジェクトの確認
grep -E '"@nestjs/core"' package.json 2>/dev/null

# NestJSバージョン確認
node -e "console.log(require('./node_modules/@nestjs/core/package.json').version)" 2>/dev/null

# 既存の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

# 既存のSentry DIラッパー確認（NestJSエンタープライズで一般的）
grep -rE "SENTRY.*TOKEN|SentryProxy|SentryService" src/ libs/ 2>/dev/null

# 設定クラスベースの初期化確認（vs env変数ベース）
grep -rE "class SentryConfig|SentryConfig" src/ libs/ 2>/dev/null

# 共有モジュールで SentryModule.forRoot() が既に登録されているかを確認
grep -rE "SentryModule\.forRoot|SentryProxyModule" src/ libs/ 2>/dev/null

# HTTPアダプター検出（デフォルトはExpress）
grep -E "FastifyAdapter|@nestjs/platform-fastify" package.json src/main.ts 2>/dev/null

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

# マイクロサービス検出
grep '"@nestjs/microservices"' package.json 2>/dev/null

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

# タスクキュー/スケジュール済みジョブ検出
grep -E '"@nestjs/bull"|"@nestjs/bullmq"|"@nestjs/schedule"|"bullmq"|"bull"' package.json 2>/dev/null

# データベース検出
grep -E '"@prisma/client"|"typeorm"|"mongoose"|"pg"|"mysql2"' package.json 2>/dev/null

# AIライブラリ検出
grep -E '"openai"|"@anthropic-ai"|"langchain"|"@langchain"|"@google/generative-ai"|"ai"' package.json 2>/dev/null

# コンパニオンフロントエンド確認
ls -d ../frontend ../web ../client ../ui 2>/dev/null

注意すべきこと：

• @sentry/nestjs は既にインストール済みですか？はいの場合、instrument.ts が存在し Sentry.init() が呼び出されているか確認します。機能設定のみが必要な場合があります。
• Sentry DIラッパーが検出された？ → プロジェクトはテスト性のためにSentryをDIトークン（例：SENTRY_PROXY_TOKEN）の背後にラップしています。すべてのランタイムSentry呼び出し（startSpan、captureException、withIsolationScope）には、コントローラー、サービス、プロセッサーで @sentry/nestjs を直接インポートする代わりに、注入されたプロキシを使用します。instrument.ts のみが @sentry/nestjs を直接インポートするべきです。
• 設定クラスが検出された？ → プロジェクトは Sentry.init() オプション用に型付き設定クラスを使用します（例：YAMLまたは @nestjs/config から読み込まれます）。新しいSDKオプション（例：sendDefaultPii、profileSessionSampleRate）を追加する場合は、設定型に追加する必要があります。環境ごとに設定可能であるべき値をハードコードしないでください。
• 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 +オプションのコンソールキャプチャ
• ✅ Crons — @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
Crons	@nestjs/schedule、Bull、またはBullMQ検出時	${SKILL_ROOT}/references/crons.md
AI監視	OpenAI/Anthropic/LangChain/等検出時	${SKILL_ROOT}/references/ai-monitoring.md

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

---

フェーズ 3: ガイド

インストール

# コアSDK（常に必須 — @sentry/nodeを含む）
npm install @sentry/nestjs

# プロファイリングサポート付き（オプション）
npm install @sentry/nestjs @sentry/profiling-node

⚠️ @sentry/node を @sentry/nestjs と共にインストールしないでください — @sentry/nestjs は @sentry/node からすべてを再エクスポートしています。両方をインストールするとダブル登録が発生します。

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

NestJSはセットアップパターンを特定する必要があります。Sentry SDKはNode.jsモジュール（OpenTelemetry経由）パッチを当てる必要があり、NestJSがロードする前に行う必要があります。

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

• instrument.ts が既に存在する場合 → 新しいものを作成せず、それを変更してください。
• 設定クラスが Sentry.init() を駆動する場合 → env変数をハードコードする代わりに設定から オプションを読み込みます。
• Sentry DIラッパーが存在する場合 → サービス/コントローラーで @sentry/nestjs を直接インポートする代わりに、それを使用します。

ステップ 1: src/instrument.ts を作成

import * as Sentry from "@sentry/nestjs";
// オプション: プロファイリングを追加
// import { nodeProfilingIntegration } from "@sentry/profiling-node";

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

  // トレーシング — 本番環境の高トラフィックでは 0.1–0.2 に下げます
  tracesSampleRate: 1.0,

  // プロファイリング（@sentry/profiling-nodeが必須）
  // integrations: [nodeProfilingIntegration()],
  // profileSessionSampleRate: 1.0,
  // profileLifecycle: "trace",

  // 構造化ログ（SDK ≥ 9.41.0）
  enableLogs: true,
});

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

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,
  sendDefaultPii: config.sentry.sendDefaultPii ?? true,
  tracesSampleRate: config.sentry.tracesSampleRate ?? 1.0,
  profileSessionSampleRate: config.sentry.profilesSampleRate ?? 1.0,
  profileLifecycle: "trace",
  enableLogs: true,
});

新しいSDKオプション（例：sendDefaultPii、profileSessionSampleRate）を追加する場合は、設定型に追加して、環境ごとに設定できるようにします。

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

// instrument.ts は最初のインポート — NestJSまたはその他のモジュールの前
import "./instrument";

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

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

  // グレースフルシャットダウンを有効にする — SIGTERM/SIGINTでSentryイベントをフラッシュします
  app.enableShutdownHooks();

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

なぜ最初？ OpenTelemetryは http、express、データベースドライバー、およびその他のモジュールにモンキーパッチを当てる必要があります。instrument.ts の前にロードされるモジュールは自動計測されません。

ステップ 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(), // グローバルに SentryTracingInterceptor を登録
  ],
  controllers: [AppController],
  providers: [
    AppService,
    {
      provide: APP_FILTER,
      useClass: SentryGlobalFilter, // すべての未処理例外をキャプチャ
    },
  ],
})
export class AppModule {}

各ピースの機能：

• SentryModule.forRoot() — グローバルな APP_INTERCEPTOR として SentryTracingInterceptor を登録し、HTTPトランザクション命名を有効にします
• SentryGlobalFilter — BaseExceptionFilter を拡張し、HTTP、GraphQL（HttpException を再スローしてレポートなし）、およびRPCコンテキスト全体で例外をキャプチャします

⚠️ SentryModule.forRoot() を2回登録しないでください。 フェーズ1で共有ライブラリモジュール（例：SentryProxyModule または AnalyticsModule）で既にインポートされていることが判明した場合は、AppModule に再度追加しないでください。重複登録により、すべてのスパンがインターセプターで2回処理され、トレースデータが膨れ上がります。

⚠️ 2つのエントリーポイント、異なるインポート：

• @sentry/nestjs → SDK初期化、キャプチャAPI、デコレーター（SentryTraced、SentryCron、SentryExceptionCaptured）
• @sentry/nestjs/setup → NestJS DIコンストラクト（SentryModule、SentryGlobalFilter）

@sentry/nestjs（メインエントリーポイント）から SentryModule をインポートしないでください。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 を使用（推奨）

上記のステップ3で既にカバーされています。これが最も簡単なオプションです。

オプション B: 既存のカスタムグローバルフィルター — @SentryExceptionCaptured() デコレーターを追加

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

@Catch()
export class YourExistingFilter implements ExceptionFilter {
  @SentryExceptionCaptured() // catch() をラップして自動的に例外をレポート
  catch(exception: unknown, host: ArgumentsHost): void {
    // 既存のエラーハンドリングは変わりません
  }
}

オプション 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> {
    // 自動的にSentryスパンでラップされます
  }

  @SentryTraced()  // デフォルトは 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 は @Cron の後に来る必要があります
    schedule: { type: "crontab", value: "0 * * * *" },
    checkinMargin: 2, // マークされるまでの分数
    maxRuntime: 10, // 最大実行時間（分）
    timezone: "UTC",
  })
  async generateReport() {
    // チェックイン自動送信（開始/成功/失敗時）
  }
}

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

バックグラウンドジョブはデフォルトの分離スコープを共有します。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を依存関係注入トークン（例：SENTRY_PROXY_TOKEN）の背後にラップします。フェーズ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イシューダッシュボードで確認します。

同意された機能ごと

機能を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トラッキング
Crons	${SKILL_ROOT}/references/crons.md	スケジュール済みジョブまたはタスクキュー
AI監視	${SKILL_ROOT}/references/ai-monitoring.md	OpenAI/Anthropic/LangChain検出

各機能について：${SKILL_ROOT}/references/<feature>.md を読む、手順に正確に従う、それが機能することを検証します。

---

設定リファレンス

キー Sentry.init() オプション

オプション	型	デフォルト	目的
dsn	string	—	空の場合はSDK無効；env: SENTRY_DSN
environment	string	"production"	例："staging"；env: SENTRY_ENVIRONMENT
release	string	—	例："myapp@1.0.0"；env: SENTRY_RELEASE
sendDefaultPii	boolean	false	IPアドレスとリクエストヘッダーを含める
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" = 呼び出し
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	イベント当たりの最大パンくず数

環境変数

変数	マップ先	注
SENTRY_DSN	dsn	dsn が init() に渡されない場合は使用
SENTRY_RELEASE	release	git SHA、Heroku、CircleCI から自動検出
SENTRY_ENVIRONMENT	environment	"production" にフォールバック
SENTRY_AUTH_TOKEN	CLI/ソースマップ	npx @sentry/wizard@latest -i sourcemaps 用
SENTRY_ORG	CLI/ソースマップ	Organization slug
SENTRY_PROJECT	CLI/ソースマップ	Project slug

自動有効化される統合

これらの統合は、パッケージが検出されると自動的にアクティブになります。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がイベントを受信していることをテストします：

// テストエンドポイントを追加（本番環境前に削除）
@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内部をstdoutに出力
2. SENTRY_DSN env変数が実行中のプロセスで設定されていることを確認
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>
例外がキャプチャされていない	SentryGlobalFilter が APP_FILTER 経由で AppModule で登録されていることを確認
自動計測が機能していない	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スパンが欠落	integrations: [Sentry.prismaIntegration()] を Sentry.init() に追加
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 vs profileSessionSampleRate	profilesSampleRate はSDK 10.x で廃止予定。代わりに profileSessionSampleRate + profileLifecycle: "trace" を使用
すべてのリクエストで重複スパン	SentryModule.forRoot() が複数のモジュールで登録されています。1回だけ呼び出されていることを確認 — 共有/ライブラリモジュールを確認
instrument.ts で設定プロパティが認識されない	型付き設定クラスを使用する場合、新しいSDKオプションを設定型定義に追加し、プロジェクトを再構築してからTypeScriptが認識できます

バージョン要件

機能	最小SDKバージョン
@sentry/nestjs パッケージ	8.0.0
@SentryTraced デコレーター	8.15.0
@SentryCron デコレーター	8.16.0
イベントエミッター自動計測	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