Logpush

解決する課題

Cloudflareのエッジで発生する大量のログを、手動でダウンロードしたり都度APIを叩いて取得したりする運用から脱却し、継続的かつ自動的に外部へ届けられるようにします。

• CDN・WAF・Workersなどが生成する大量のリクエストログを、自前のログ基盤やSIEMへ継続的に送りたい
• セキュリティインシデント調査のために、過去に遡ってリクエスト単位のログを保持・検索したい
• 複数ゾーンやアカウント全体のログを一元的な分析基盤に集約し、横断的に可視化したい
• ログの取得をポーリングではなくプッシュ型にして、取りこぼしや遅延を減らしたい
• コンプライアンス要件で、アクセスログを一定期間そのまま保管しておく必要がある

主要概念と用語

• Logpushジョブ（Logpush Job）: どのログセットを、どの配信先へ、どの頻度で送るかを定義する設定単位。ゾーン単位またはアカウント単位で作成する
• ログセット（Dataset）: 配信対象となるログの種類。HTTPリクエストログ、ファイアウォールイベント、DNSログ、Workersの実行トレースなど複数のデータセットから選ぶ
• フィールド選択（Log Fields）: ログセットに含まれる項目のうち、実際に配信するフィールドを取捨選択する設定。不要な項目を外すことで転送量を抑えられる
• 配信先（Destination）: ログの送り先。オブジェクトストレージ（R2やS3互換ストレージ）、SplunkやDatadogなどのSaaS型分析基盤、汎用HTTPエンドポイントなどに対応する
• オーナーシップチャレンジ（Ownership Challenge）: 配信先が本当にそのアカウントの管理下にあることを確認するための検証手順。新しい配信先を登録する際に必須
• バッチ・圧縮（Batch / Compression）: ログは一定間隔・サイズでバッチ化され、圧縮された形式（gzipなど）でNDJSON（改行区切りJSON）として配信される
• フィルタ（Filter）: 特定の条件（ステータスコードやホスト名など）に合致するログだけを配信対象に絞る設定

仕様・制限・クォータ

• Logpushはプラン（主にEnterprise系）に応じて利用可能なログセットや保持期間が異なり、無料プランでは利用できない機能が多い
• ログの配信はニアリアルタイムであり、瞬時ではない。バッチ化・圧縮・配信先への書き込みにかかる時間だけ遅延が生じる
• 1つのジョブが扱えるログセットは基本的に1つであり、複数種類のログを1本のジョブにまとめて送ることはできない
• 配信先の登録にはオーナーシップチャレンジが必要で、未検証の宛先へは配信できない
• フィールドやフィルタの選択肢はログセットごとに異なり、すべてのログセットが同じ粒度の項目を持つわけではない
• 配信失敗時にはリトライが行われるが、恒久的な失敗が続くとジョブが自動的に無効化されることがある

内部の仕組み

Cloudflareのエッジネットワークで発生したリクエスト・イベントは、ログセットごとに内部でバッファリングされ、Logpushジョブの設定に従って定期的にバッチとしてまとめられます。

• 各エッジロケーションで生成されたログは、まずCloudflare内部の集約基盤へ集められ、ゾーンまたはアカウント単位のログセットとして整理されます
• ジョブに設定されたフィールド選択・フィルタに従って不要な項目や対象外のイベントが除外され、残りがNDJSON形式に整形されます
• 整形されたログはgzip等で圧縮され、一定のバッチサイズまたは時間間隔ごとに配信先へHTTPS経由でプッシュされます
• 配信が失敗した場合は自動的に再試行され、それでも成功しない状態が続くとジョブの状態が異常として扱われます

設計パターン / ベストプラクティス

• 必要なフィールドだけを選択する: ログセットの全項目を送るのではなく、実際の分析・監査に使うフィールドだけに絞り、転送量とストレージコストを抑える
• フィルタで対象を絞る: 全リクエストではなく、エラーレスポンスやセキュリティイベントなど関心のある条件だけに絞ったジョブを別途用意すると、下流の処理が軽くなる
• 配信先を用途で分ける: 長期保管用のオブジェクトストレージと、リアルタイム分析用のSaaS基盤とでジョブを分け、それぞれに最適な保持期間・検索性を持たせる
• ログセットごとにジョブを分割: HTTPリクエストログとファイアウォールイベントなど、性質の異なるログは別ジョブにして管理・監視をシンプルに保つ
• オーナーシップチャレンジを事前に完了させる: 新しい配信先を追加する際は、検証手順を先に済ませておき、本番切り替え時の手戻りを防ぐ

運用・監視

• ジョブの状態確認: ダッシュボードやAPIでジョブが有効か、直近の配信が成功しているかを定期的に確認する
• 配信の遅延・失敗: 配信先側の受け入れ制限やネットワーク障害でエラーが続くと、ジョブが無効化されることがあるため、エラー通知や配信先のヘルスも合わせて監視する
• フィールド変更時の影響: フィールド選択やフィルタを変更すると下流の解析クエリやダッシュボードに影響するため、変更前に配信先側の受け皿を確認する
• データの整合性チェック: 配信先で受け取ったログの件数やタイムスタンプの連続性を定期的に確認し、欠損がないかを検証する

コスト

Logpushの利用可否や無料枠は契約プランによって異なり、大量ログの配信や長期利用では追加費用が発生する場合があります。転送量が直接コストに影響するため、不要なフィールドを送らないこと、フィルタで対象を絞ることが最適化の基本です。また配信先側（オブジェクトストレージの保管料やSaaS分析基盤の取り込み課金）でも別途コストが発生する点に注意します。

セキュリティ

• 配信先の検証を徹底する: オーナーシップチャレンジを経ていない宛先へは配信できない仕組みになっており、誤配信や第三者への漏洩リスクを抑えている
• アクセス権限の最小化: Logpushジョブの作成・変更権限は、APIトークンやロールで必要なメンバーにのみ付与する
• 機微情報の扱い: リクエストログにはクエリパラメータやヘッダーなど機微な情報が含まれうるため、配信するフィールドを吟味し、必要に応じて配信先側でのアクセス制御・暗号化を徹底する
• 配信経路の保護: 配信はHTTPS経由で行われるため、配信先エンドポイント側でも適切なTLS設定と認証を維持する

関連サービス・比較

LogpushはCloudflare内部で発生するログを外部へ継続配信する役割を担い、ダッシュボードでの簡易的な確認やAPI経由の都度取得（Logpull的な使い方）とは異なる位置づけです。AWSでは同様の役割をKinesis Data FirehoseやCloudWatch Logsのサブスクリプションが担います。

ハンズオン / CLI例

Logpushの設定はダッシュボードまたはCloudflare APIから行います。wranglerでAPIトークンの状態を確認したうえで、APIを直接呼び出す例を示します。

# wrangler経由でCloudflare APIトークンの有効性を確認
wrangler whoami

# 配信先のオーナーシップチャレンジを開始（例: R2バケットを配信先にする場合）
curl -X POST "https://api.cloudflare.com/client/v4/zones/${ZONE_ID}/logpush/ownership" \
  -H "Authorization: Bearer ${CF_API_TOKEN}" \
  -H "Content-Type: application/json" \
  --data '{
    "destination_conf": "r2://my-logs-bucket/logs?account-id=${ACCOUNT_ID}"
  }'

# チャレンジファイルの内容を使ってオーナーシップを検証
curl -X POST "https://api.cloudflare.com/client/v4/zones/${ZONE_ID}/logpush/ownership/validate" \
  -H "Authorization: Bearer ${CF_API_TOKEN}" \
  -H "Content-Type: application/json" \
  --data '{
    "destination_conf": "r2://my-logs-bucket/logs?account-id=${ACCOUNT_ID}",
    "ownership_challenge": "challenge-token-xxxx"
  }'

# Logpushジョブを作成（HTTPリクエストログを配信先へ送る）
curl -X POST "https://api.cloudflare.com/client/v4/zones/${ZONE_ID}/logpush/jobs" \
  -H "Authorization: Bearer ${CF_API_TOKEN}" \
  -H "Content-Type: application/json" \
  --data '{
    "name": "http-requests-to-r2",
    "dataset": "http_requests",
    "destination_conf": "r2://my-logs-bucket/logs?account-id=${ACCOUNT_ID}",
    "ownership_challenge": "challenge-token-xxxx",
    "enabled": true
  }'

# 作成済みジョブの一覧と状態を確認
curl -X GET "https://api.cloudflare.com/client/v4/zones/${ZONE_ID}/logpush/jobs" \
  -H "Authorization: Bearer ${CF_API_TOKEN}"