観測・デプロイ運用・料金

観測の基本 — ログ・メトリクス・スタックトレース

Workers Logs — 保存して検索できるログ

Workers Logs は、Worker が出力するログを Cloudflare アカウントに自動収集・保存し、ダッシュボードで検索・分析できる仕組みです。新規に作成した Worker では既定で有効ですが、既存プロジェクトでは wrangler.jsonc に observability 設定を追加して再デプロイする必要があります（Wrangler 3.78.6 以上）。

{
	"observability": {
		"enabled": true,
		"head_sampling_rate": 1 // 省略可。既定 = 1（100% 記録）
	}
}

記録されるのは、リクエストごとに 1 件自動生成される invocation log（リクエスト・レスポンス・メタデータ）と、コード中の console.log によるカスタムログ、そして例外です。カスタムログは文字列連結ではなくオブジェクトをそのまま渡すのが定石です。フィールドが自動でインデックスされ、user_id のようなキーでの絞り込みが高速になります。

// NG: テキストマッチでしか検索できない
console.log("user_id: " + 123);

// OK: user_id キーでフィルタできる
console.log({ user_id: 123, event: "checkout" });

高トラフィックなアプリでは head_sampling_rate を 0〜1 で指定し、記録するリクエストの割合を下げてコストを抑えます（例: 0.01 = 1%）。1 ログの上限は 256 KB で、超過分は切り詰められます。料金と保持期間（2026-08 時点）は次のとおりです。

wrangler tail — リアルタイムログ

デプロイ直後の動作確認には、グローバルのログイベントをほぼリアルタイムで流し込む wrangler tail が便利です。プロジェクトディレクトリで実行するだけで、受信リクエストごとの構造化 JSON が届きます。

npx wrangler tail
# jq と組み合わせて必要なフィールドだけ抽出
npx wrangler tail --format json | jq .event.request.url
# エラーになった呼び出しだけに絞る
npx wrangler tail --status error

--method / --search（console.log 本文のテキストマッチ）/ --ip self / --version-id などのフィルタも使えます。リアルタイムログは保存されないことに注意してください。後から調べるためのログは Workers Logs の役割です。第三者サービスへ送りたい場合は OpenTelemetry エクスポート、Workers Logpush（Paid のみ）、Tail Workers が使えます。

メトリクスとダッシュボード分析

ダッシュボードの Workers & Pages で Worker を選ぶと、リクエスト成功/失敗数、サブリクエスト数、実行ごとの wall time / CPU 時間 / メモリ使用量（分位点表示）などのメトリクスを確認できます。メトリクスは過去 3 か月まで遡れます。ここで重要なのが invocation status（呼び出しステータス）です。HTTP ステータスコードとは別物で、Worker の実行そのものが成功したかを示します。

ルート（route）にひも付けた Worker 群の集計は、ゾーンごとの Workers Analytics（過去 30 日）で確認します。アプリ固有のカスタム指標を取りたい場合は Workers Analytics Engine が用意されています。

ソースマップでスタックトレースを復元する

本番の Worker はバンドル・ミニファイ済みのため、素のスタックトレースは「1 行に潰れた js の何文字目」しか教えてくれません。wrangler.jsonc に 1 行足すと、デプロイ時にソースマップが自動生成・アップロードされ、未捕捉例外のスタックトレースが元の TypeScript のファイル名・行番号に自動で逆引きされます（Wrangler 3.46.0 以上、上限 15 MB gzip）。

{
	"upload_source_maps": true
}

復元されたトレースはリアルタイムログや Tail Workers で確認できます。逆引きは呼び出し完了後に非同期で行われるため CPU 時間には影響しませんが、Worker 内で error.stack を console.log しても復元済みトレースは得られない点に注意してください。

Versions と gradual deployments — 段階的に出す、即座に戻す

Worker のコードや設定を変更するたびに version（バンドル済みコード・静的アセット・バインディング・互換性設定のスナップショット）が作られます。どの version がトラフィックを受けるかを決めるのが deployment です。npx wrangler deploy はこの 2 つを一度に行い、新 version を即座に 100% のトラフィックへ展開します。

この 2 つを分離すると、gradual deployment（段階的ロールアウト）が可能になります。まず versions upload でデプロイせずに version だけを作り、versions deploy で新旧 2 version 間のトラフィック比率を指定します。

# 1. デプロイせずに新バージョンをアップロード
npx wrangler versions upload --message "checkout flow v2"

# 2. 対話プロンプトで比率を指定してデプロイ（例: 旧 90% / 新 10%）
npx wrangler versions deploy

# 非対話で比率を直接指定することもできる
npx wrangler versions deploy <OLD_VERSION_ID>@90% <NEW_VERSION_ID>@10% -y

<OLD_VERSION_ID> / <NEW_VERSION_ID> は npx wrangler versions list で確認できる UUID に置き換えます。エラー率をメトリクス（--version-id 付きの wrangler tail や Version metadata binding）で観測しながら、新 version の比率を段階的に 100% まで上げるのが基本の運用です。分割中は複数 version が同時に稼働するため、同一ユーザーのリクエストが version 間を行き来する version skew が起きえます。ユーザーを一定期間同じ version に固定したい場合は version affinity を使います。

問題が起きたら rollback です。直近 100 version 以内なら、指定 version を即座に 100% トラフィックの新 deployment として展開できます。

# 1 つ前のバージョンに戻す（ID 指定も可）
npx wrangler rollback
# 現在の稼働状態を確認
npx wrangler deployments status

ただし rollback が戻すのはコードと設定だけです。KV・R2・D1・Durable Objects のデータは戻りませんし、バインディング先のリソースを削除・変更していた場合（例: 対象 version が参照する KV namespace を削除済み）はロールバック自体が拒否されます。

limits と料金 — 上限を知り、課金を見積もる

Workers の料金は「リクエスト数」と「CPU ミリ秒」の 2 軸だけで決まります。CPU 時間はコードが実際に CPU を使った時間で、fetch() や KV 読み取りなど I/O を待っている時間（wall time との差分）は含まれず、課金もされません。duration・データ転送（egress）・帯域への課金はありません。主要な上限と料金（2026-08 時点）は次のとおりです。

試算例: 月 1,500 万リクエスト・平均 CPU 7 ms の Worker なら、基本料 $5.00 + リクエスト超過分 $1.50（500 万 × $0.30/100 万）+ CPU 超過分 $1.50（1 億 500 万 ms − 3,000 万 ms ≒ 7,500 万 ms × $0.02/100 万）= 月 $8.00 です。サブリクエストは課金されず、静的アセットへのリクエストは無料・無制限です。

そのほか、同時に応答待ちできる外部接続は 6、環境変数は 1 つ 5 KB で Free 64 個 / Paid 128 個、グローバルスコープの初期化（startup）は 1 秒以内、という上限もあります。Cron・Queue・Durable Object アラームの呼び出しは wall time 15 分までです。暴走やコスト攻撃への保険として、CPU 時間の上限は Worker ごとに明示設定できます（引き上げは Paid のみ、最大 300,000 ms）。

{
	"limits": {
		"cpu_ms": 300000 // 既定は 30000（30 秒）
	}
}

nodejs_compat と CI/CD — npm パッケージとデプロイ自動化

Node.js 互換（nodejs_compat）

npm パッケージの多くは node:buffer や node:crypto といった Node.js API に依存しています。Workers ランタイムはこれらの API のサブセットを提供しており、nodejs_compat フラグを有効化し、compatibility_date を 2024-09-23 以降にすると使えるようになります。

{
	"compatibility_flags": ["nodejs_compat"],
	"compatibility_date": "2026-08-11"
}

Buffer / Crypto / EventEmitter / File system / HTTP(S) / Net / Path / Process / Stream / Timers / URL / Zlib などはランタイムがネイティブ実装しており、未実装の API は Wrangler が unenv によるポリフィルを注入します。ポリフィルされたモジュールは import は通りますが、未実装メソッドを呼ぶと [unenv] <method name> is not implemented yet! という実行時エラーになります。「バンドルは通ったのに本番で落ちる」パターンの典型なので、依存パッケージの動作確認は必須です。AsyncLocalStorage だけ必要なら軽量な nodejs_als フラグもあります。

CI/CD — Workers Builds と GitHub 連携

手元からの wrangler deploy は、チーム開発では「誰の環境から何がデプロイされたか分からない」問題を生みます。Workers Builds は Cloudflare 内蔵の CI/CD で、GitHub / GitLab リポジトリを Worker に接続すると、対象ブランチへの push のたびに自動でビルド・デプロイされます。設定はダッシュボードで完結します。

1. 新規なら Workers & Pages → Create application → Import a repository からリポジトリを選択
2. 既存 Worker なら対象 Worker の Settings → Builds → Connect で接続し、ビルド設定を構成
3. push するとビルドが走り、成功すると version としてアップロード。deploy command が npx wrangler deploy なら、その version がそのまま Active Deployment に昇格

deploy command を npx wrangler versions upload に変えると「ビルドと version 化は自動、本番反映は手動（gradual deployment で）」という安全側の運用にできます。接続時はダッシュボード上の Worker 名と Wrangler 設定の name が一致している必要があります。self-hosted の Git や他のプロバイダを使う場合は、GitHub Actions など外部 CI/CD から wrangler を実行する構成が推奨されています。

つまずきポイント

理解度チェック

まとめと次章へ

• ログは二層構造 — その場の確認は wrangler tail、保存・検索は Workers Logs（observability.enabled）。構造化ログ（オブジェクトを console.log）が検索性の鍵
• エラー調査はダッシュボードの invocation status で分類し、upload_source_maps で元ソースの行番号までたどる
• リリースは versions upload → versions deploy の段階的ロールアウトが基本。問題があれば wrangler rollback で即時復旧（ただしデータは戻らない）
• 課金はリクエスト数 + CPU ms の 2 軸のみ。Free は CPU 10 ms / 10 万リクエスト/日、Paid は既定 CPU 30 秒（最大 5 分）。limits.cpu_ms が暴走への保険になる
• npm パッケージ利用は nodejs_compat + compatibility date 2024-09-23 以降。デプロイの自動化は Workers Builds の GitHub / GitLab 連携で

これで観測・デプロイ・コストという「本番運用の三種の神器」が揃いました。最終章では、ここまでの全要素を組み合わせてミニ SaaS を丸ごと構築する総合演習に挑みます。

• Workers Logs / Real-time logs
• Metrics and analytics / Source maps and stack traces
• Versions & deployments / Gradual deployments / Rollbacks
• Limits / Pricing
• Node.js compatibility / Workers Builds