sentry-node-sdk

Name: sentry-node-sdk
Author: getsentry

github.com/getsentry開発2723.4k 回インストール今日更新

リポジトリ

sentry-node-sdk について

Node.js、Bun、Deno を使うサーバーサイドの JavaScript・TypeScript プロジェクト向けに、Sentry の導入を案内するスキルです。ランタイムや既存の構成を調べ、環境に応じた機能を提案します。

主な機能

01Node.js・Bun・Deno の識別
02フレームワークと既存設定の検出
03SDK の導入と起動設定の案内
04エラー監視とトレースの設定
05ログ・プロファイリング・Cron 監視の設定

活用シーン

01サーバーサイド JavaScript プロジェクトへの Sentry 導入
02ランタイムに応じたエラー・トレース監視の設定
03スケジュールジョブや AI 呼び出しの監視

インストール

コマンドをコピーしてターミナルで実行します。

$npx skills add https://github.com/getsentry/sentry-for-ai --skill sentry-node-sdk

インストール後、Claude Code で/sentry-node-sdkを入力して読み込まれたか確認します。

同梱ファイル

SKILL.md と一緒にインストールされる参考資料やスクリプト。

references/

ai-monitoring.md

crons.md

error-monitoring.md

logging.md

metrics.md

profiling.md

tracing.md

詳細

すべてのスキル > SDK のセットアップ > Node.js / Bun / Deno SDK

Sentry Node.js / Bun / Deno SDK

プロジェクトをスキャンし、サーバーサイドの JavaScript および TypeScript ランタイム（Node.js、Bun、Deno）で Sentry を完全にセットアップできるよう案内する、独自の判断基準を備えたウィザードです。

このスキルを使用する場面

ユーザーが「Node.js に Sentry を追加して」「Bun」または「Deno」と依頼した場合
ユーザーが @sentry/node、@sentry/bun、または @sentry/deno のインストールや設定を希望する場合
ユーザーがバックエンドの JS/TS アプリで、エラー監視、トレーシング、ログ記録、プロファイリング、Cron、メトリクス、または AI 監視を希望する場合
ユーザーが instrument.js、--import ./instrument.mjs、bun --preload、または npm:@sentry/deno について質問した場合
ユーザーが Express、Fastify、Koa、Hapi、Connect、Bun.serve()、または Deno.serve() の監視を希望する場合

NestJS の場合 sentry-nestjs-sdk を使用してください。NestJS ネイティブのデコレーターとフィルターを使うためです。 Next.js の場合 sentry-nextjs-sdk を使用してください。3 つのランタイム（ブラウザー、サーバー、エッジ）のアーキテクチャに対応しています。

注: 以下の SDK バージョンは、執筆時点での最新の Sentry ドキュメント（@sentry/node ≥10.42.0、@sentry/bun ≥10.42.0、@sentry/deno ≥10.42.0）に基づいています。実装前に必ず docs.sentry.io/platforms/javascript/guides/node/ で確認してください。

フェーズ 1：検出

次のコマンドを実行して、ランタイム、フレームワーク、既存の Sentry セットアップを特定します。

# Detect runtime
bun --version 2>/dev/null && echo "Bun detected"
deno --version 2>/dev/null && echo "Deno detected"
node --version 2>/dev/null && echo "Node.js detected"

# Detect existing Sentry packages
cat package.json 2>/dev/null | grep -E '"@sentry/'
cat deno.json deno.jsonc 2>/dev/null | grep -i sentry

# Detect Node.js framework
cat package.json 2>/dev/null | grep -E '"express"|"fastify"|"@hapi/hapi"|"koa"|"@nestjs/core"|"connect"'

# Detect Bun-specific frameworks
cat package.json 2>/dev/null | grep -E '"elysia"|"hono"'

# Detect Deno frameworks (deno.json imports)
cat deno.json deno.jsonc 2>/dev/null | grep -E '"oak"|"hono"|"fresh"'

# Detect module system (Node.js)
cat package.json 2>/dev/null | grep '"type"'
ls *.mjs *.cjs 2>/dev/null | head -5

# Detect existing instrument file
ls instrument.js instrument.mjs instrument.ts instrument.cjs 2>/dev/null

# Detect logging libraries
cat package.json 2>/dev/null | grep -E '"winston"|"pino"|"bunyan"'

# Detect cron / scheduling
cat package.json 2>/dev/null | grep -E '"node-cron"|"cron"|"agenda"|"bull"|"bullmq"'

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

# Detect OpenTelemetry tracing
cat package.json 2>/dev/null | grep -E '"@opentelemetry/sdk-node"|"@opentelemetry/sdk-trace-node"|"@opentelemetry/sdk-trace-base"'
grep -rn "NodeTracerProvider\|trace\.getTracer\|startActiveSpan" \
  --include="*.ts" --include="*.js" --include="*.mjs" 2>/dev/null | head -5

# Check for companion frontend
ls frontend/ web/ client/ ui/ 2>/dev/null
cat package.json 2>/dev/null | grep -E '"react"|"vue"|"svelte"|"next"'

確認事項：

質問	影響
ランタイムはどれですか？（Node.js / Bun / Deno）	パッケージ、初期化パターン、プリロードフラグが決まります
Node.js：ESM と CJS のどちらですか？	ESM では `--import ./instrument.mjs` が必要です。CJS では `require("./instrument")` を使用します
フレームワークが検出されましたか？	登録するエラーハンドラーが決まります
`@sentry/*` はすでにインストールされていますか？	インストールを省略し、機能の設定に進みます
`instrument.js` / `instrument.mjs` はすでに存在しますか？	上書きせず、既存のファイルに統合します
ロギングライブラリが検出されましたか？	Sentry Logs を推奨します
Cron / ジョブスケジューラーが検出されましたか？	Cron 監視を推奨します
AI ライブラリが検出されましたか？	AI 監視を推奨します
OpenTelemetry トレーシングが検出されましたか？	ネイティブトレーシングではなく OTLP の経路を使用します
関連するフロントエンドが見つかりましたか？	フェーズ 4 へのクロスリンクを実行します

フェーズ 2：推奨事項

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

OTel の検出結果に基づくルート：

OTel トレーシングが検出された場合（package.json に @opentelemetry/sdk-node または @opentelemetry/sdk-trace-node がある、あるいはソースコードに NodeTracerProvider がある）→ OTLP 経路を使用します：@sentry/node-core/light 経由で otlpIntegration() を使用し、tracesSampleRate は設定しません。Sentry はエラーを OTel トレースに自動的に関連付けます。

推奨（基本的なカバレッジ）：

✅ エラーモニタリング — 常に有効にします。未処理の例外、Promise の拒否、フレームワークのエラーを捕捉します。
✅ トレーシング — OpenTelemetry による HTTP、DB、キューのインストルメンテーションを自動で行います。

オプション（可観測性の強化）：

⚡ ロギング — Sentry.logger.* による構造化ログです。winston／pino／bunyan を使用している場合や、ログ検索が必要な場合に推奨します。
⚡ プロファイリング — CPU の継続的なプロファイリングです（Node.js のみ。Bun または Deno では利用できません）。OTLP 経路では利用できません。
⚡ AI モニタリング — OpenAI、Anthropic、LangChain、Vercel AI SDK に対応します。AI／LLM 呼び出しが検出された場合に推奨します。
⚡ Cron — 実行されなかった、または失敗したスケジュール済みジョブを検出します。node-cron、Bull、または Agenda が検出された場合に推奨します。
⚡ メトリクス — カスタムカウンター、ゲージ、分布を扱います。カスタム KPI が必要な場合に推奨します。
⚡ ランタイムメトリクス — メモリ、CPU、イベントループのメトリクスを自動収集します。nodeRuntimeMetricsIntegration()（Node.js）／bunRuntimeMetricsIntegration()（Bun）。

推奨ロジック：

機能	次の場合に推奨
エラーモニタリング	常に — 必須の基本機能です
OTLP インテグレーション	OTel トレーシングが検出された場合 — ネイティブのトレーシングに置き換わります
トレーシング	サーバーアプリでは常に — HTTP スパンと DB スパンは価値が高いです。OTel トレーシングが検出された場合はスキップします
ロギング	アプリで winston、pino、bunyan を使用している場合、またはログとトレースの相関が必要な場合
プロファイリング	Node.js のみ — パフォーマンスが重要なサービスで、ネイティブアドオンに互換性がある場合。OTel トレーシングが検出された場合はスキップします（`tracesSampleRate` が必要で、OTLP と互換性がありません）
AI モニタリング	アプリが OpenAI、Anthropic、LangChain、Vercel AI、または Google GenAI を呼び出す場合
Cron	アプリが node-cron、Bull、BullMQ、Agenda、またはその他のスケジュール済みタスクのパターンを使用している場合
メトリクス	アプリでカスタムカウンター、ゲージ、またはヒストグラムが必要な場合
ランタイムメトリクス	メモリ／CPU／イベントループの可視性を自動で得たい Node.js または Bun のサービス

OTel トレーシングが検出された場合： 「プロジェクトで OpenTelemetry トレーシングを確認しました。既存の OTel セットアップ経由の Sentry の OTLP インテグレーションによるトレーシングと、エラーモニタリング、Sentry ロギング［該当する場合はメトリクス／Cron／AI モニタリングも］をおすすめします。進めてもよろしいですか？」

OTel がない場合： 「エラーモニタリングとトレーシングのセットアップをおすすめします。ロギングやプロファイリングも追加しますか？」

フェーズ 3：手順

ランタイム：Node.js

オプション 1：ウィザード（Node.js におすすめ）

この操作はご自身で実行する必要があります — ウィザードはログインのためにブラウザーを開き、エージェントが処理できない対話形式の入力を求めます。以下をコピーしてターミナルに貼り付けてください。
npx @sentry/wizard@latest -i node
ログイン、組織／プロジェクトの選択、SDK のインストール、instrument.js の作成、package.json スクリプトの更新を行います。

完了したら戻ってきて、検証に進んでください。

ユーザーがウィザードをスキップした場合は、以下のオプション 2（手動セットアップ）に進みます。

オプション 2：手動セットアップ — Node.js

インストール

npm install @sentry/node --save
# or
yarn add @sentry/node
# or
pnpm add @sentry/node

Instrument ファイルの作成

CommonJS（instrument.js）：

// instrument.js — must be loaded before all other modules
const Sentry = require("@sentry/node");

Sentry.init({
  dsn: process.env.SENTRY_DSN ?? "___DSN___",

  dataCollection: {
    // To disable sending user data and HTTP bodies, uncomment the lines below. For more info visit:
    // https://docs.sentry.io/platforms/javascript/guides/node/configuration/options/#dataCollection
    // userInfo: false,
    // httpBodies: [],
  },

  // 100% in dev, lower in production
  tracesSampleRate: process.env.NODE_ENV === "development" ? 1.0 : 0.1,

  // Capture local variable values in stack frames
  includeLocalVariables: true,

  enableLogs: true,
});

ESM（instrument.mjs）：

// instrument.mjs — loaded via --import flag before any other module
import * as Sentry from "@sentry/node";

Sentry.init({
  dsn: process.env.SENTRY_DSN ?? "___DSN___",

  dataCollection: {
    // To disable sending user data and HTTP bodies, uncomment the lines below. For more info visit:
    // https://docs.sentry.io/platforms/javascript/guides/node/configuration/options/#dataCollection
    // userInfo: false,
    // httpBodies: [],
  },
  tracesSampleRate: process.env.NODE_ENV === "development" ? 1.0 : 0.1,
  includeLocalVariables: true,
  enableLogs: true,
});

Sentry を最初に読み込んでアプリを起動する

CommonJS — エントリーファイルの先頭行に require("./instrument") を追加します。

// app.js
require("./instrument"); // must be first

const express = require("express");
// ... rest of your app

ESM — --import フラグを使用して、他のすべてのモジュールより先に Sentry を読み込みます（Node.js 18.19.0 以降が必要です）。

node --import ./instrument.mjs app.mjs

package.json のスクリプトに追加します。

{
  "scripts": {
    "start": "node --import ./instrument.mjs server.mjs",
    "dev": "node --import ./instrument.mjs --watch server.mjs"
  }
}

または、環境変数を使用します（既存の起動コマンドをラップする場合に便利です）。

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

フレームワークのエラーハンドラー

フレームワークのエラーを捕捉できるように、すべてのルートの後にSentryのエラーハンドラーを登録します。

Express：

const express = require("express");
const Sentry = require("@sentry/node");

const app = express();

// ... your routes

// Add AFTER all routes — captures 5xx errors by default
Sentry.setupExpressErrorHandler(app);

// Optional: capture 4xx errors too
// Sentry.setupExpressErrorHandler(app, {
//   shouldHandleError(error) { return error.status >= 400; },
// });

app.listen(3000);

Fastify：

const Fastify = require("fastify");
const Sentry = require("@sentry/node");

const fastify = Fastify();

// Add BEFORE routes (unlike Express!)
Sentry.setupFastifyErrorHandler(fastify);

// ... your routes

await fastify.listen({ port: 3000 });

Koa：

const Koa = require("koa");
const Sentry = require("@sentry/node");

const app = new Koa();

// Add as FIRST middleware (catches errors thrown by later middleware)
Sentry.setupKoaErrorHandler(app);

// ... your other middleware and routes

app.listen(3000);

Hapi（非同期 — awaitが必要）：

const Hapi = require("@hapi/hapi");
const Sentry = require("@sentry/node");

const server = Hapi.server({ port: 3000 });

// ... your routes

// Must await — Hapi registration is async
await Sentry.setupHapiErrorHandler(server);

await server.start();

Connect：

const connect = require("connect");
const Sentry = require("@sentry/node");

const app = connect();

// Add BEFORE routes (like Fastify and Koa)
Sentry.setupConnectErrorHandler(app);

// ... your middleware and routes

require("http").createServer(app).listen(3000);

NestJS — 詳細な内容を網羅した専用のスキルがあります。

代わりにsentry-nestjs-sdkスキルを使用してください。 NestJSは、NestJSネイティブの構成要素を備えた別のパッケージ（@sentry/nestjs）を使用します。 SentryModule.forRoot()、SentryGlobalFilter、@SentryTraced、@SentryCronデコレーター、 GraphQL／マイクロサービスのサポートが含まれます。NestJSのセットアップ全体については、このスキルを読み込んでください。

Vanilla Node.jsのhttpモジュール — リクエストハンドラーを手動でラップします。

const http = require("http");
const Sentry = require("@sentry/node");

const server = http.createServer((req, res) => {
  Sentry.withIsolationScope(() => {
    try {
      // your handler
      res.end("OK");
    } catch (err) {
      Sentry.captureException(err);
      res.writeHead(500);
      res.end("Internal Server Error");
    }
  });
});

server.listen(3000);

フレームワークのエラーハンドラーの概要：

フレームワーク	関数	配置場所	非同期？
Express	`setupExpressErrorHandler(app)`	すべてのルートの後	いいえ
Fastify	`setupFastifyErrorHandler(fastify)`	ルートの前	いいえ
Koa	`setupKoaErrorHandler(app)`	最初のミドルウェア	いいえ
Hapi	`setupHapiErrorHandler(server)`	`server.start()`の前	はい
Connect	`setupConnectErrorHandler(app)`	ルートの前	いいえ
NestJS	→ `sentry-nestjs-sdk`を使用	専用スキル	—

ランタイム：Bun

Bun向けのウィザードはありません。 手動でセットアップしてください。

インストール

bun add @sentry/bun

`instrument.ts`（または`instrument.js`）を作成します

// instrument.ts
import * as Sentry from "@sentry/bun";

Sentry.init({
  dsn: process.env.SENTRY_DSN ?? "___DSN___",

  dataCollection: {
    // To disable sending user data and HTTP bodies, uncomment the lines below. For more info visit:
    // https://docs.sentry.io/platforms/javascript/guides/node/configuration/options/#dataCollection
    // userInfo: false,
    // httpBodies: [],
  },
  tracesSampleRate: process.env.NODE_ENV === "development" ? 1.0 : 0.1,
  enableLogs: true,
});

`--preload`を指定してアプリを起動します

bun --preload ./instrument.ts server.ts

package.jsonに追加します。

{
  "scripts": {
    "start": "bun --preload ./instrument.ts server.ts",
    "dev": "bun --watch --preload ./instrument.ts server.ts"
  }
}

Bun.serve() — 自動計装

@sentry/bunはJavaScript Proxyを介してBun.serve()を自動的に計装します。追加のセットアップは不要です。--preloadを指定して初期化するだけで、Bun.serve()の呼び出しがトレースされます。

// server.ts
const server = Bun.serve({
  port: 3000,
  fetch(req) {
    return new Response("Hello from Bun!");
  },
});

Bunでのフレームワークエラーハンドラー

BunではExpress、Fastify、Hono、Elysiaを実行できます。同じ@sentry/bunのインポートと、@sentry/bunから再エクスポートされる@sentry/nodeのエラーハンドラー関数を使用します。

import * as Sentry from "@sentry/bun";
import express from "express";

const app = express();
// ... routes
Sentry.setupExpressErrorHandler(app);
app.listen(3000);

Bunの機能サポート

機能	Bunのサポート	備考
エラー監視	✅ 完全対応	Nodeと同じAPI
トレーシング	✅ `@sentry/node` OTel経由	ほとんどの自動計装が動作します
ロギング	✅ 完全対応	`enableLogs: true`と`Sentry.logger.*`
プロファイリング	❌ 利用不可	`@sentry/profiling-node`は、Bunと互換性のないネイティブアドオンを使用します
メトリクス	✅ 完全対応	`Sentry.metrics.*`
ランタイムメトリクス	✅ 完全対応	`bunRuntimeMetricsIntegration()` — メモリ、CPU、イベントループ（イベントループ遅延のパーセンタイルは対象外）
Cron	✅ 完全対応	`Sentry.withMonitor()`
AI監視	✅ 完全対応	OpenAI、Anthropicのインテグレーションが動作します

ランタイム：Deno

Deno向けのウィザードはありません。 手動でセットアップしてください。 Deno 2.0以降が必要です。 Deno 1.xはサポートされていません。 npm:指定子を使用してください。 deno.land/x/sentryレジストリは非推奨です。

`deno.json`を使ってインストール（推奨）

{
  "imports": {
    "@sentry/deno": "npm:@sentry/[email protected]"
  }
}

または、npm:指定子を使って直接インポートします。

import * as Sentry from "npm:@sentry/deno";

初期化 — エントリーファイルに追加します

// main.ts — Sentry.init() must be called before any other code
import * as Sentry from "@sentry/deno";

Sentry.init({
  dsn: Deno.env.get("SENTRY_DSN") ?? "___DSN___",

  dataCollection: {
    // To disable sending user data and HTTP bodies, uncomment the lines below. For more info visit:
    // https://docs.sentry.io/platforms/javascript/guides/node/configuration/options/#dataCollection
    // userInfo: false,
    // httpBodies: [],
  },
  tracesSampleRate: Deno.env.get("DENO_ENV") === "development" ? 1.0 : 0.1,
  enableLogs: true,
});

// Your application code follows
Deno.serve({ port: 8000 }, (req) => {
  return new Response("Hello from Deno!");
});

Node.jsやBunと異なり、Denoには--preloadまたは--importフラグがありません。エントリーファイルではSentryを最初にimportする必要があります。

Denoに必要な権限

SDKがSentryの取り込みドメインにアクセスするには、ネットワークアクセスが必要です。

deno run \
  --allow-net=o<ORG_ID>.ingest.sentry.io \
  --allow-read=./src \
  --allow-env=SENTRY_DSN,SENTRY_RELEASE \
  main.ts

開発では--allow-allを使用できますが、本番環境での使用は推奨されません。

DenoのCronインテグレーション

DenoにはネイティブのCronスケジューリング機能があります。自動監視にはdenoCronIntegrationを使用します。

import * as Sentry from "@sentry/deno";
import { denoCronIntegration } from "@sentry/deno";

Sentry.init({
  dsn: Deno.env.get("SENTRY_DSN") ?? "___DSN___",
  integrations: [denoCronIntegration()],
});

// Cron is automatically monitored
Deno.cron("daily-cleanup", "0 0 * * *", () => {
  // cleanup logic
});

Deno の機能サポート

機能	Deno のサポート	備考
エラー監視	✅ 完全対応	未処理の例外 + `captureException`
トレーシング	✅ カスタム OTel	`Deno.serve()` と `fetch` のスパンを自動生成
ロギング	✅ 完全対応	`enableLogs: true` + `Sentry.logger.*`
プロファイリング	❌ 利用不可	Deno 用のプロファイリングアドオンはありません
メトリクス	✅ 完全対応	`Sentry.metrics.*`
ランタイムメトリクス	❌ 利用不可	Deno 用のランタイムメトリクス連携はありません
Cron	✅ 完全対応	`denoCronIntegration()` + `Sentry.withMonitor()`
AI モニタリング	✅ 部分対応	Vercel AI SDK との連携が動作します。OpenAI／Anthropic は `npm:` 経由で利用できます

OTLP 連携（OTel ファーストのプロジェクト — Node.js のみ）

この方法は、フェーズ 1 で OpenTelemetry トレーシングが検出された場合にのみ使用してください（例：package.json に @opentelemetry/sdk-node または @opentelemetry/sdk-trace-node がある場合）。既存の OTel セットアップがないプロジェクトでは、上記の標準的な @sentry/node の方法を使用してください。

OTLP 連携では、独自の OpenTelemetry をバンドルしない軽量な Sentry SDK、@sentry/node-core/light を使用します。代わりに、ユーザーの既存の OTel TracerProvider にフックし、OTLP 経由でスパンを Sentry にエクスポートします。

使用する場合

シナリオ	推奨される方法
新規プロジェクトで、既存の OTel がない	標準の `@sentry/node`（上記）— OTel が組み込まれています
既存の OTel セットアップがあり、Sentry トレーシングを使用したい	`@sentry/node-core/light` + `otlpIntegration()`
既存の OTel セットアップがあり、自分の Collector に送信したい	`@sentry/node-core/light` + `otlpIntegration({ collectorUrl })`

インストール

npm install @sentry/node-core @opentelemetry/api @opentelemetry/sdk-trace-node @opentelemetry/sdk-trace-base
# or
yarn add @sentry/node-core @opentelemetry/api @opentelemetry/sdk-trace-node @opentelemetry/sdk-trace-base
# or
pnpm add @sentry/node-core @opentelemetry/api @opentelemetry/sdk-trace-node @opentelemetry/sdk-trace-base

@opentelemetry/* パッケージはピア依存関係です。プロジェクトにすでにインストールされている場合は、重複してインストールしないでください。

初期化

// instrument.mjs — load via --import flag before any other module
import { NodeTracerProvider } from '@opentelemetry/sdk-trace-node';
import * as Sentry from '@sentry/node-core/light';
import { otlpIntegration } from '@sentry/node-core/light/otlp';

// Register the user's OTel TracerProvider first
const provider = new NodeTracerProvider();
provider.register();

Sentry.init({
  dsn: process.env.SENTRY_DSN ?? '___DSN___',

  dataCollection: {
    // To disable sending user data and HTTP bodies, uncomment the lines below. For more info visit:
    // https://docs.sentry.io/platforms/javascript/guides/node/configuration/options/#dataCollection
    // userInfo: false,
    // httpBodies: [],
  },
  enableLogs: true,

  // Do NOT set tracesSampleRate — OTel controls sampling
  integrations: [
    otlpIntegration({
      // Export OTel spans to Sentry via OTLP (default: true)
      setupOtlpTracesExporter: true,
    }),
  ],
});

カスタム Collector エンドポイントを使用する場合：

Sentry.init({
  dsn: process.env.SENTRY_DSN ?? '___DSN___',
  integrations: [
    otlpIntegration({
      collectorUrl: 'http://localhost:4318/v1/traces',
    }),
  ],
});

アプリの起動

標準的な Node.js セットアップと同じ --import パターンを使用します。

node --import ./instrument.mjs app.mjs

標準の `@sentry/node` との主な違い

項目	`@sentry/node`（標準）	`@sentry/node-core/light`（OTLP）
OTel のバンドル	✅ はい — TracerProvider が組み込まれています	❌ いいえ — 既存のプロバイダーを使用します
トレーシングの制御	`Sentry.init()` の `tracesSampleRate`	OTel SDK がサンプリングを制御します
自動インストルメンテーション	✅ 組み込み（HTTP、DB など）	❌ OTel インストルメンテーションは自分で管理します
プロファイリング	✅ 利用可能	❌ 非対応
エラーとトレースの関連付け	✅ 自動	✅ 自動（`otlpIntegration` 経由）
パッケージサイズ	大きい（OTel を含む）	小さい（軽量モード）

合意した各機能について

該当するリファレンスファイルを読み込み、手順に従ってください。

機能	リファレンスファイル	読み込むタイミング
エラー監視	`references/error-monitoring.md`	常に（基本項目）— イベントの捕捉、スコープ、情報の付加、beforeSend
OTLP 連携	上記の OTLP 連携を参照	OTel トレーシングが検出された場合 — ネイティブのトレーシングを置き換えます
トレーシング	`references/tracing.md`	OTel 自動インストルメンテーション、カスタムスパン、分散トレーシング、サンプリング。OTel トレーシングが検出された場合はスキップ
ロギング	`references/logging.md`	構造化ログ、`Sentry.logger.*`、ログとトレースの相関
プロファイリング	`references/profiling.md`	Node.js のみ — CPU プロファイリング、Bun／Deno の制限事項を記載。OTel トレーシングが検出された場合はスキップ
メトリクス	`references/metrics.md`	カスタムカウンター、ゲージ、分布
ランタイムメトリクス	下記のインライン記述を参照	Node.js と Bun のメモリ、CPU、イベントループのメトリクスを自動収集
Cron	`references/crons.md`	スケジュールされたジョブの監視、node-cron、Bull、Agenda、Deno.cron
AI モニタリング	`sentry-setup-ai-monitoring` スキルを読み込む	OpenAI、Anthropic、LangChain、Vercel AI、Google GenAI

各機能について、リファレンスファイルを読み、手順に正確に従い、次に進む前に検証してください。

ランタイムメトリクス

Node.js および Bun のランタイムの健全性メトリクス（メモリ、CPU 使用率、イベントループの遅延／使用率、稼働時間）を、設定可能な間隔で自動収集します。メトリクスは、Sentry の Metrics 製品の node.runtime.*／bun.runtime.* 名前空間に表示されます。

Node.js — instrument.js に nodeRuntimeMetricsIntegration() を追加します。

const Sentry = require("@sentry/node");

Sentry.init({
  dsn: process.env.SENTRY_DSN,
  integrations: [
    Sentry.nodeRuntimeMetricsIntegration(),
    // Optional: change collection interval (default 30 000 ms)
    // Sentry.nodeRuntimeMetricsIntegration({ collectionIntervalMs: 60_000 }),
  ],
});

デフォルトで収集されるメトリクス：node.runtime.mem.rss、node.runtime.mem.heap_used、node.runtime.mem.heap_total、node.runtime.cpu.utilization、node.runtime.event_loop.delay.p50、node.runtime.event_loop.delay.p99、node.runtime.event_loop.utilization、node.runtime.process.uptime。

Bun — instrument.ts に bunRuntimeMetricsIntegration() を追加します。

import * as Sentry from "@sentry/bun";
import { bunRuntimeMetricsIntegration } from "@sentry/bun";

Sentry.init({
  dsn: process.env.SENTRY_DSN,
  integrations: [
    bunRuntimeMetricsIntegration(),
    // Optional: change collection interval (default 30 000 ms)
    // bunRuntimeMetricsIntegration({ collectionIntervalMs: 60_000 }),
  ],
});

収集されるメトリクス：Bun ではイベントループの遅延パーセンタイルを利用できない点を除き、Node.js と同じです。プレフィックスは bun.runtime.* です。

設定リファレンス

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

オプション	型	デフォルト	備考
`dsn`	`string`	—	必須です。`SENTRY_DSN` 環境変数からも設定できます
`tracesSampleRate`	`number`	—	0～1。トレーシングを有効にするには必須です。OTLP パスを使用する場合は設定しないでください
`dataCollection`	`object`	設定されていない場合は保守的	自動収集するカテゴリ（`userInfo`、`cookies`、`httpHeaders`、`httpBodies`、`queryParams`、`genAI`）を細かく制御します。省略すると、SDK は `sendDefaultPii`（デフォルトは `false`）にフォールバックします。このオブジェクトを渡すと（`{}` の場合も含む）、未設定のカテゴリが許可側のデフォルトに切り替わります。カテゴリごとにオプトアウトしてください。
`includeLocalVariables`	`boolean`	`false`	スタックフレームにローカル変数の値を追加します（Node.js）
`enableLogs`	`boolean`	`false`	Sentry Logs 製品を有効にします（v9.41.0 以降）
`environment`	`string`	`"production"`	`SENTRY_ENVIRONMENT` 環境変数からも設定できます
`release`	`string`	—	`SENTRY_RELEASE` 環境変数からも設定できます
`debug`	`boolean`	`false`	SDK の動作をコンソールに記録します
`enabled`	`boolean`	`true`	送信を無効にするには、テストで `false` に設定します
`sampleRate`	`number`	`1.0`	送信するエラーイベントの割合（0～1）
`shutdownTimeout`	`number`	`2000`	プロセス終了前にイベントをフラッシュするまでのミリ秒数

`nativeNodeFetchIntegration()` のオプション

送信側の fetch／undici スパンのキャプチャを設定します。@opentelemetry/[email protected] 以降、content-length などのレスポンスヘッダーは自動でキャプチャされなくなりました。オプトインするには headersToSpanAttributes を使用してください。

Sentry.init({
  integrations: [
    Sentry.nativeNodeFetchIntegration({
      headersToSpanAttributes: {
        requestHeaders: ["x-request-id"],
        responseHeaders: ["content-length", "content-type"],
      },
    }),
  ],
});

オプション	型	デフォルト	備考
`breadcrumbs`	`boolean`	`true`	送信側の fetch リクエストのパンくずを記録します
`headersToSpanAttributes.requestHeaders`	`string[]`	—	スパン属性としてキャプチャするリクエストヘッダー名
`headersToSpanAttributes.responseHeaders`	`string[]`	—	スパン属性としてキャプチャするレスポンスヘッダー名

`otlpIntegration()` のオプション（`@sentry/node-core/light/otlp`）

@sentry/node-core/light を使用する OTel 優先のプロジェクト向けです。インポート：import { otlpIntegration } from '@sentry/node-core/light/otlp'。

オプション	型	デフォルト	用途
`setupOtlpTracesExporter`	`boolean`	`true`	スパンを Sentry に送信する OTLP エクスポーターを自動設定します。すでに独自の Collector にエクスポートしている場合は `false` に設定します
`collectorUrl`	`string`	`undefined`	OTel Collector の OTLP HTTP エンドポイント（例：`http://localhost:4318/v1/traces`）。設定すると、スパンは DSN から導出された Sentry エンドポイントではなく、Collector に送信されます

グレースフルシャットダウン

プロセス終了前にバッファー内のイベントをフラッシュします。短時間で終了するスクリプトやサーバーレス環境では重要です。

process.on("SIGTERM", async () => {
  await Sentry.close(2000); // flush with 2s timeout
  process.exit(0);
});

環境変数

変数	用途	実行時
`SENTRY_DSN`	DSN（`init()` にハードコードする代わりに使用）	すべて
`SENTRY_ENVIRONMENT`	デプロイ環境	すべて
`SENTRY_RELEASE`	リリースバージョン文字列（git から自動検出）	すべて
`SENTRY_AUTH_TOKEN`	ソースマップのアップロード用トークン	ビルド時
`SENTRY_ORG`	ソースマップのアップロード用組織スラッグ	ビルド時
`SENTRY_PROJECT`	ソースマップのアップロード用プロジェクトスラッグ	ビルド時
`NODE_OPTIONS`	ESM 用に `--import ./instrument.mjs` を設定	Node.js

ソースマップ（Node.js）

本番環境で読みやすいスタックトレースを得るには、@sentry/cli または webpack/esbuild/rollup プラグインを使ってソースマップをアップロードする必要があります。たとえば、ビルド時に inject + upload の手順を追加します。

{
  "scripts": {
    "build": "tsc && sentry-cli sourcemaps inject ./dist && sentry-cli sourcemaps upload ./dist"
  }
}

アップロードには SENTRY_AUTH_TOKEN（ビルド時のシークレット）が必要です。トークンの作成方法と CI への設定方法については、sentry-source-maps を参照してください。

検証

セットアップ後、Sentry がイベントを受信していることを確認します。

// Add temporarily to your entry file or a test route, then remove
import * as Sentry from "@sentry/node"; // or @sentry/bun / @sentry/deno

Sentry.captureException(new Error("Sentry test error — delete me"));

または、未処理の例外を発生させます。

// In a route handler or startup — will be captured automatically
throw new Error("Sentry test error — delete me");

次に、Sentry Issues ダッシュボードを確認します。エラーは約 30 秒以内に表示されるはずです。

検証チェックリスト：

確認項目	方法
エラーの捕捉	ハンドラー内で例外をスローし、Sentry Issues で確認します
トレーシングの動作	Performance タブを確認します。HTTP スパンが表示されるはずです
`includeLocalVariables` の動作	Sentry のスタックフレームに変数の値が表示されることを確認します
ソースマップの動作	スタックトレースに、圧縮されたファイル名ではなく読みやすいファイル名が表示されることを確認します

フェーズ 4：関連スキルの案内

バックエンドのセットアップ完了後、関連するサービスがないか確認します。

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

# Other backend services
ls ../go.mod ../requirements.txt ../Gemfile 2>/dev/null

フロントエンド、フレームワーク固有の SDK、または別のバックエンドが見つかった場合は、対応するスキルを案内します。

JavaScript フレームワーク専用スキル（汎用の node-sdk より優先）：

検出対象	優先するスキル	理由
NestJS（`package.json` に `@nestjs/core`）	`sentry-nestjs-sdk`	NestJS ネイティブのデコレーター、フィルター、GraphQL サポートを備えた `@sentry/nestjs` を使用します
Next.js（`package.json` に `next`）	`sentry-nextjs-sdk`	3 ランタイム構成（ブラウザー、サーバー、エッジ）、`withSentryConfig`、ソースマップのアップロードに対応します

フロントエンドの関連スキル：

検出対象	提案するスキル
React アプリ（`package.json` に `react`）	`sentry-react-sdk`
Svelte/SvelteKit	`sentry-svelte-sdk`

その他のバックエンドの関連スキル：

検出対象	提案するスキル
Go バックエンド（`go.mod`）	`sentry-go-sdk`
Python バックエンド（`requirements.txt`、`pyproject.toml`）	`sentry-python-sdk`
Ruby バックエンド（`Gemfile`）	`sentry-ruby-sdk`

フロントエンドとバックエンドで同じ DSN を使用するか、プロジェクトをリンクすると、分散トレーシングが有効になります。これにより、ブラウザー、API サーバー、データベースにまたがるスタックトレースを、1 つのトレースビューで確認できます。

トラブルシューティング

問題	原因	解決策
イベントが表示されない	`instrument.js` の読み込みが遅すぎます	最初の `require()` にするか、`--import` または `--preload` で読み込まれるようにしてください
トレーススパンが見つからない	`tracesSampleRate` が設定されていません	`Sentry.init()` に `tracesSampleRate: 1.0` を追加してください
ESM の計装が機能しない	`--import` フラグがありません	`node --import ./instrument.mjs` で実行してください。アプリ内で `import "./instrument.mjs"` を指定するだけでは不十分です
Bun で `@sentry/profiling-node` のインストールに失敗する	ネイティブアドオンに互換性がありません	Bun ではプロファイリングはサポートされていないため、`@sentry/profiling-node` を削除してください
Deno：イベントが送信されない	`--allow-net` 権限がありません	`--allow-net=o<ORG_ID>.ingest.sentry.io` を指定して実行してください
Deno：`deno.land/x/sentry` が機能しない	非推奨で、v8.55.0 のまま更新されていません	`npm:@sentry/deno` 指定子に切り替えてください
`includeLocalVariables` に値が表示されない	インテグレーションが有効化されていないか、コードがミニファイされています	初期化時に `includeLocalVariables: true` が指定されていることを確認し、ソースマップを確認してください
NestJS：エラーが捕捉されない	SDK が間違っているか、フィルターがありません	`sentry-nestjs-sdk` を使用してください。NestJS では `@sentry/node` ではなく `@sentry/nestjs` が必要です
Hapi：`setupHapiErrorHandler` のタイミングに関する問題	await されていません	`server.start()` の前に `await Sentry.setupHapiErrorHandler(server)` を実行する必要があります
シャットダウン時にイベントが失われる	フラッシュ前にプロセスが終了します	SIGTERM/SIGINT ハンドラーに `await Sentry.close(2000)` を追加してください
スタックトレースにミニファイされたコードが表示される	ソースマップがアップロードされていません	ビルド手順で `@sentry/cli` によるソースマップのアップロードを設定してください
トレースが表示されない（OTLP）	`@opentelemetry/*` パッケージがないか、`otlpIntegration` が追加されていません	`@opentelemetry/sdk-trace-node` がインストールされていることを確認してください。`integrations` に `otlpIntegration()` を追加し、`tracesSampleRate` は設定しないでください
OTLP：エラーがトレースに関連付けられない	`otlpIntegration` が登録されていません	`integrations` 配列に `otlpIntegration()` が含まれていることを確認してください。これにより、エラーを OTel トレースに関連付ける伝播コンテキストが登録されます
プロファイリングが開始されない（OTLP）	プロファイリングには `tracesSampleRate` が必要です	プロファイリングは OTLP 経路と互換性がありません。標準の `@sentry/node` セットアップを使用してください

Markdown 対応

ログインしてコメント

基本情報

作者: getsentry
リポジトリ: getsentry/sentry-for-ai
カテゴリ: 開発
インストール数: 3,353
GitHub スター: 272

問題を報告

sentry-node-sdk

sentry-node-sdk について

主な機能

活用シーン

インストール

同梱ファイル

詳細

Sentry Node.js / Bun / Deno SDK

このスキルを使用する場面

フェーズ 1：検出

フェーズ 2：推奨事項

フェーズ 3：手順

ランタイム：Node.js

オプション 1：ウィザード（Node.js におすすめ）

オプション 2：手動セットアップ — Node.js

インストール

Instrument ファイルの作成

Sentry を最初に読み込んでアプリを起動する

フレームワークのエラーハンドラー

ランタイム：Bun

インストール

instrument.ts（またはinstrument.js）を作成します

--preloadを指定してアプリを起動します

Bun.serve() — 自動計装

Bunでのフレームワークエラーハンドラー

Bunの機能サポート

ランタイム：Deno

deno.jsonを使ってインストール（推奨）

初期化 — エントリーファイルに追加します

Denoに必要な権限

DenoのCronインテグレーション

Deno の機能サポート

OTLP 連携（OTel ファーストのプロジェクト — Node.js のみ）

使用する場合

インストール

初期化

アプリの起動

標準の @sentry/node との主な違い

合意した各機能について

ランタイムメトリクス

設定リファレンス

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

nativeNodeFetchIntegration() のオプション

otlpIntegration() のオプション（@sentry/node-core/light/otlp）

グレースフルシャットダウン

環境変数

ソースマップ（Node.js）

検証

フェーズ 4：関連スキルの案内

トラブルシューティング

コメント

`instrument.ts`（または`instrument.js`）を作成します

`--preload`を指定してアプリを起動します

`deno.json`を使ってインストール（推奨）

標準の `@sentry/node` との主な違い

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

`nativeNodeFetchIntegration()` のオプション

`otlpIntegration()` のオプション（`@sentry/node-core/light/otlp`）