Workers Logs

Workers Logs は、Cloudflare Workers から出るログデータを自動で収集、保存、絞り込み、分析できます。データは Cloudflare アカウントに書き込まれ、各 Worker のダッシュボードで照会できます。新しく作った Worker は、デフォルトで observability 設定が有効です。

ログには 呼び出しログ、カスタムログ、エラー、捕捉されていない例外が含まれます。

サードパーティへログを送る場合は、OpenTelemetry export（推奨）、Workers Logpush、または Tail Workers を使います。

Worker が Workers Logs にログを書くには、observability 設定を追加する必要があります。Worker の Wrangler ファイルに次の設定を追加し、Worker を再デプロイします。

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

[observability]
enabled = true
head_sampling_rate = 1

ヘッドベースサンプリング で、ログを取る Workers リクエストの割合を設定できます。

Environments を使うと、同じ Worker アプリケーションを異なる設定でデプロイできます。たとえば、staging と production で別の head_sampling_rate を設定できます。staging という環境の observability を設定する手順です。1. [env.staging] の下に次の設定を追加します。

{
  "env": {
    "staging": {
      "observability": {
        "enabled": true,
        "head_sampling_rate": 1 // optional
      }
    }
  }
}

[env.staging.observability]
enabled = true
head_sampling_rate = 1

2. npx wrangler deploy -e staging で Worker をデプロイします
3. 各環境で手順 1 と 2 を繰り返します。

Cloudflare ダッシュボードから Worker のログにアクセスします。

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

   Workers & Pages を開く ↗

2. Overview で Worker を選びます。

3. Observability を選びます。

Workers Logs を最大限に使うには、JSON 形式でログを出すことを推奨します。Workers Logs はフィールドを自動抽出し、データベースへ適切にインデックスします。この構造化ログの利点は、カーディナリティに上限のないフィールドでも、任意の軸でデータを切り分けられることです。次のシナリオを考えます。

違いは、より速い照会のためにログをどうインデックスするかです。シナリオ 1 では user_id がメッセージ内に埋め込まれています。特定の user_id に関するログを探すには、テキスト一致が必要です。シナリオ 2 と 3 では、キー user_id と user_email でログを絞り込めます。

Workers の呼び出しごとに、Request、Response、関連メタデータなどを含む呼び出しログが 1 件返ります。この呼び出しログは、フィールド $cloudflare.$metadata.type = "cf-worker-event" で識別できます。各呼び出しログは、呼び出しの文脈で Cloudflare が使える情報で補完されます。

Workers Logs の UI では、ログはローカライズされたタイムスタンプとメッセージで表示されます。メッセージは呼び出しハンドラーによって決まります。たとえば Fetch リクエストはリクエストメソッドと URL を説明するメッセージになり、cron イベントは cron として並びます。呼び出しハンドラーと呼び出しメッセージの対応は次のとおりです。

呼び出しログは、wrangler で invocation_logs = false を追加すると無効にできます。

{
	"observability": {
		"logs": {
			"invocation_logs": false
		}
	}
}

[observability.logs]
invocation_logs = false

デフォルトでは、Worker はリクエスト、レスポンス、関連メタデータを含む 呼び出しログ を出します。

コードの任意の場所にカスタムログも追加できます。Worker 内の console.log は Workers Logs に表示されます。次の例は、Worker のリクエストハンドラー内のカスタム console.log です。

export default {
	async fetch(request) {
		const { cf } = request;
		const { city, country } = cf;

		console.log(`Request came from city: ${city} in country: ${country}`);

		return new Response("Hello worker!", {
			headers: { "content-type": "text/plain" },
		});
	},
};

addEventListener("fetch", (event) => {
	event.respondWith(handleRequest(event.request));
});

/**
 * Respond with hello worker text
 * @param {Request} request
 */
async function handleRequest(request) {
	const { cf } = request;
	const { city, country } = cf;

	console.log(`Request came from city: ${city} in country: ${country}`);

	return new Response("Hello worker!", {
		headers: { "content-type": "text/plain" },
	});
}

上記のコードをデプロイしたあと、ダッシュボード または リアルタイムログ で Worker のログを確認します。

ヘッドベースサンプリングでは、Cloudflare Worker への受信リクエストのうち、ログを取る割合を指定できます。特にトラフィックが多いアプリケーションでは、ログ量とコストを抑えつつ、アプリケーションの性能に関する有用な洞察を得られます。ヘッドベースサンプリング率を設定すると、ログを取るリクエストの割合を制御できます。そのリクエスト文脈内のログはすべて収集されます。

ヘッドベースサンプリングを有効にするには、observability 設定内で head_sampling_rate を設定します。有効範囲は 0 から 1 です。0 は 100 件中 0 件をログに取り、1 はすべてのリクエストをログに取ります。head_sampling_rate を省略すると、デフォルト値は 1（100%）です。次の例では head_sampling_rate を 0.01 にしており、100 件に 1 件のリクエストがログに残ります。

{
	"observability": {
		"enabled": true,
		"head_sampling_rate": 0.01 // 1% sampling rate
	}
}

[observability]
enabled = true
head_sampling_rate = 0.01

¹ アカウントあたり 1 日の上限は 50 億件です。上限を超えると、その日の残りは 1% のヘッドベースサンプリングが適用されます。

² 1 件のログの最大サイズは 256 KB です。これを超えるログは 切り詰められ、ログの $cloudflare.truncated フィールドが true になります。

Workers Logs は、Free プランと Paid プランの両方の Workers プラン に含まれます。

ある Worker が月に 1,500 万リクエストを処理します。各リクエストは呼び出しログ 1 件と console.log 1 件を出します。head_sampling_rate は 1 です。

ある Worker が月に 10 億リクエストを処理します。各リクエストは呼び出しログ 1 件と console.log 1 件を出します。head_sampling_rate は 0.1 です。