ログエクスプローラー

ベータ

ログエクスプローラーを使用すると、Cloudflare ダッシュボードまたは API 内で直接 Cloudflare ログを保存および探索できます。これにより、ログを第三者に転送することなく、ログの可視性を提供します。ログは Cloudflare のグローバルネットワーク上に R2 オブジェクトストレージプラットフォームを使用して保存され、ダッシュボードまたは SQL API を介してクエリできます。

サポートされているデータセット

現在、ログエクスプローラーで利用可能なゾーンレベルのデータセットは次のとおりです。

HTTP リクエスト (FROM http_requests)
ファイアウォールイベント (FROM firewall_events)

認証

API と通信するには、適切な認証ヘッダーを設定する必要があります。

X-Auth-Email - ドメインに関連付けられた Cloudflare アカウントのメールアドレス
X-Auth-Key - Cloudflare API キー

また、アカウントおよびゾーンレベルのログ編集権限を持つ API トークンも認証に使用できます。

Authorization: Bearer <API_TOKEN>

ログエクスプローラーを有効にする

ダッシュボードまたは API を使用して、ログエクスプローラーでクエリしたいデータセットを有効にできます。

ダッシュボード
API

Cloudflare ダッシュボード ↗にログインし、アカウントとドメインを選択します。
分析 & ログ > ログエクスプローラーに移動します。
データセットを有効にするを選択して、クエリしたいデータセットを選択します。後でさらにデータセットを有効にすることができます。

ログエクスプローラー API を使用して、保存したい各データセットのログエクスプローラーを有効にします。ログストリームが有効になった後、ログを表示できるようになるまで最大 30 分かかる場合があります。

次の curl コマンドは、http_requests を有効にするための例と、コマンドが成功したときの期待される応答です。

curl https://api.cloudflare.com/client/v4/zones/{zone_id}/logs/explorer/datasets \
  --header 'Authorization: Bearer <API_TOKEN>' \
  --header 'Content-Type: application/json' \
  --data '{
  "dataset": "http_requests"
}'

{
  "result": {
    "id": 1,
    "dataset": "http_requests",
    "created_at": "2023-09-25T22:12:31Z",
    "updated_at": "2023-09-25T22:12:31Z"
  },
  "success": true,
  "errors": [],
  "messages": []
}

ログエクスプローラーの使用

ログのフィルタリングと表示は、Cloudflare ダッシュボードまたはクエリ API を介して利用できます。

ダッシュボード
API

Cloudflare ダッシュボード ↗にログインし、アカウントとドメインを選択します。
分析 & ログ > ログエクスプローラーに移動します。
ドロップダウンから使用するデータセットを選択します。
制限を選択します。これは返される最大結果数で、たとえば 50 です。
クエリしたい時間範囲を選択します。たとえば、過去 12 時間です。
フィルターを追加を選択してクエリを作成します。フィールド、演算子、および値を選択します。
クエリのプレビューが表示されます。変更したい場合はカスタム SQL を使用を選択します。
完了したらクエリを実行を選択します。結果はクエリ結果セクションに表示されます。

ログエクスプローラーは、Cloudflare のネットワークで生成されたログをクエリするために、馴染みのある SQL 構文を使用するクエリエンドポイントを公開します。

たとえば、特定の Ray ID を持つ HTTP リクエストを見つけるには、次の SQL クエリを実行できます。

curl https://api.cloudflare.com/client/v4/zones/{zone_id}/logs/explorer/query/sql \
  --header "Authorization: Bearer <API_TOKEN>" \
  --url-query query="SELECT clientRequestScheme, clientRequestHost, clientRequestMethod, edgeResponseStatus, clientRequestUserAgent FROM http_requests WHERE RayID = '806c30a3cec56817' LIMIT 1"

次の HTTP リクエストの詳細が返されます。

{
  "result": [
    {
      "clientrequestscheme": "https",
      "clientrequesthost": "example.com",
      "clientrequestmethod": "GET",
      "clientrequestuseragent": "curl/7.88.1",
      "edgeresponsestatus": 200
    }
  ],
  "success": true,
  "errors": [],
  "messages": []
}

出力形式

ログエクスプローラーの出力は、JSON 以外のさまざまな形式で表示できます。JSON Lines（NDJSON とも呼ばれる）、CSV、プレーンテキストです。プレーンテキストは、psql の aligned 出力モードに似た ASCII テーブルを使用します。クライアント側で形式を変換する必要がない利便性に加えて、JSON Lines、CSV、およびプレーンテキスト形式は、API からストリーミングされる利点があります。したがって、大きな結果セットの場合、早く応答を得ることができます。

出力形式は、HTTP Accept ヘッダーを使用して選択できます。以下の表に示します。

出力形式	コンテンツタイプ	ストリーミング?
JSON	`application/json`	いいえ
JSON Lines	`application/x-ndjson`	はい
CSV	`text/csv`	はい
プレーンテキスト	`text/plain`	はい

クエリの最適化

ログエクスプローラーでサポートされているすべてのテーブルには、クエリに応じてスキャンされるデータ量を絞り込むのに役立つ特別な列 date が含まれています。これにより、クエリ応答時間が短縮されます。date の値は YYYY-MM-DD の形式である必要があります。たとえば、2023 年 10 月 12 日に発生したログをクエリするには、WHERE 句に次のように追加します：date = '2023-10-12'。この列は、<、>、および = の標準演算子をサポートしています。

curl https://api.cloudflare.com/client/v4/zones/{zone_id}/logs/explorer/query/sql \
  --header 'Authorization: Bearer <API_TOKEN>' \
  --url-query query="SELECT clientRequestMethod, clientRequestPath, clientRequestProtocol FROM http_requests WHERE date = '2023-10-12' LIMIT 500"

追加のクエリ最適化のヒント

クエリの時間範囲を絞り込む。データ処理量を減らすために、より小さな時間ウィンドウに焦点を当てます。これにより、過剰なデータのクエリを避け、応答時間を短縮できます。
ORDER BY および LIMIT 句を省略する。これらの句は、特に大規模なデータセットを扱う場合、クエリを遅くする可能性があります。大量のレコードを返すクエリの場合、広い時間範囲から最新の N レコードに制限するのではなく、時間範囲を短縮します。
必要な列のみを選択する。たとえば、SELECT * を特定の列のリストに置き換えます。また、最初のイテレーションとして SELECT RayId を使用し、その後 Ray ID でフィルタリングして追加の列を取得するクエリを続けることができます。さらに、SELECT COUNT(*) を使用して、完全なデータセットを取得せずに一致するレコードのある時間範囲を調べることができます。

サポートされている SQL クエリ

これらは、ログエクスプローラーでサポートされている SQL クエリ句です。

SELECT

SELECT 句は、データベーステーブルから取得したい列を指定します。個々の列名、式、またはすべての列を選択するためのワイルドカード文字を含めることができます。

FROM

FROM 句は、データを取得するテーブルを指定します。SELECT ステートメントのデータのソースを示します。

WHERE

WHERE 句は、指定された条件に基づいてクエリによって返される行をフィルタリングします。行が結果セットに含まれるために満たす必要がある条件を指定できます。

GROUP BY

GROUP BY 句は、同じ値を持つ行を要約行にグループ化するために使用されます。

HAVING

HAVING 句は WHERE 句に似ていますが、GROUP BY 句と特に使用されます。GROUP BY 操作が実行された後に、指定された条件に基づいて行のグループをフィルタリングします。

ORDER BY

ORDER BY 句は、結果セットを 1 つ以上の列で昇順または降順にソートするために使用されます。

LIMIT

LIMIT 句は、クエリによって返される行の数を制約するために使用されます。通常、ORDER BY 句と組み合わせて使用され、上位 N 行を取得したり、ページネーションを実装したりします。

よくある質問

クエリ可能なフィールド（または列）は何ですか？

データセットログフィールドにリストされているすべてのフィールドは、ログエクスプローラーで表示できます。フィルタリングには、bool、int、float、または string 型のような単純な値を持つフィールドのみがサポートされています。キーと値のペアを持つフィールドは現在サポートされていません。たとえば、HTTP リクエストデータセットの RequestHeaders および Cookies フィールドをフィルターとして使用することはできません。

なぜ私のクエリが完了しないのか、またはタイムアウトするのか？

ログエクスプローラーは、クエリパラメータが狭い時間範囲に焦点を当てるときに最も効果的です。クエリが大量のデータを返す場合、クエリタイムアウトが発生する可能性があります。パフォーマンスを向上させるために、クエリを洗練させることを検討してください。

HTTP ステータス 524（ゲートウェイタイムアウト）でクエリがタイムアウトした場合は、application/x-ndjson のようなストリーミング出力形式のいずれかを使用することを検討してください。

私のクエリがエラーを返しました。何が間違っているのかをどうやって確認できますか？

エラーコードの改善に取り組んでいます。一般的なエラーが発生した場合は、SQL 構文（カスタム SQL 機能を使用している場合）を確認し、日付と制限を含めていること、フィルタリングしているフィールドがキーと値のペアでないことを確認してください。それでもクエリが失敗する場合は、タイムアウトしている可能性があります。フィルターを洗練させることを試みてください。

データはどこに保存されていますか？

データは Cloudflare R2 に保存されています。各ログエクスプローラーのデータセットは、Cloudflare D1 と同様に、顧客ごとに保存され、他の顧客のデータとは分離されています。将来的には、このシングルテナントストレージモデルにより、独自の保持ポリシーを作成し、データを保存する地域を選択する柔軟性が提供されます。

ログエクスプローラーは顧客メタデータ境界をサポートしていますか？

顧客メタデータ境界は、現在ログエクスプローラーではサポートされていません。

Cloudflare Dashboard Discord Community Learning Center Support Portal

Cookie Settings