本文へ移動
統合ガイド

Cloudflare 労働者 Telemetry

Cloudflare ワーカーからのエッジ リクエスト ステータス、遅延、プロバイダーの障害、cron 実行、およびキュー ワーカーをログに記録します。

レビュー者 Telemetry 製品チーム に . 送信するイベント、除外するデータ、コードの追加方法を確認しました. このページのレビュー担当

役に立つ
  • エッジ API 監視
  • Cron の可観測性
  • キューのデバッグ
実装の証拠

Cloudflare Worker telemetry でイベントを送信して確認する

制御されたアプリケーション境界で Cloudflare Worker telemetry を使用し、イベント コントラクトを小さく保ち、集約ビューを構築する前に既知の結果を検証します。

  1. 1

    結果を選択してください

    エッジ API 監視

  2. 2

    契約を定義する

    worker_name、route_template、メソッド、status_code、コロ、および trigger_type

  3. 3

    結果で発行する

    エラー処理とタイムアウトを備えた送信 Promise を、実際のリクエストの ctx.waitUntil に渡してください。これはベストエフォートのバックグラウンド送信であり、永続保存や自動再試行ではありません。

  4. 4

    証拠を検証する

    Exercise a known fixture, then inspect edge_request_completed for one correctly typed terminal row.

始める前に

始める前に

  • Telemetry API キーのワーカー シークレット バインディング
  • 明示的に管理されたバックグラウンド配信に ExecutionContext が利用可能
  • 正規化されたルート名と Cloudflare リクエスト メタデータのホワイトリスト

配信設定

サーバー側のインストールと初期化

この Worker の例はシークレットバインディングの env.TELEMETRY_API_KEY で Log API を直接呼び出します。npm SDK や process.env の設定は不要です。 ブラウザ バンドル、クライアントに表示される環境変数、ソース管理、ログ、および例外メッセージに取り込み資格情報が含まれないようにします。

  1. 1制限されたネットワーク動作を持つ再利用可能なサーバー側配信クライアントを 1 つ準備します。
  2. 2成功、失敗、再試行、またはタイムアウトの境界に結果イベントを追加します。
  3. 3アラートを有効にする前に、制御されたフィクスチャを送信し、保存されている行を検査します。

スニペット

1 つの構造化されたイベントから始める

ワークフローが完了、失敗、または再試行される場所にこの図形を追加します。次に、実際のフィールドからダッシュボードを構築します。

cloudflare-workers

Cloudflare Worker telemetryイベント

javascript
// Wrap your existing /api/events handler; do not replace its business logic.
export default {
  async fetch(request, env, ctx) {
    const started = performance.now();
    const response = await handleEvents(request, env, ctx);
    try {
      ctx.waitUntil(deliverEdgeEvent(env, {
        worker_name: "events-api",
        route_template: "/api/events",
        method: request.method,
        status_code: response.status,
        colo: request.cf?.colo,
        latency_ms: performance.now() - started,
        latency_scope: "response_ready",
        status: response.status >= 400 ? "error" : "success",
        release: env.APP_RELEASE,
      }));
    } catch {
      // Scheduling or metadata failures must not replace the response.
    }
    return response;
  },
};

async function deliverEdgeEvent(env, data) {
  let timer;
  try {
    if (!env.TELEMETRY_API_KEY) return;
    const controller = new AbortController();
    timer = setTimeout(() => controller.abort(), 3000);
    const response = await fetch("https://api.telemetry.sh/log", {
      method: "POST",
      headers: {
        Authorization: env.TELEMETRY_API_KEY,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({ table: "edge_request_completed", data }),
      signal: controller.signal,
    });
    if (!response.ok || (await response.json()).status !== "success") {
      throw new Error("delivery_unconfirmed");
    }
  } catch {
    try { console.warn("Telemetry delivery unconfirmed"); } catch {}
  } finally {
    clearTimeout(timer);
  }
}

イベントスキーマ

worker_name、route_template、メソッド、status_code、コロ、および trigger_type

ステータス、latency_ms、利用可能な場合は cpu_time_ms、および error_type

request_id、queue_name、試行、リリース、および環境

設定を確認する

チェックポイント 1

エラー処理とタイムアウトを備えた送信 Promise を、実際のリクエストの ctx.waitUntil に渡してください。これはベストエフォートのバックグラウンド送信であり、永続保存や自動再試行ではありません。

チェックポイント 2

生の URL ではなくルート テンプレートを記録し、Cookie、認証ヘッダー、リクエスト本文、クライアント IP アドレス、または無制限の cf プロパティをログに記録しません。

チェックポイント 3

handleEvents を既存の /api/events ハンドラーに置き換えてください。この例は返されたレスポンスのステータスと準備完了までの時間を記録し、ストリーム本文の送信完了は測定しません。アプリが投げたエラーはそのまま伝播します。未捕捉の実行時エラーには Workers Logs を使い続けてください。

検証

イベントが到着したことを証明する

既知の成功例と失敗例を実行した後、これを実行します。最終的なイベント コントラクトがスニペットと異なる場合は、フォールバック テーブル名を置き換えます。

cloudflare-workers-検証

Cloudflare Worker telemetry 検証クエリ

sql
SELECT *
FROM edge_request_completed
ORDER BY timestamp_utc DESC
LIMIT 20;
論理結果ごとに 1 つのターミナル行を、予想されるステータス、識別子、単位、および UTC 時刻とともに確認します。
推論されたスキーマを検査し、再試行によってフィールド タイプが変更されたり、新しい論理イベント ID が生成されたりしないことを確認します。
保存されたフィールドで認証情報、生のペイロード、プロンプト、プライベート コンテンツ、および無制限のエラー メッセージを検索します。
ダッシュボードを完了として扱う前に、プロバイダーのタイムアウト、取り込みの拒否、およびプロセスのシャットダウンを実行します。

実装の参考資料

新しい運用パスを有効にする前に、イベント契約、データ安全性に関するガイダンス、上流の主要ドキュメントを確認してください。

イベントを記録する場所

結果イベントを小さく、回復可能なものに保つ

このパターンが提供するのは、

  • 上流のワークフローの横にある、制限付きの SQL 対応の結果。
  • ダッシュボード、アラート、およびイベント間の相関関係の安定したフィールド。
  • 成功、失敗、再試行、タイムアウトの動作を検証するためのフィクスチャ駆動のパス。

このパターンでは提供されません

  • OTLP エクスポーター、自動収集パイプライン、または詳細なトレースと診断ログの代替。
  • ペイロードにイベント ID が含まれているという理由だけで、1 回だけ配信されます。
  • 生のプロバイダー ペイロード、ユーザー コンテンツ、資格情報、または規制されたデータを収集する許可。

イベントスキーマの例

クエリまたはスニペットを運用環境に適用する前に、行粒度、出力境界、必要なタイプ、プライバシー クラス、サンプル ペイロード、および検証チェックリストを確認してください。

関連製品の機能

このワークフローを続行します アラート

レビューされた信頼性クエリを、所有するしきい値と応答のワークフローにプロモートします。

関連する SQL レシピ

その他のSQL例

このワークフローの構造化フィールドに対してクエリを実行し、結果の例を検査して、有用な回答をダッシュボードまたはアラートに変換します。

すべてのレシピを参照する

実装ファミリーごとに参照する

関連する統合パターンを比較する

この統合と組み合わせるテンプレート

さらなる統合