All Skills > SDK Setup > Cloudflare SDK

Sentry Cloudflare SDK

Cloudflare プロジェクトをスキャンして、Workers、Pages、Durable Objects、Queues、Workflows、Hono の完全な Sentry セットアップをガイドする意見を持ったウィザード。

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

• ユーザーが Cloudflare プロジェクトで「Sentry を Cloudflare Workers に追加する」または「Sentry をセットアップする」と要求している
• ユーザーが @sentry/cloudflare をインストールまたは設定したい
• Cloudflare Workers または Pages のエラーモニタリング、トレーシング、ロギング、crons、AI モニタリングが必要
• ユーザーが withSentry、sentryPagesPlugin、instrumentDurableObjectWithSentry、または instrumentD1WithSentry について質問している
• Cloudflare 上の Durable Objects、Queues、Workflows、Scheduled ハンドラー、Email ハンドラーをモニタリングしたい

注: 以下の SDK バージョンと API は執筆時点の Sentry ドキュメント (@sentry/cloudflare v10.43.0) を反映しています。 実装する前に、必ず docs.sentry.io/platforms/javascript/guides/cloudflare/ で確認してください。

---

フェーズ 1: 検出

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

# Cloudflare プロジェクトを検出
ls wrangler.toml wrangler.jsonc wrangler.json 2>/dev/null

# 既存の Sentry を検出
cat package.json 2>/dev/null | grep -E '"@sentry/'

# プロジェクトタイプを検出 (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'

# フレームワークを検出
cat package.json 2>/dev/null | grep -E '"hono"|"remix"|"astro"|"svelte"'

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

# D1 データベースを検出
cat wrangler.toml 2>/dev/null | grep -i 'd1_databases'

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

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

# Scheduled ハンドラー (cron トリガー) を検出
cat wrangler.toml 2>/dev/null | grep -i 'crons\|triggers'

# 互換性フラグを検出
cat wrangler.toml 2>/dev/null | grep -i 'compatibility_flags'
cat wrangler.jsonc 2>/dev/null | grep -i 'compatibility_flags'

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

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

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

決定すべきこと：

質問	影響
Workers か Pages か？	ラッパーの決定: withSentry vs sentryPagesPlugin
Hono フレームワークか？	honoIntegration 経由の自動 Hono エラーハンドラー統合
@sentry/cloudflare は既にインストール済みか？	インストールをスキップして機能設定へ
Durable Objects が設定されているか？	instrumentDurableObjectWithSentry を推奨
D1 データベースがバインドされているか？	instrumentD1WithSentry を推奨
Queues が設定されているか？	withSentry がキューハンドラーを自動計装
Workflows が設定されているか？	instrumentWorkflowWithSentry を推奨
Cron トリガーが設定されているか？	withSentry がスケジュール済みハンドラーを自動計装；Crons モニタリングを推奨
nodejs_als または nodejs_compat フラグが設定されているか？	必須 — SDK は AsyncLocalStorage が必要
AI/LLM ライブラリがあるか？	AI Monitoring 統合を推奨
コンパニオンフロントエンドか？	フェーズ 4 のクロスリンクをトリガー

---

フェーズ 2: 推奨

見つけたものに基づいて、具体的な推奨を提示します。オープンエンドの質問をしないで、提案をリードします：

推奨 (コアカバレッジ):

• ✅ エラーモニタリング — 常に；fetch、scheduled、queue、email、Durable Object ハンドラー内のハンドルされない例外をキャプチャ
• ✅ トレーシング — 自動 HTTP リクエストスパン、アウトバウンド fetch トレーシング、D1 クエリスパン

オプション (強化された可視性):

• ⚡ ロギング — Sentry.logger.* 経由の構造化ログ；ログ検索が必要な場合に推奨
• ⚡ Crons — 見落とされた/失敗したスケジュール済みジョブを検出；cron トリガーが設定されている場合に推奨
• ⚡ D1 計装 — 自動クエリスパンとブレッドクラム；D1 がバインドされている場合に推奨
• ⚡ Durable Objects — DO メソッドの自動エラーキャプチャとスパン；DO が設定されている場合に推奨
• ⚡ Workflows — ワークフロータスのための自動スパン作成；Workflows がバインドされている場合に推奨
• ⚡ AI Monitoring — Vercel AI SDK、OpenAI、Anthropic、LangChain；AI ライブラリが検出された場合に推奨

推奨ロジック：

機能	推奨するタイミング...
エラーモニタリング	常に — 交渉の余地のないベースライン
トレーシング	常に — HTTP リクエストトレーシングとアウトバウンド fetch は高い価値
ロギング	アプリが構造化ログ検索またはログ対トレース相関が必要
Crons	wrangler.toml に cron トリガーが設定されている
D1 計装	D1 データベースバインディングが存在する
Durable Objects	Durable Object バインディングが設定されている
Workflows	Workflow バインディングが設定されている
AI Monitoring	アプリが Vercel AI SDK、OpenAI、Anthropic、または LangChain を使用している
メトリクス	アプリがカスタムカウンター、ゲージ、または分布が必要

提案: 「エラーモニタリング + トレーシングをセットアップすることをお勧めします。D1 計装と Crons モニタリングも追加しましょうか？」

---

フェーズ 3: ガイド

オプション 1: Source Maps ウィザード

これは自分で実行する必要があります — ウィザードはログイン用にブラウザを開き、エージェントが処理できないインタラクティブな入力が必要です。ターミナルにコピー＆ペーストしてください：

npx @sentry/wizard@latest -i sourcemaps

これにより、本番スタックトレースが読み取り可能なコードを表示するように source maps アップロードがセットアップされます。SDK 初期化はセットアップされません — 下記のオプション 2 で実際の SDK セットアップを実行する必要があります。

完了したら、SDK セットアップについてはオプション 2 に進んでください。

注: フレームワーク SDK (Next.js、SvelteKit) とは異なり、Cloudflare 固有のウィザード統合はありません。sourcemaps ウィザードは source maps アップロード設定のみを処理します。

---

オプション 2: 手動セットアップ

前提条件: 互換性フラグ

SDK は AsyncLocalStorage が必要です。Wrangler 設定に以下のいずれかを追加します：

wrangler.toml:

compatibility_flags = ["nodejs_als"]
# または: 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,
    sendDefaultPii: true,
    tracesSampleRate: 1.0,
    enableLogs: true,
  }),
  {
    async fetch(request, env, ctx) {
      return new Response("Hello World!");
    },
  } satisfies ExportedHandler<Env>,
);

重要なポイント：

• 最初の引数は env を受け取るコールバック — これを使って SENTRY_DSN のようなシークレットを読み込みます
• SDK は自動的に DSN、environment、release、debug、tunnel、トレースサンプルレートを 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,
  sendDefaultPii: true,
  tracesSampleRate: 1.0,
  enableLogs: true,
}));

複数ミドルウェアをチェーンする：

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

export const onRequest = [
  // Sentry は最初である必要があります
  Sentry.sentryPagesPlugin((context) => ({
    dsn: context.env.SENTRY_DSN,
    tracesSampleRate: 1.0,
  })),
  // ここにさらにミドルウェアを追加
];

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

Hono アプリは fetch メソッドを持つオブジェクト — withSentry で直接ラップします：

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

const app = new Hono();

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

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

app.onError((err, ctx) => {
  return ctx.json({ error: err.message }, 500);
});

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

honoIntegration (デフォルトで有効) は Hono の onError ハンドラーからのエラーを自動的にキャプチャして、ルートパスで正しいトランザクション名を設定します。

SENTRY_DSN シークレットをセットアップ

DSN を Cloudflare シークレットに保存します — ハードコードしないでください：

# ローカル開発: .dev.vars に追加
echo 'SENTRY_DSN="https://examplePublicKey@o0.ingest.sentry.io/0"' >> .dev.vars

# 本番: シークレットとして設定
npx wrangler secret put SENTRY_DSN

Env タイプにバインディングを追加します：

interface Env {
  SENTRY_DSN: string;
  // ... その他のバインディング
}

Source Maps セットアップ

Source maps により本番スタックトレースが読み取り可能になります。これがないと、最小化/バンドルされたコードが表示されます。

ステップ 1: Sentry 認証トークンを生成

sentry.io/settings/auth-tokens/ にアクセスして、project:releases と org:read スコープを持つトークンを作成します。

ステップ 2: Sentry Vite プラグインをインストール (ほとんどの Cloudflare プロジェクトは Wrangler 経由で Vite を使用)：

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

ステップ 3: vite.config.ts を設定 (プロジェクトにある場合)：

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,
    }),
  ],
});

ステップ 4: CI 環境変数を設定

SENTRY_AUTH_TOKEN=sntrys_eyJ...
SENTRY_ORG=my-org
SENTRY_PROJECT=my-project

ステップ 5: .gitignore に追加

.dev.vars
.env.sentry-build-plugin

---

自動リリース検出

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.* 経由の構造化ログ、ログ対トレース相関
Crons	references/crons.md	スケジュール済みハンドラーモニタリング、withMonitor、チェックイン API
Durable Objects	references/durable-objects.md	Durable Object クラスを計装してエラーキャプチャとスパンを実現

各機能について：参照ファイルを読み、そのステップを正確に従い、移動する前に確認してください。

---

検証

セットアップ後、Sentry が機能していることを確認します：

// 一時的にハンドラーに追加して、削除します
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 スパンをチェック
Source maps が機能している	スタックトレースが読み取り可能なファイル/行名を表示することを確認
D1 スパン (設定されている場合)	D1 クエリを実行、db.query スパンをチェック
Scheduled モニタリング (設定されている場合)	cron をトリガー、Crons ダッシュボードをチェック

---

設定リファレンス

Sentry.init() オプション

オプション	タイプ	デフォルト	注釈
dsn	string	—	必須。設定されていない場合は env.SENTRY_DSN から自動的に読み込まれます
tracesSampleRate	number	—	0–1；開発環境では 1.0、本番では低い値を推奨
tracesSampler	function	—	動的サンプリング関数；tracesSampleRate と相互に排他的
sendDefaultPii	boolean	false	イベントにリクエストヘッダーとクッキーを含める
enableLogs	boolean	false	Sentry Logs プロダクトを有効化
environment	string	auto	設定されていない場合は env.SENTRY_ENVIRONMENT から読み込まれます
release	string	auto	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)[]	all URLs	どのアウトバウンドリクエストがトレースヘッダーを取得するかを制御
skipOpenTelemetrySetup	boolean	false	OpenTelemetry 互換トレーサーをオプトアウト
instrumentPrototypeMethods	boolean | string[]	false	Durable Object: RPC スパン用にプロトタイプメソッドを計装

環境変数 (env から読み込まれます)

SDK は Cloudflare env オブジェクトからこれらを自動的に読み込みます：

変数	目的
SENTRY_DSN	Sentry init 用の DSN
SENTRY_RELEASE	リリースバージョン文字列
SENTRY_ENVIRONMENT	環境名 (production、staging)
SENTRY_TRACES_SAMPLE_RATE	トレースサンプルレート (float として解析)
SENTRY_DEBUG	デバッグモードを有効化 ("true" / "1")
SENTRY_TUNNEL	イベントプロキシ用のトンネル URL
CF_VERSION_METADATA	Cloudflare バージョンメタデータバインディング (自動検出リリース)

デフォルト統合

これらは getDefaultIntegrations() によって自動的に登録されます：

統合	目的
dedupeIntegration	重複イベントを防止 (Workflows では無効)
inboundFiltersIntegration	タイプ、メッセージ、URL でイベントをフィルター
functionToStringIntegration	元の関数名を保持
linkedErrorsIntegration	エラーの cause チェーンをフォロー
fetchIntegration	アウトバウンド fetch() 呼び出しをトレース、ブレッドクラムを作成
honoIntegration	Hono onError 例外を自動キャプチャ
requestDataIntegration	リクエストデータをイベントにアタッチ
consoleIntegration	console.* 呼び出しをブレッドクラムとしてキャプチャ

---

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

Cloudflare セットアップを完了した後、コンパニオンサービスをチェックします：

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

# 隣接ディレクトリのコンパニオンバックエンドを確認
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 にまたがるスタックトレースが単一トレースビューで表示されます。

---

トラブルシューティング

問題	原因	解決策
イベントが表示されない	DSN が設定されていない、または debug: false がエラーを隠している	init オプションで一時的に debug: true を設定；wrangler secret list で SENTRY_DSN シークレットが設定されていることを確認
AsyncLocalStorage is not defined	互換性フラグが不足している	wrangler.toml の compatibility_flags に nodejs_als または nodejs_compat を追加
スタックトレースが最小化されたコードを表示している	Source maps がアップロードされていない	@sentry/vite-plugin を設定するか npx @sentry/wizard -i sourcemaps を実行；CI で SENTRY_AUTH_TOKEN が設定されていることを確認
ワーカー終了時にイベントが失われている	SDK がワーカー終了前にフラッシュされていない	withSentry または sentryPagesPlugin がハンドラーをラップしていることを確認 — ctx.waitUntil() を使用してフラッシュ
Hono エラーがキャプチャされていない	Hono アプリが withSentry でラップされていない	Hono アプリを Sentry.withSentry() の第 2 引数として渡す
Durable Object エラーが見落とされている	DO クラスが計装されていない	Sentry.instrumentDurableObjectWithSentry() でクラスをラップ — references/durable-objects.md を参照
D1 クエリがスパンを作成していない	D1 バインディングが計装されていない	使用前に Sentry.instrumentD1WithSentry(env.DB) でバインディングをラップ
Scheduled ハンドラーがモニタリングされていない	withSentry がハンドラーをラップしていない	エクスポートされたハンドラーオブジェクト全体が export default Sentry.withSentry(...) でラップされていることを確認
リリースが自動検出されていない	CF_VERSION_METADATA バインディングが設定されていない	wrangler.toml に [version_metadata] と binding = "CF_VERSION_METADATA" を追加
Workflows でイベントが重複している	Dedupe 統合フィルタリングステップが失敗している	SDK は Workflows で自動的に dedupe を無効化；instrumentWorkflowWithSentry を使用していることを確認