Analytics Engine に書き込む

Workers Analytics Engine は、大規模な時系列分析を提供します。カスタム指標の追跡、利用量ベースの課金、顧客ごとのサービス健全性の把握に使えます。

ログと異なり、Analytics Engine は高カーディナリティデータに対する集計クエリ向けです。書き込みはノンブロッキングで、リクエストのレイテンシには影響しません。

バインディングを設定する

Wrangler 設定ファイルに Analytics Engine のデータセットバインディングを追加します。データセットは、最初に書き込んだときに自動作成されます。

{
	"analytics_engine_datasets": [
		{
			"binding": "ANALYTICS",
			"dataset": "my_dataset",
		},
	],
}

[[analytics_engine_datasets]]
binding = "ANALYTICS"
dataset = "my_dataset"

データポイントを書き込む

export default {
	async fetch(request, env) {
		const url = new URL(request.url);

		// Write a page view event
		env.ANALYTICS.writeDataPoint({
			blobs: [
				url.pathname,
				request.headers.get("cf-connecting-country") ?? "unknown",
			],
			doubles: [1], // Count
			indexes: [url.hostname], // Sampling key
		});

		// Write a response timing event
		const start = Date.now();
		const response = await fetch(request);
		const duration = Date.now() - start;

		env.ANALYTICS.writeDataPoint({
			blobs: [url.pathname, response.status.toString()],
			doubles: [duration],
			indexes: [url.hostname],
		});

		// Writes are non-blocking - no need to await or use waitUntil()
		return response;
	},
};

interface Env {
	ANALYTICS: AnalyticsEngineDataset;
}

export default {
	async fetch(request: Request, env: Env): Promise<Response> {
		const url = new URL(request.url);

		// Write a page view event
		env.ANALYTICS.writeDataPoint({
			blobs: [
				url.pathname,
				request.headers.get("cf-connecting-country") ?? "unknown",
			],
			doubles: [1], // Count
			indexes: [url.hostname], // Sampling key
		});

		// Write a response timing event
		const start = Date.now();
		const response = await fetch(request);
		const duration = Date.now() - start;

		env.ANALYTICS.writeDataPoint({
			blobs: [url.pathname, response.status.toString()],
			doubles: [duration],
			indexes: [url.hostname],
		});

		// Writes are non-blocking - no need to await or use waitUntil()
		return response;
	},
};

データポイントの構造

各データポイントは、次の要素で構成されます。

blobs（文字列） - グループ化とフィルター用のディメンションです。パス、リージョン、ステータスコード、顧客 ID などに使います。
doubles（数値） - 記録する数値です。カウント、所要時間、サイズなどです。
indexes（文字列） - サンプリングキーとして使う 1 つの文字列です。関連イベントを同じインデックスにまとめます。

データをクエリする

SQL API でデータをクエリします。

curl "https://api.cloudflare.com/client/v4/accounts/$CLOUDFLARE_ACCOUNT_ID/analytics_engine/sql" \
  --header "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
  --data "SELECT blob1 AS path, SUM(_sample_interval) AS views FROM my_dataset WHERE timestamp > NOW() - INTERVAL '1' HOUR GROUP BY path ORDER BY views DESC LIMIT 10"