Query Builder

Query Builder は、構造化クエリを書いてテレメトリデータを調査・可視化するための機能です。Query Builder は Workers Observability データセットを検索します。現時点では、Workers Logs が保存するすべてのログが含まれます。

同じクエリは、Workers Observability REST API でもプログラムから実行できます。データセットのキー一覧、クエリの実行、キーの値一覧のエンドポイントがあります。

Query Builder は、Cloudflare ダッシュボードの Observability ページにあります。

Query Builder はすべての開発者が使え、有効化は不要です。クエリは Cloudflare が保存するすべての Workers Logs を検索します。まだ Workers Logs を有効にしていない場合は、Worker の Wrangler ファイル に次の設定を追加し、Worker を再デプロイします。

{
	"observability": {
		"enabled": true,
		"logs": {
			"invocation_logs": true,
			"head_sampling_rate": 1 // optional. default = 1.
		}
	}
}

[observability]
enabled = true

  [observability.logs]
  invocation_logs = true
  head_sampling_rate = 1

1. Cloudflare ダッシュボードで、Workers & Pages ページを開きます。

   Workers & Pages を開く ↗

2. Worker を選びます。

3. 左のナビゲーションで Observability を選び、Overview タブを開きます。

4. Visualization を選びます。

5. 任意: Filter、Group By、Order By、Limit にフィールドを追加します。詳細は クエリの構成 を参照してください。

6. 任意: 適切な時間範囲を選びます。

7. Run を選びます。変更のたびにクエリは自動で実行されます。

Query Builder は、次のような可視化演算子に対応しています。

1 つのクエリに複数の可視化を追加できます。可視化ごとにグラフが描画されます。生のクエリ結果を示すサマリーテーブルも 1 つ返されます。

どのメソッドも集約関数です。ほとんどのメソッドは、ログイベント内の特定フィールドに対して動きます。例外は Count で、フィルター条件に一致するログイベントの件数を返す集約関数です。

フィルターは、指定した条件に一致する列を返すために使います。フィルターはキー、演算子、値の 3 つで構成されます。

キーは、ログイベント内の任意のフィールドです。たとえば $workers.cpuTimeMs や $metadata.message を選べます。

演算子は、真偽を評価する論理条件です。対応する条件は次の表を参照してください。

数値フィールドの値は整数です。文字列フィールドの値は任意の文字列です。

フィルターを追加する手順は次のとおりです。

上記のフィルターでクエリを実行すると、$workers.cpuTimeMs > 100 のログイベントだけが返されます。

フィルターを複数追加すると AND で結合され、すべてのフィルターに一致するイベントだけが返されます。

検索は、指定したテキストを含むイベントだけを返すテキストフィルターです。手早く絞り込むときや、ログ内の一意な識別値を探すときに便利です。

Group By は、同じ値を持つ行をまとめてサマリー行にします。たとえば $workers.event.request.cf.country を Group By フィールドに追加すると、サマリーテーブルは国ごとにグループ化されます。

Order By は、サマリーテーブルの結果の並び順を決めます。asc を選ぶと昇順（小さい順）です。desc を選ぶと降順（大きい順）です。

Limit は、返す結果の件数を制限します。Order By と組み合わせると、上位または先頭の N 件を返せます。

時間範囲を選ぶと、一致するイベントを探す時間区間を指定します。保持期間は プランの種類 によって異なります。

クエリの表示は、Visualizations、Invocations、Events の 3 つです。

Visualizations タブは、クエリのグラフとサマリーテーブルを表示します。

Invocations タブは、すべてのログを invocation（呼び出し）ごとにグループ化し、タイムスタンプ順に表示します。クエリ条件に一致する invocation だけが返されます。

Events タブは、すべてのログをタイムスタンプ順に表示します。クエリ条件に一致するイベントだけが返されます。Events タブには、表示するフィールドを追加できます。

あとから調査で再利用しそうなクエリは、保存しておくことを推奨します。Save Query を選ぶと、名前、説明、カスタムタグ付きで保存できます。クエリはアカウント単位で保存され、アカウント内のすべてのユーザーが使えます。

保存したクエリは、Queries タブから該当クエリを選んで再実行できます。クエリを編集して、編集内容を保存することもできます。

クエリはユーザーごとにスターを付けられます。スター付きクエリはユーザー単位で、アカウント単位ではありません。

保存したクエリは Queries タブから削除できます。削除すると、アカウント内のすべてのユーザーからそのクエリが消えます。

1. Cloudflare ダッシュボードで、Observability ページを開きます。

   Observability を開く ↗

2. Queries タブを選びます。

3. 右側の三点メニューを選び、追加操作を開きます。

4. Delete Query を選び、画面の指示に従います。

保存したクエリには一意の URL が付き、アカウント内の任意のユーザーと共有できます。

この例では、5xx エラーを返すすべてのパスを見つけてデバッグするクエリを組み立てます。まずベースクエリを作ります。このベースクエリでは、生のイベント件数で可視化します。$workers.event.response.status が 500 より大きいフィルターを追加します。次に $workers.event.request.path と $workers.event.response.status でグループ化し、この挙動の影響を受けたリクエスト数を特定します。

結果を見ると、/agents/chat/default パスで 404 と 500 が起きています。このパスにフィルターをかけて調査できます。

次に Invocations タブを選んで調査します。このエラーの invocation が 2 件ログされていることがわかります。

1 件の invocation を展開して関連ログを表示し、デバッグを続けられます。