Workers scheduled cron を wrangler tail でリアルタイムログ確認する手順

Cloudflare Workers の scheduled イベント（cron trigger）を設定したはいいが、「本当に動いているのか確認できない」という状況に陥りやすい。この記事では、wrangler.toml への cron 設定からハンドラの実装、wrangler tail によるログ確認、ローカルテストの手順まで、実際に再現できる形でまとめる。

scheduled イベントとは何か

Cloudflare Workers には HTTP リクエストを受け取るだけでなく、cron スケジュールで定期実行する仕組みがある。これが scheduled イベント（cron trigger） だ。

仕組みはシンプルで、wrangler.toml に cron 式を書くと、Cloudflare の側から指定した時刻に Worker が呼び出される。Worker コードは scheduled ハンドラで受け取り、通常の HTTP ハンドラとは別のエントリポイントとして動く。

HTTP エンドポイントを公開せずに定期処理だけ走らせたい場合（例：定期的なデータ集計、外部 API のポーリング、DB の定期クリーンアップ）に有用だ。

wrangler.toml への cron 設定

cron trigger は wrangler.toml（または wrangler.jsonc）の [triggers] セクションに記述する。

name = "my-cron-worker"
main = "src/index.ts"
compatibility_date = "2024-11-01"

[triggers]
crons = ["0 4 * * *"]

複数のスケジュールを設定する場合は配列に並べる。

[triggers]
crons = ["0 4 * * *", "*/30 * * * *"]

重要：cron の時刻は UTC 基準。日本時間（JST = UTC+9）で「毎朝 4:30 に実行したい」なら 30 19 * * *（前日 19:30 UTC）と書く必要がある。ここを JST のまま書いてしまうのはよくあるミスなので注意したい。

cron 式の各フィールドは以下の順。

公式ドキュメントによると、実行間隔の最小単位は 1 分。毎秒実行のような細粒度の制御は scheduled イベントではできない（執筆時点）。

Worker のコード：scheduled ハンドラの書き方

TypeScript で書く場合の最小構成は次のようになる。

export interface Env {
  // KV や D1 など、バインドを使う場合はここに追加
}

export default {
  async scheduled(
    event: ScheduledEvent,
    env: Env,
    ctx: ExecutionContext
  ): Promise<void> {
    console.log(
      `scheduled fired: cron=${event.cron}, scheduledTime=${event.scheduledTime}`
    );
    await doSomething(env);
  },

  async fetch(request: Request, env: Env): Promise<Response> {
    return new Response("OK");
  },
};

async function doSomething(env: Env): Promise<void> {
  // 実際の処理をここに書く
}

event.cron には wrangler.toml に書いた cron 式の文字列が入る。複数の cron を登録している場合、どの cron で呼ばれたかをここで判別できる。event.scheduledTime は UNIX エポック（ミリ秒）で渡される。

scheduled のみの Worker では fetch ハンドラを省略できる場合もあるが、空の fetch を用意しておくと構成が明示的になり無難だ。

console.log() を使った出力は Workers のログとして記録され、後述の wrangler tail で確認できる。エラーは console.error() で出力しておくと、ログフィルタリングで絞り込みやすい。

wrangler tail でログをリアルタイムに確認する

デプロイ後、Worker が実際に動いているかを確認するには wrangler tail を使う。実行中のまま次の scheduled 実行を待ち受けることができる。

wrangler tail --format=pretty

--format=pretty を付けると人間が読みやすい整形で出力される。JSON で後処理したい場合は --format=json。出力例は次のような形になる（環境によって異なります）。

[2024-11-01 04:00:01] [info] scheduled fired: cron=0 4 * * *, scheduledTime=1730437200000

よく使うオプション

wrangler tail はリアルタイムのストリーミングであり、過去のログは遡れない。cron が数時間後に実行される場合はコマンドを起動したまま待つ必要がある。

過去ログを永続化したい場合は、Workers Analytics Engine や R2 に書き出す構成が必要になる。あるいは外部の監視サービスへ Logpush で転送する方法もある。用途に応じて検討するといい。

ローカルで scheduled イベントをテストする

本番デプロイ前にローカルで scheduled イベントを動かすには、--test-scheduled フラグを使う。

wrangler dev --test-scheduled

このフラグを付けて wrangler dev を起動すると、/__scheduled というエンドポイントが有効になる。curl やブラウザで叩くことで、手動で scheduled イベントをトリガーできる。

# cron 式を指定してトリガー（スペースを + でURLエンコード）
curl "http://localhost:8787/__scheduled?cron=0+4+*+*+*"

cron パラメータを省略した場合は、wrangler.toml に書いた最初の cron 式が使われる。

# パラメータ省略（最初に登録された cron を使用）
curl "http://localhost:8787/__scheduled"

ローカルの wrangler dev ではターミナルに直接 console.log の出力が流れるので、wrangler tail は不要だ。確認方法がシンプルに済む分、ここでしっかりロジックを検証しておくと、本番デプロイ後のデバッグが楽になる。

デプロイと確認の全体フロー

wrangler.toml に [triggers] crons を設定
         ↓
wrangler dev --test-scheduled でローカル動作確認
         ↓
curl localhost:8787/__scheduled でトリガーしログを目視
         ↓
wrangler deploy でデプロイ
         ↓
wrangler tail --format=pretty を起動して待機
         ↓
cron のタイミングでログが流れることを確認

なお、fetch ハンドラと scheduled ハンドラを同一 Worker に共存させる構成の感覚は、Hono × Cloudflare WorkersでSSEを実装——streamSSEからEventSource受信まで を読むと補完できる。

まとめ

Cloudflare Workers の scheduled イベントを確認するポイントは3つだ。

1. wrangler.toml の [triggers] に crons を書く。時刻は UTC なので JST との9時間差に注意する。
2. console.log / console.error でログを出力する。scheduled ハンドラ内の出力は wrangler tail で確認できる。
3. 本番確認は wrangler tail --format=pretty。リアルタイムストリームなので、cron 実行のタイミングまで起動したまま待つ。

まずは wrangler dev --test-scheduled でローカル動作を確認し、curl localhost:8787/__scheduled でトリガーしてみるところから始めてほしい。ログが流れることを目視で確認できると、本番への自信が一段上がる。