Monitoring API

Zaraz Monitoring API では、GraphQL Analytics API を通じて Zaraz イベントの詳細データを取得できます。この API で、イベント、ページビュー、トリガー、アクション、サーバーサイドリクエストのステータス（エラーと成功を含む）を監視できます。API で取得できるデータは、ダッシュボードの Zaraz Monitoring ページに表示される内容と同じです。ただし API ではプログラムから照会できるため、想定外の偏差に対するアラートや通知を作れます。

始めるには、API トークン認証ガイドに従って Analytics API トークンを生成します。

主要なエンティティ

Monitoring API には、それぞれ異なる洞察を提供する次の中核エンティティがあります。

zarazTrackAdaptiveGroups: Zaraz イベントに関するデータです。イベント数やタイムスタンプなどがあります。
zarazActionsAdaptiveGroups: Zaraz Actions に関する情報です。
zarazTriggersAdaptiveGroups: Zaraz Triggers に関するデータを追跡します。
zarazFetchAdaptiveGroups: サーバーサイドリクエストのデータです。Zaraz が行うサードパーティリクエストの URL と、返されたステータスコードを含みます。

GraphQL クエリの例

上のデータセットを使って任意のクエリを作れます。ここでは、使えるクエリの例を示します。

Zaraz イベントの件数を、時刻でグループ化して照会します。

query ZarazEvents(
	$zoneTag: string
	$limit: uint64!
	$start: Time
	$end: Time
	$orderBy: ZoneZarazTrackAdaptiveGroupsOrderBy!
) {
	viewer {
		zones(filter: { zoneTag: $zoneTag }) {
			data: zarazTrackAdaptiveGroups(
				limit: $limit
				filter: { datetimeHour_geq: $start, datetimeHour_leq: $end }
				orderBy: [$orderBy]
			) {
				count
				dimensions {
					ts: datetimeHour
				}
			}
		}
	}
}

Zaraz のロード件数を、時刻でグループ化して照会します。

query ZarazLoads(
	$zoneTag: string
	$limit: uint64!
	$start: Date
	$end: Date
	$orderBy: ZoneZarazTriggersAdaptiveGroupsOrderBy!
) {
	viewer {
		zones(filter: { zoneTag: $zoneTag }) {
			data: zarazTriggersAdaptiveGroups(
				limit: $limit
				filter: { date_geq: $start, date_leq: $end, triggerName: Pageview }
				orderBy: [$orderBy]
			) {
				count
				dimensions {
					ts: date
				}
			}
		}
	}
}

Zaraz が処理した各トリガーの合計実行回数を照会します。

query ZarazTriggers(
	$zoneTag: string
	$limit: uint64!
	$start: Date
	$end: Date
) {
	viewer {
		zones(filter: { zoneTag: $zoneTag }) {
			data: zarazTriggersAdaptiveGroups(
				limit: $limit
				filter: { date_geq: $start, date_leq: $end }
				orderBy: [count_DESC]
			) {
				count
				dimensions {
					name: triggerName
				}
			}
		}
	}
}

ステータス 400 のサーバーサイドレスポンスの件数を、時刻と URL でグループ化して照会します。

query ErroneousResponses(
	$zoneTag: string
	$limit: uint64!
	$start: Time
	$end: Time
	$orderBy: ZoneZarazFetchAdaptiveGroupsOrderBy!
) {
	viewer {
		zones(filter: { zoneTag: $zoneTag }) {
			data: zarazFetchAdaptiveGroups(
				limit: $limit
				filter: {
					datetimeHour_geq: $start
					datetimeHour_leq: $end
					url_neq: ""
					status: 400
				}
				orderBy: [$orderBy]
			) {
				count
				dimensions {
					ts: datetimeHour
					name: url
				}
			}
		}
	}
}

変数の例

{
	"zoneTag": "d6dfdf32c704a77ac227243a5eb5ca61",
	"start": "2025-01-01T00:00:00Z",
	"end": "2025-01-30T00:00:00Z",
	"limit": 10000,
	"orderBy": "datetimeHour_ASC"
}

zoneTag は自分のゾーンに合わせて変更し、開始日と終了日も目的の範囲に設定してください。

パラメーターの説明

zoneTag: Cloudflare ゾーンの一意の識別子です。
limit: 返す結果の最大件数です。
start と end: 照会する日付範囲を ISO 8601 形式で指定します。
orderBy: 並べ替え順です。日時の昇順または降順などです。

`curl` リクエストの例

この curl コマンドで、Zaraz が処理したイベント数を Zaraz Monitoring API に照会します。$TOKEN を API トークンに、$ZONE_TAG をゾーンタグに置き換え、開始日と終了日も必要に応じて調整します。

curl -X POST https://api.cloudflare.com/client/v4/graphql \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -d '{
    "query": "query AllEvents($zoneTag: String!, $limit: Int!, $start: Date, $end: Date, $orderBy: [ZoneZarazTriggersAdaptiveGroupsOrderBy!]) { viewer { zones(filter: { zoneTag: $zoneTag }) { data: zarazTrackAdaptiveGroups( limit: $limit filter: { datetimeHour_geq: $start datetimeHour_leq: $end } orderBy: [$orderBy] ) { count dimensions { ts: datetimeHour } } } } }",
    "variables": {
      "zoneTag": "$ZONE_TAG",
      "start": "2025-01-01T00:00:00Z",
      "end": "2025-01-30T00:00:00Z",
      "limit": 10000,
      "orderBy": "datetimeHour_ASC"
    }
  }'

`curl` の構成要素

Authorization: Authorization ヘッダーには Bearer トークンが必要です。$TOKEN を実際の API トークンに置き換えます。
Content-Type: JSON ペイロードであることを示すため、application/json を設定します。
データペイロード: GraphQL クエリと、zoneTag、start、end、limit、orderBy などの変数パラメーターを含みます。

この curl の例は、指定した日付範囲内のイベント数とタイムスタンプを含む JSON レスポンスを返します。ユースケースに合わせて variables の値を変更します。