sentry-cloudflare-sdk

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

Sentry Cloudflare SDK

Cloudflare プロジェクトをスキャンし、Workers、Pages、Durable Objects、Queues、Workflows、Hono 向けの Sentry の完全なセットアップを案内する、意見を反映したウィザードです。

このスキルを呼び出す場面

• ユーザーが「Cloudflare Workers に Sentry を追加して」または Cloudflare プロジェクトで「Sentry をセットアップして」と依頼した場合
• ユーザーが @sentry/cloudflare のインストールまたは設定を希望している場合
• ユーザーが Cloudflare Workers または Pages のエラー監視、トレース、ログ、cron、AI 監視を希望している場合
• ユーザーが withSentry、sentryPagesPlugin、instrumentDurableObjectWithSentry、instrumentD1WithSentry について質問した場合
• ユーザーが Cloudflare 上の Durable Objects、Queues、Workflows、Scheduled ハンドラー、または Email ハンドラーの監視を希望している場合

注： 以下の SDK バージョンと API は、執筆時点の Sentry ドキュメント（@sentry/cloudflare v10.61.0）に基づいています。 実装前に、必ずこちらのドキュメントで確認してください。

---

フェーズ 1：検出

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

# Detect Cloudflare project
ls wrangler.toml wrangler.jsonc wrangler.json 2>/dev/null

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

# Detect project type (Workers vs Pages)
ls functions/ functions/_middleware.js functions/_middleware.ts 2>/dev/null && echo "Pages detected"
cat wrangler.toml 2>/dev/null | grep -E 'main|pages_build_output_dir'

# Detect framework
cat package.json 2>/dev/null | grep -E '"hono"|"remix"|"astro"|"svelte"'

# Detect Durable Objects
cat wrangler.toml 2>/dev/null | grep -i 'durable_objects'

# Detect D1 databases
cat wrangler.toml 2>/dev/null | grep -i 'd1_databases'

# Detect Queues
cat wrangler.toml 2>/dev/null | grep -i 'queues'

# Detect Workflows
cat wrangler.toml 2>/dev/null | grep -i 'workflows'

# Detect Scheduled handlers (cron triggers)
cat wrangler.toml 2>/dev/null | grep -i 'crons\|triggers'

# Detect compatibility flags
cat wrangler.toml 2>/dev/null | grep -i 'compatibility_flags'
cat wrangler.jsonc 2>/dev/null | grep -i 'compatibility_flags'

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

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

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

確認する項目：

質問	影響
Workers と Pages のどちらですか？	使用するラッパー（withSentry と sentryPagesPlugin）が決まります
Hono フレームワークを使用していますか？	よりすっきりと統合できる、単独の @sentry/hono パッケージ（v10.55.0 以降）を推奨します
@sentry/cloudflare はすでにインストールされていますか？	インストールを省略し、機能の設定に進みます
Durable Objects は設定されていますか？	instrumentDurableObjectWithSentry を推奨します
D1 データベースはバインドされていますか？	withSentry は D1 バインディングを自動計測するため（v10.57.0 以降）、手動でのラップは不要です
Queues は設定されていますか？	withSentry はキューハンドラーを自動計測します
Workflows は設定されていますか？	instrumentWorkflowWithSentry を推奨します
Cron トリガーは設定されていますか？	withSentry は scheduled ハンドラーを自動計測します。Crons の監視を推奨します
nodejs_als または nodejs_compat フラグは設定されていますか？	必須 — SDK には AsyncLocalStorage が必要です
AI／LLM ライブラリを使用していますか？	AI 監視のインテグレーションを推奨します
連携するフロントエンドはありますか？	フェーズ 4 のクロスリンクを実行します

---

フェーズ 2：提案

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

推奨（基本的なカバー範囲）：

• ✅ エラー監視 — 常に推奨します。fetch、scheduled、queue、email、Durable Object の各ハンドラーで捕捉されない例外を記録します
• ✅ トレーシング — HTTP リクエストスパン、アウトバウンド fetch のトレーシング、D1 クエリスパンを自動で記録します

任意（可観測性の強化）：

• ⚡ ロギング — Sentry.logger.* による構造化ログです。ログ検索が必要な場合に推奨します
• ⚡ Crons — 実行されなかった、または失敗したスケジュールジョブを検出します。cron トリガーが設定されている場合に推奨します
• ⚡ D1 インストルメンテーション — クエリスパンとブレッドクラムを自動で記録します。D1 がバインドされている場合に推奨します
• ⚡ Durable Objects — DO メソッドのエラーとスパンを自動で記録します。DO が設定されている場合に推奨します
• ⚡ Workflows — ワークフローのステップのスパンを自動で作成します。Workflows が設定されている場合に推奨します
• ⚡ AI 監視 — Vercel AI SDK、OpenAI、Anthropic、LangChain に対応します。AI ライブラリが検出された場合に推奨します

推奨ロジック：

機能	次の場合に推奨します
エラー監視	常に — 欠かせない基本機能です
トレーシング	常に — HTTP リクエストのトレーシングとアウトバウンド fetch は大きな価値があります
ロギング	アプリで構造化ログの検索、またはログとトレースの関連付けが必要な場合
Crons	wrangler.toml で cron トリガーが設定されている場合
D1 インストルメンテーション	D1 データベースのバインディングがある場合
Durable Objects	Durable Object のバインディングが設定されている場合
Workflows	Workflow のバインディングが設定されている場合
AI 監視	アプリで Vercel AI SDK、OpenAI、Anthropic、または LangChain を使用している場合
メトリクス	アプリでカスタムカウンター、ゲージ、または分布が必要な場合

次のように提案します。「エラー監視とトレーシングの設定をおすすめします。D1 インストルメンテーションと Crons の監視も追加しましょうか？」

---

フェーズ 3：設定方法の案内

オプション 1：ソースマップウィザード

この操作はご自身で実行する必要があります — ウィザードではログインのためにブラウザーを開き、エージェントが対応できない対話形式の入力が必要です。次のコマンドをターミナルにコピーして貼り付けてください。

npx @sentry/wizard@latest -i sourcemaps

これによりソースマップのアップロードが設定され、本番環境のスタックトレースに読みやすいコードが表示されます。SDK の初期化は設定されないため、実際の SDK の設定には、引き続き以下のオプション 2 に従う必要があります。

完了したら、SDK の設定を行うためにオプション 2 に進んでください。

注： フレームワーク SDK（Next.js、SvelteKit）とは異なり、Cloudflare 専用のウィザード連携はありません。sourcemaps ウィザードではソースマップのアップロード設定のみを行います。

---

オプション 2：手動設定

前提条件：互換性フラグ

SDK には AsyncLocalStorage が必要です。Wrangler の設定に次のフラグのいずれか 1 つを追加してください。

wrangler.toml：

compatibility_flags = ["nodejs_als"]
# or: compatibility_flags = ["nodejs_compat"]

wrangler.jsonc：

{
  "compatibility_flags": ["nodejs_als"]
}

nodejs_als は軽量で、AsyncLocalStorage のみを有効にします。コードでほかの Node.js API も必要な場合は、nodejs_compat を使用してください。

インストール

npm install @sentry/cloudflare

Workers の設定

ハンドラーを withSentry でラップします。これにより、fetch、scheduled、queue、email、tail の各ハンドラーが自動的にインストルメントされます。

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

export default Sentry.withSentry(
  (env: Env) => ({
    dsn: env.SENTRY_DSN,
    tracesSampleRate: 1.0,
    enableLogs: true,
    dataCollection: {
      // To disable sending user data and HTTP bodies, uncomment the lines below. For more info visit:
      // https://docs.sentry.io/platforms/javascript/guides/cloudflare/configuration/options/#dataCollection
      // userInfo: false,
      // httpBodies: [],
    },
  }),
  {
    async fetch(request, env, ctx) {
      return new Response("Hello World!");
    },
  } satisfies ExportedHandler<Env>,
);

要点：

• 第 1 引数は env を受け取るコールバックです。これを使って SENTRY_DSN などのシークレットを読み取ります
• SDK は DSN、環境、リリース、デバッグ、トンネル、トレースのサンプルレートを env から自動的に読み取ります（環境変数を参照）
• withSentry はエクスポートされたすべてのハンドラーをラップするため、scheduled、queue などを個別にラップする必要はありません

Pages の設定

ミドルウェアとして sentryPagesPlugin を使用します。

// functions/_middleware.ts
import * as Sentry from "@sentry/cloudflare";

export const onRequest = Sentry.sentryPagesPlugin((context) => ({
  dsn: context.env.SENTRY_DSN,
  tracesSampleRate: 1.0,
  enableLogs: true,
  dataCollection: {
    // To disable sending user data and HTTP bodies, uncomment the lines below. For more info visit:
    // https://docs.sentry.io/platforms/javascript/guides/cloudflare/configuration/options/#dataCollection
    // userInfo: false,
    // httpBodies: [],
  },
}));

複数のミドルウェアを連結する場合：

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

export const onRequest = [
  // Sentry must be first
  Sentry.sentryPagesPlugin((context) => ({
    dsn: context.env.SENTRY_DSN,
    tracesSampleRate: 1.0,
  })),
  // Add more middlewares here
];

wrapRequestHandler を直接使用する場合（Cloudflare Pages 上の SvelteKit などのフレームワーク向け）：

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

export const handle = ({ event, resolve }) => {
  return Sentry.wrapRequestHandler(
    {
      options: {
        dsn: event.platform.env.SENTRY_DSN,
        tracesSampleRate: 1.0,
      },
      request: event.request,
      context: event.platform.ctx,
    },
    () => resolve(event),
  );
};

Cloudflare Workers 上の Hono

推奨（v10.55.0 以降）： Hono アプリにはスタンドアロンの @sentry/hono パッケージを使用してください。

npm install @sentry/hono @sentry/cloudflare

@sentry/cloudflare パッケージはピア依存関係であり、@sentry/hono とバージョンを一致させる必要があります。

import { Hono } from "hono";
import { sentry } from "@sentry/hono/cloudflare";

type Bindings = { SENTRY_DSN: string };

const app = new Hono<{ Bindings: Bindings }>();

// Initialize Sentry middleware as early as possible
app.use(
  sentry(app, (env) => ({
    dsn: env.SENTRY_DSN,
    tracesSampleRate: 1.0,
  })),
);

app.get("/", (ctx) => ctx.json({ message: "Hello" }));

app.get("/error", () => {
  throw new Error("Test error");
});

export default app;

sentry() ミドルウェアは、エラーを自動的にキャプチャし、ルートパターンを使ってトランザクションスパンを作成します。

従来の方法（非推奨）： withSentry を使って @sentry/cloudflare を使用する方法も引き続き機能しますが、honoIntegration は非推奨です。

import { Hono } from "hono";
import * as Sentry from "@sentry/cloudflare";

const app = new Hono();

app.get("/", (ctx) => ctx.json({ message: "Hello" }));

export default Sentry.withSentry(
  (env: Env) => ({
    dsn: env.SENTRY_DSN,
    tracesSampleRate: 1.0,
  }),
  app,
);

SENTRY_DSN シークレットの設定

DSN は Cloudflare のシークレットとして保存し、ハードコードしないでください。

# Local development: add to .dev.vars
echo 'SENTRY_DSN="https://[email protected]/0"' >> .dev.vars

# Production: set as a secret
npx wrangler secret put SENTRY_DSN

Env 型にバインディングを追加します。

interface Env {
  SENTRY_DSN: string;
  // ... other bindings
}

ソースマップの設定

ソースマップを使用すると、本番環境のスタックトレースを読みやすくできます。ほとんどの Cloudflare プロジェクトは Wrangler 経由で Vite を使ってビルドするため、Sentry Vite プラグインを組み込み、ビルド時にマップをアップロードするようにします。

npm install @sentry/vite-plugin --save-dev

import { defineConfig } from "vite";
import { sentryVitePlugin } from "@sentry/vite-plugin";

export default defineConfig({
  build: {
    sourcemap: true,
  },
  plugins: [
    sentryVitePlugin({
      org: "___ORG_SLUG___",
      project: "___PROJECT_SLUG___",
      authToken: process.env.SENTRY_AUTH_TOKEN,
    }),
  ],
});

SENTRY_AUTH_TOKEN はビルド時のシークレットです。トークンの作成方法と CI への組み込み方については、sentry-source-maps を参照してください。上記の npx @sentry/wizard@latest -i sourcemaps というショートカットを使うと、この設定を自動化できます。

---

リリースの自動検出

SDK は Cloudflare のバージョンメタデータバインディングを使って、リリースバージョンを自動的に検出できます。

wrangler.toml：

[version_metadata]
binding = "CF_VERSION_METADATA"

リリースの優先順位（高い順）：

1. Sentry.init() に渡される release オプション
2. SENTRY_RELEASE 環境変数
3. CF_VERSION_METADATA.id バインディング

---

合意した機能ごとに

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

機能	リファレンスファイル	読み込むタイミング
エラーモニタリング	references/error-monitoring.md	常に（基本）— 未処理の例外、手動キャプチャ、スコープ、情報の付加
トレーシング	references/tracing.md	HTTP リクエストのトレーシング、送信 fetch スパン、D1 クエリスパン、分散トレーシング
ロギング	references/logging.md	Sentry.logger.* による構造化ログ、ログとトレースの相関
Cron	references/crons.md	スケジュールされたハンドラーのモニタリング、withMonitor、チェックイン API
Durable Objects	references/durable-objects.md	Durable Object クラスに計測機能を組み込み、エラーキャプチャとスパンを有効化

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

---

設定リファレンス

Sentry.init() のオプション

オプション	型	デフォルト	備考
dsn	string	—	必須です。設定されていない場合は、env.SENTRY_DSN から自動的に読み取ります
tracesSampleRate	number	—	0～1。開発環境では1.0、本番環境では低い値を推奨します
tracesSampler	function	—	動的サンプリング関数です。tracesSampleRate と同時には指定できません
dataCollection	object	設定しない場合は保守的	SDK が収集するデータ（userInfo、httpBodies など）を制御します。省略した場合は sendDefaultPii（デフォルトは false）にフォールバックします。このオブジェクトを渡すと（{} の場合も含む）、許可的なデフォルト設定が有効になります。データ収集リファレンスを参照してください
sendDefaultPii	boolean	false	レガシーなオプションです。収集するデータの制御には dataCollection を推奨します
enableLogs	boolean	false	Sentry Logs 製品を有効にします
environment	string	自動	設定されていない場合は、env.SENTRY_ENVIRONMENT から読み取ります
release	string	自動	CF_VERSION_METADATA.id または SENTRY_RELEASE から検出されます
debug	boolean	false	設定されていない場合は、env.SENTRY_DEBUG から読み取ります。SDK の動作をコンソールに記録します
tunnel	string	—	設定されていない場合は、env.SENTRY_TUNNEL から読み取ります
beforeSend	function	—	エラーイベントの送信前にフィルタリングまたは変更します
beforeSendTransaction	function	—	トランザクションイベントの送信前にフィルタリングまたは変更します
beforeSendLog	function	—	ログエントリの送信前にフィルタリングまたは変更します
tracePropagationTargets	(string|RegExp)[]	すべての URL	トレースヘッダーを付与する送信リクエストを制御します
skipOpenTelemetrySetup	boolean	false	OpenTelemetry 互換トレーサーをオプトアウトします
instrumentPrototypeMethods	boolean | string[]	false	Durable Object：RPC スパン用にプロトタイプメソッドを計測します

データ収集リファレンス

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

環境変数（env から読み取り）

SDK は、以下の環境変数を Cloudflare の env オブジェクトから自動的に読み取ります。

変数	用途
SENTRY_DSN	Sentry の初期化に使用する DSN
SENTRY_RELEASE	リリースバージョン文字列
SENTRY_ENVIRONMENT	環境名（production、staging）
SENTRY_TRACES_SAMPLE_RATE	トレースのサンプルレート（浮動小数点数として解析）
SENTRY_DEBUG	デバッグモードを有効化（"true" / "1"）
SENTRY_TUNNEL	イベントのプロキシに使用するトンネル URL
CF_VERSION_METADATA	Cloudflare バージョンメタデータバインディング（リリースを自動検出）

デフォルトのインテグレーション

以下は getDefaultIntegrations() によって自動的に登録されます。

インテグレーション	用途
dedupeIntegration	イベントの重複を防止します（Workflows では無効）
inboundFiltersIntegration	種類、メッセージ、URL に基づいてイベントをフィルタリングします
functionToStringIntegration	元の関数名を保持します
linkedErrorsIntegration	エラーの cause チェーンをたどります
fetchIntegration	送信 fetch() 呼び出しをトレースし、パンくずリストを作成します
honoIntegration	v10.55.0 で非推奨 — 代わりに @sentry/hono パッケージを使用してください。Hono の onError 例外を自動的に捕捉します
requestDataIntegration	リクエストデータをイベントに付加します
consoleIntegration	console.* 呼び出しをパンくずリストとして捕捉します

---

検証

セットアップ後、Sentry が動作していることを確認します。

// Add temporarily to your fetch handler, then remove
export default Sentry.withSentry(
  (env: Env) => ({
    dsn: env.SENTRY_DSN,
    tracesSampleRate: 1.0,
  }),
  {
    async fetch(request, env, ctx) {
      throw new Error("Sentry test error — delete me");
    },
  } satisfies ExportedHandler<Env>,
);

デプロイしてルートを実行し、Sentry Issues ダッシュボードを確認します。エラーは約30秒以内に表示されます。

検証チェックリスト：

確認項目	方法
エラーの捕捉	fetch ハンドラー内で例外をスローし、Sentry で確認します
トレーシングの動作	Performance タブで HTTP スパンを確認します
ソースマップの動作	スタックトレースに読みやすいファイル名と行番号が表示されることを確認します
D1 スパン（設定した場合）	D1 クエリを実行し、db.query スパンを確認します
スケジュール監視（設定した場合）	cron を実行し、Crons ダッシュボードを確認します

フェーズ 4：相互リンク

Cloudflare のセットアップが完了したら、関連サービスがあるか確認します。

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

# Check for companion backend in adjacent directories
ls ../backend ../server ../api 2>/dev/null
cat ../go.mod ../requirements.txt ../Gemfile 2>/dev/null | head -3

フロントエンドが見つかった場合は、対応する SDK スキルを提案します。

検出されたフロントエンド	提案するスキル
React	sentry-react-sdk
Next.js	sentry-nextjs-sdk
Svelte/SvelteKit	sentry-svelte-sdk
Vue/Nuxt	docs.sentry.io/platforms/javascript/guides/vue/ を参照

別のディレクトリにバックエンドが見つかった場合：

検出されたバックエンド	提案するスキル
Go（go.mod）	sentry-go-sdk
Python（requirements.txt、pyproject.toml）	sentry-python-sdk
Ruby（Gemfile）	sentry-ruby-sdk
Node.js（Express、Fastify）	sentry-node-sdk

フロントエンドとバックエンドをリンクされた Sentry プロジェクトで接続すると、分散トレーシングが可能になります。これは、ブラウザー、Cloudflare Worker、バックエンド API にまたがるスタックトレースを、1 つのトレースビューで確認できる機能です。

---

トラブルシューティング

問題	原因	解決策
イベントが表示されない	DSN が設定されていない、または debug: false によってエラーが非表示になっている	初期化オプションで一時的に debug: true を設定します。wrangler secret list で SENTRY_DSN シークレットが設定されていることを確認します
AsyncLocalStorage is not defined	互換性フラグが不足している	wrangler.toml の compatibility_flags に nodejs_als または nodejs_compat を追加します
スタックトレースに圧縮されたコードが表示される	ソースマップがアップロードされていない	@sentry/vite-plugin を設定するか、npx @sentry/wizard -i sourcemaps を実行します。CI で SENTRY_AUTH_TOKEN を確認します
短時間で終了するリクエストでイベントが失われる	Worker が終了する前に SDK のフラッシュが行われていない	withSentry または sentryPagesPlugin でハンドラーをラップします。これらは ctx.waitUntil() を使ってフラッシュします
Hono のエラーが捕捉されない	Hono アプリが計測されていない	@sentry/hono/cloudflare を使います。sentry ミドルウェアをインポートし、app.use(sentry(app, options)) を呼び出します
Durable Object のエラーが見つからない	DO クラスが計測されていない	Sentry.instrumentDurableObjectWithSentry() でクラスをラップします。references/durable-objects.md を参照してください
D1 クエリでスパンが作成されない	ハンドラーが withSentry でラップされていない、または env 以外のバインディングにクエリしている	env 上の D1 バインディングは withSentry によって自動計測されます（v10.57.0 以降）。手動でのラップは不要です（instrumentD1WithSentry は非推奨です）。すべてのクエリメソッド（prepare、batch、exec、withSession）は v10.61.0 以降でトレースされます
スケジュールされたハンドラーが監視されない	ハンドラーが withSentry でラップされていない	export default Sentry.withSentry(...) で、エクスポートされたハンドラーオブジェクト全体をラップしていることを確認します
リリースが自動検出されない	CF_VERSION_METADATA バインディングが設定されていない	wrangler.toml に binding = "CF_VERSION_METADATA" を含む [version_metadata] を追加します
Workflows でイベントが重複する	重複排除インテグレーションがステップの失敗をフィルタリングしている	SDK は Workflows の重複排除を自動的に無効にします。instrumentWorkflowWithSentry を使っていることを確認します