使用 Cloudflare Worker telemetry 傳送並驗證事件
在受控應用程式邊界使用 Cloudflare Worker telemetry,保持事件契約較小,並在建置聚合檢視之前驗證已知結果。
- 1
選擇結果
邊緣API監控
- 2
定義合約
worker_name、route_template、方法、status_code、顏色和 trigger_type
- 3
在結果處發出
將已處理錯誤且設有逾時的傳送 Promise 傳給實際請求的 ctx.waitUntil。這是盡力而為的背景傳送,不保證持久儲存,也不自動重試。
- 4
核實證據
Exercise a known fixture, then inspect edge_request_completed for one correctly typed terminal row.
開始之前
開始之前
- Telemetry API 金鑰的 Worker 秘密繫結
- ExecutionContext 可用於顯式管理的後台交付
- Cloudflare 請求後設資料的規範化路由名稱和允許列表
交貨設定
安裝並初始化伺服器端
此 Worker 範例透過秘密綁定中的 env.TELEMETRY_API_KEY 直接呼叫 Log API,無需 npm SDK 或 process.env 設定。 將攝取憑據保留在瀏覽器包、客戶端可見的環境變數、原始碼控制、日誌和異常訊息之外。
- 1準備一個具有有限網路行為的可重用伺服器端交付客戶端。
- 2在成功、失敗、重試或超時邊界處新增結果事件。
- 3在啟用警示之前傳送受控裝置並檢查儲存的行。
片段
從一個結構化事件開始
在工作流程完成、失敗或重試的位置新增此形狀。然後從真實的欄位建置儀表板。
Cloudflare Worker telemetry事件
// 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 Worker telemetry 驗證查詢
SELECT *
FROM edge_request_completed
ORDER BY timestamp_utc DESC
LIMIT 20;實施參考
在啟用新的生產路徑之前,請檢查事件合約、資料安全指南和上游主要文件。
在哪裡記錄事件
保持結果事件小且可恢復
該模式提供了
- 除了上游工作流程之外,還有一個有界的、SQL 就緒的結果。
- 用於儀表板、警示和跨事件關聯的穩定欄位。
- 用於驗證成功、失敗、重試和超時行為的夾具驅動路徑。
該模式不提供
- OTLP 匯出器、自動收集管道或詳細追蹤和診斷日誌的替代品。
- 僅因為有效負載包含事件 ID,所以僅傳送一次。
- 收集原始提供商有效負載、使用者內容、憑證或受監管資料的權限。
事件結構描述範例
此工作流程的事件結構描述
在將查詢或程式碼片段適應生產之前,請檢查行粒度、發出邊界、所需型別、隱私類、範例有效負載和驗證清單。
相關產品功能
繼續此工作流程 警示
將經過審查的可靠性查詢提升到擁有的閾值和回應工作流程中。
相關 SQL 查詢範例
更多 SQL 範例
針對此工作流程中的結構化欄位執行查詢,檢查範例結果,並將有用的答案轉換為儀表板或警示。
按路由計算 API 請求吞吐量
哪些 API 路由每分鐘處理的請求最多?
開啟查詢範例測量 API 429 速率限制恢復
收到 HTTP 429 的請求重試後能否成功恢復?
開啟查詢範例按路由計算API錯誤率
在至少有 20 次請求的 API 路由中,哪些路由的 5xx 錯誤率最高?
開啟查詢範例計算 p50、p95 和 p99 API 延遲
哪些端點的尾部延遲最差?
開啟查詢範例計算 API 錯誤預算消耗率
API 消耗其 99.9% 可用性預算的速度有多快?
開啟查詢範例檢測丟失的服務心跳
哪些預期遙測源已停止傳送心跳?
開啟查詢範例按路線和版本比較核心網路生命力
哪個路線和版本的前端效能最弱?
開啟查詢範例按實施系列瀏覽
比較相關整合模式
與此整合配對的範本
更多整合