すべてのスキル > SDK設定 > Node.js / Bun / Deno SDK

Sentry Node.js / Bun / Deno SDK

プロジェクトをスキャンし、Node.js、Bun、DenoなどのサーバーサイドJavaScriptおよびTypeScriptランタイムに対するSentryの完全な設定をガイドする独自のウィザード。

このスキルを実行する場合

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

NestJS? 代わりにsentry-nestjs-sdkを使用してください — これは@sentry/nestjsを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設定を特定します：

# ランタイムを検出
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"

# 既存のSentryパッケージを検出
cat package.json 2>/dev/null | grep -E '"@sentry/'
cat deno.json deno.jsonc 2>/dev/null | grep -i sentry

# Node.jsフレームワークを検出
cat package.json 2>/dev/null | grep -E '"express"|"fastify"|"@hapi/hapi"|"koa"|"@nestjs/core"|"connect"'

# Bun固有のフレームワークを検出
cat package.json 2>/dev/null | grep -E '"elysia"|"hono"'

# Denoフレームワークを検出（deno.jsonインポート）
cat deno.json deno.jsonc 2>/dev/null | grep -E '"oak"|"hono"|"fresh"'

# モジュールシステムを検出（Node.js）
cat package.json 2>/dev/null | grep '"type"'
ls *.mjs *.cjs 2>/dev/null | head -5

# 既存のインストルメントファイルを検出
ls instrument.js instrument.mjs instrument.ts instrument.cjs 2>/dev/null

# ログライブラリを検出
cat package.json 2>/dev/null | grep -E '"winston"|"pino"|"bunyan"'

# クロン / スケジューリングを検出
cat package.json 2>/dev/null | grep -E '"node-cron"|"cron"|"agenda"|"bull"|"bullmq"'

# AI / LLM使用を検出
cat package.json 2>/dev/null | grep -E '"openai"|"@anthropic-ai"|"@langchain"|"@vercel/ai"|"@google/generative-ai"'

# OpenTelemetry トレーシングを検出
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

# コンパニオンフロントエンドを確認
ls frontend/ web/ client/ ui/ 2>/dev/null
cat package.json 2>/dev/null | grep -E '"react"|"vue"|"svelte"|"next"'

決定すべき事項：

質問	影響
どのランタイム？（Node.js / Bun / Deno）	パッケージ、initパターン、プリロードフラグを決定します
Node.js: ESMまたはCJS？	ESMは--import ./instrument.mjsが必要です。CJSはrequire("./instrument")を使用します
フレームワークを検出？	どのエラーハンドラーを登録するかを決定します
@sentry/*がすでにインストール済み？	インストールをスキップして、機能設定に進みます
instrument.js / instrument.mjsが既に存在？	それを上書きするのではなく、マージします
ログライブラリを検出？	Sentry ログを推奨します
クロン / ジョブスケジューラーを検出？	クロンモニタリングを推奨します
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トレースにリンクします

推奨（コアカバレッジ）：

• ✅ エラーモニタリング — 常に実施します。ハンドルされない例外、約束の拒否、フレームワークエラーをキャプチャします
• ✅ トレーシング — OpenTelemetryを介した自動HTTP、DB、キューインストルメンテーション

オプション（強化された観測可能性）：

• ⚡ ログ記録 — Sentry.logger.*経由の構造化ログ。winston/pino/bunyanまたはログ検索が必要な場合に推奨します
• ⚡ プロファイリング — 継続的なCPUプロファイリング（Node.jsのみ。BunやDenoでは利用不可）。OTLPパスでは利用不可
• ⚡ AIモニタリング — OpenAI、Anthropic、LangChain、Vercel AI SDK。AI/LLM呼び出しが検出された場合に推奨します
• ⚡ クロン — スケジュールされたジョブの欠落や失敗を検出します。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を呼び出す場合
クロン	アプリがnode-cron、Bull、BullMQ、Agenda、またはその他のスケジュールされたタスクパターンを使用している場合
メトリクス	アプリがカスタムカウンター、ゲージ、またはヒストグラムを必要とする場合
ランタイムメトリクス	Node.jsまたはBunサービスが自動メモリ/CPU/イベントループの可視性を望む場合

OTelトレーシングを検出： 「プロジェクトでOpenTelemetryトレーシングが使用されていることが確認されました。既存のOTel設定経由のトレーシング用Sentry OTLP統合 + エラーモニタリング + Sentry ログ [+ 該当する場合はメトリクス/クロン/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

インストルメントファイルを作成

CommonJS (instrument.js):

// instrument.js — 他のすべてのモジュールの前にロードする必要があります
const Sentry = require("@sentry/node");

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

  sendDefaultPii: true,

  // 開発では100%、本番環境ではそれ以下
  tracesSampleRate: process.env.NODE_ENV === "development" ? 1.0 : 0.1,

  // スタックフレームのローカル変数値をキャプチャ
  includeLocalVariables: true,

  enableLogs: true,
});

ESM (instrument.mjs):

// instrument.mjs — フラグ経由で他のモジュールの前にロードされます
import * as Sentry from "@sentry/node";

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

  sendDefaultPii: true,
  tracesSampleRate: process.env.NODE_ENV === "development" ? 1.0 : 0.1,
  includeLocalVariables: true,
  enableLogs: true,
});

Sentryをロードして最初にアプリを起動

CommonJS — エントリファイルの最初の行としてrequire("./instrument")を追加します：

// app.js
require("./instrument"); // 最初である必要があります

const express = require("express");
// ... アプリの残りの部分

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();

// ... ルート

// すべてのルートの後に追加 — デフォルトで5xxエラーをキャプチャ
Sentry.setupExpressErrorHandler(app);

// オプション: 4xxエラーもキャプチャ
// 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();

// ルートの前に追加（Expressと異なります！）
Sentry.setupFastifyErrorHandler(fastify);

// ... ルート

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

Koa:

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

const app = new Koa();

// 最初のミドルウェアとして追加（後で投げられたエラーをキャッチします）
Sentry.setupKoaErrorHandler(app);

// ... その他のミドルウェアとルート

app.listen(3000);

Hapi（非同期 — awaitが必須）:

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

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

// ... ルート

// awaitが必須 — Hapi登録は非同期です
await Sentry.setupHapiErrorHandler(server);

await server.start();

Connect:

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

const app = connect();

// ルートの前に追加（FastifyとKoaのように）
Sentry.setupConnectErrorHandler(app);

// ... ミドルウェアとルート

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

NestJS — 独自の専用スキルを備えています：

代わりにsentry-nestjs-sdkスキルを使用してください。 NestJSはNestJSネイティブ構成を備えた別個のパッケージ（@sentry/nestjs）を使用します： SentryModule.forRoot()、SentryGlobalFilter、@SentryTraced、@SentryCronデコレータ、 およびGraphQL/マイクロサービスサポート。その完全なNestJS設定のスキルをロードしてください。

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

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

const server = http.createServer((req, res) => {
  Sentry.withIsolationScope(() => {
    try {
      // ハンドラー
      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___",

  sendDefaultPii: true,
  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 プロキシ経由で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/nodeエラーハンドラー関数（@sentry/bunにより再エクスポート）を使用します：

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

const app = express();
// ... ルート
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、イベントループ（イベントループ遅延パーセンタイルなし）
クロン	✅ 完全	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/deno@10.42.0"
  }
}

またはnpm:指定子で直接インポートします：

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

初期化 — エントリファイルに追加

// main.ts — Sentry.init()は他のコードの前に呼び出す必要があります
import * as Sentry from "@sentry/deno";

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

  sendDefaultPii: true,
  tracesSampleRate: Deno.env.get("DENO_ENV") === "development" ? 1.0 : 0.1,
  enableLogs: true,
});

// アプリケーションコードは以下に続きます
Deno.serve({ port: 8000 }, (req) => {
  return new Response("Hello from Deno!");
});

Node.jsおよびBunとは異なり、Denoは--preloadまたは--importフラグを備えていません。Sentryはエントリファイルの最初のimportである必要があります。

必須のDenoパーミッション

SDKはSentry ingestドメインに到達するためのネットワークアクセスが必要です：

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は自動的にモニタリングされます
Deno.cron("daily-cleanup", "0 0 * * *", () => {
  // クリーンアップロジック
});

Denoの機能サポート

機能	Denoサポート	注釈
エラーモニタリング	✅ 完全	ハンドルされない例外 + captureException
トレーシング	✅ カスタムOTel	Deno.serve()とfetchの自動スパン
ログ記録	✅ 完全	enableLogs: true + Sentry.logger.*
プロファイリング	❌ 利用不可	Deno用プロファイリングアドオンなし
メトリクス	✅ 完全	Sentry.metrics.*
ランタイムメトリクス	❌ 利用不可	Deno用ランタイムメトリクス統合なし
クロン	✅ 完全	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統合は@sentry/node-core/lightを使用します — 独自のOpenTelemetryをバンドルしない軽量Sentry SDK。代わりに、ユーザーの既存OTel TracerProviderにフックし、スパンをOTLP経由でSentryにエクスポートします。

使用する場合

シナリオ	推奨パス
新しいプロジェクト、既存のOTelなし	標準@sentry/node（上記）— ビルトインOTelを含みます
既存のOTelセットアップ、Sentryトレーシングが必要	@sentry/node-core/light + otlpIntegration()
既存のOTelセットアップ、独自のコレクターに送信	@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 — 他のモジュールの前にフラグ経由でロード
import { NodeTracerProvider } from '@opentelemetry/sdk-trace-node';
import * as Sentry from '@sentry/node-core/light';
import { otlpIntegration } from '@sentry/node-core/light/otlp';

// まずユーザーのOTel TracerProviderを登録
const provider = new NodeTracerProvider();
provider.register();

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

  sendDefaultPii: true,
  enableLogs: true,

  // tracesSampleRateを設定しないでください — OTelがサンプリングをコントロール
  integrations: [
    otlpIntegration({
      // OTelスパンをOTLP経由でSentryにエクスポート（デフォルト：true）
      setupOtlpTracesExporter: true,
    }),
  ],
});

カスタムコレクターエンドポイント付き：

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およびBuのメモリ、CPU、イベントループメトリクス自動収集
クロン	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のメトリクス製品にnode.runtime.* / bun.runtime.*ネームスペース下で表示されます。

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

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

Sentry.init({
  dsn: process.env.SENTRY_DSN,
  integrations: [
    Sentry.nodeRuntimeMetricsIntegration(),
    // オプション: 収集間隔を変更（デフォルト 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(),
    // オプション: 収集間隔を変更（デフォルト 30 000 ms）
    // bunRuntimeMetricsIntegration({ collectionIntervalMs: 60_000 }),
  ],
});

収集されるメトリクス：Node.jsと同じです。ただし、イベントループ遅延パーセンタイルはありません（Bunで利用不可）。bun.runtime.*にプレフィックス付きます。

---

確認

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

// テンポラリーにエントリファイルまたはテストルートに追加してから削除
import * as Sentry from "@sentry/node"; // or @sentry/bun / @sentry/deno

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

またはハンドルされない例外をトリガー：

// ルートハンドラーまたはスタートアップで — 自動的にキャプチャされます
throw new Error("Sentry test error — delete me");

次にSentry Issues ダッシュボードを確認してください — エラーは約30秒以内に表示される必要があります。

確認チェックリスト：

チェック	方法
エラーがキャプチャされた	ハンドラーで投げて、Sentry Issuesで確認
トレーシングが機能	パフォーマンスタブをチェック — HTTPスパンが表示される必要があります
includeLocalVariablesが機能	Sentryのスタックフレームに変数値が表示される必要があります
ソースマップが機能	スタックトレースに読める可能なファイル名が表示され、最小化されていない

---

設定リファレンス

Sentry.init()コアオプション

オプション	型	デフォルト	注釈
dsn	string	—	必須。またSENTRY_DSN環境変数から
tracesSampleRate	number	—	0–1。トレーシングを有効にするのに必須。OTLPパス使用時に設定しないでください
sendDefaultPii	boolean	false	IP、リクエストヘッダー、ユーザー情報を含める
includeLocalVariables	boolean	false	スタックフレームにローカル変数値を追加（Node.js）
enableLogs	boolean	false	Sentry ログ製品を有効化（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/instrumentation-undici@0.22.0以降、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	OTLP エクスポーターを自動設定しSentryにスパンを送信。既にコレクターにエクスポート中の場合はfalseに設定
collectorUrl	string	undefined	OTel コレクターのOTLP HTTPエンドポイント（例：http://localhost:4318/v1/traces）。設定されると、スパンはDSN派生Sentryエンドポイントの代わりにコレクターに送信されます

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

プロセス終了前にバッファリングされたイベントをフラッシュします — 短命スクリプトとサーバーレスで重要：

process.on("SIGTERM", async () => {
  await Sentry.close(2000); // 2sタイムアウトでフラッシュ
  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プラグインを使用します：

npm install @sentry/cli --save-dev

# sentry.io/settings/auth-tokens/でSentry認証トークンを作成
# .env.sentry-build-pluginで設定（このファイルはgitignoreしてください）：
SENTRY_AUTH_TOKEN=sntrys_eyJ...

ビルドステップにアップロードステップを追加：

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

---

フェーズ4: クロスリンク

バックエンドセットアップ完了後、コンパニオンサービスをチェック：

# フロントエンドコンパニオン
ls frontend/ web/ client/ ui/ 2>/dev/null
cat package.json 2>/dev/null | grep -E '"react"|"vue"|"svelte"|"next"'

# その他のバックエンドサービス
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またはプリロード経由でロードされることを確認
トレーシングスパンが欠落	tracesSampleRateが設定されていない	Sentry.init()にtracesSampleRate: 1.0を追加
ESM インストルメンテーションが機能しない	--importフラグの欠落	node --import ./instrument.mjsで実行。アプリ内のimport "./instrument.mjs"は不十分
@sentry/profiling-nodeがBunでインストール失敗	ネイティブアドオン互換性なし	プロファイリングは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に値が表示されない	統合が未アクティブまたはコード最小化	init内のincludeLocalVariables: trueを確認。ソースマップをチェック
NestJS: エラー未キャプチャ	間違ったSDKまたはフィルター欠落	sentry-nestjs-sdkを使用 — NestJSは@sentry/nestjsが必要。@sentry/nodeではなく
Hapi: setupHapiErrorHandlerタイミング問題	awaitされていない	server.start()の前にawait Sentry.setupHapiErrorHandler(server)が必須
シャットダウン: イベント喪失	フラッシュの前にプロセス終了	SIGTERM/SIGINTハンドラーにawait Sentry.close(2000)を追加
スタックトレースが最小化コード表示	ソースマップアップロード未実施	ビルドステップで@sentry/cliソースマップアップロードを設定
トレース表示なし（OTLP）	@opentelemetry/*パッケージ欠落またはotlpIntegration未追加	@opentelemetry/sdk-trace-nodeインストール確認。otlpIntegration()を統合配列に追加。tracesSampleRateを設定しないでください
OTLP: エラーがトレースにリンクされない	otlpIntegrationが登録されていない	otlpIntegration()が統合配列内にあることを確認 — エラーをOTelトレースにリンクする伝搬コンテキストを登録します
プロファイリング未開始（OTLP）	プロファイリングtracesSampleRateが必要	プロファイリングはOTLPパスと互換性なし。代わりに標準@sentry/nodeセットアップを使用