Cloudflare Observability 全指南Workers Logs、Traces、Analytics Engine 与 Logpush 实战手册【免费下载链接】skillsSkills Catalog for Codex项目地址: https://gitcode.com/GitHub_Trending/skills4/skills本篇技术指南以skills/.curated/cloudflare-deploy仓库中 observability 参考文档 为核心骨架系统讲解在 Cloudflare Workers 上落地可观测性的完整方案覆盖 Workers Logs、Workers Traces、Analytics Engine、Tail Workers、Logpush 五类能力并配套 GraphQL/SQL 查询 API、配置样例与常见陷阱。读完本文你将掌握如何在wrangler.jsonc中开启观测、如何用console结构化打日志、如何用 Analytics Engine 做高基数事件存储与 SQL 聚合、如何用 Tail Worker 做日志过滤与外部导出以及如何规避采样率、字段上限、时间精度等关键坑点。一、产品总览Cloudflare 可观测性五件套该 skill 参考明确限定范围为Cloudflare Observability 功能本身Workers Logs、Traces、Analytics Engine、Logpush、Metrics Analytics以及 OpenTelemetry 导出。五个核心产品各自承担不同职责Workers Logs是什么Worker 的console.log/warn/error输出。访问方式DashboardReal-time Logs、Logpush、Tail Workers。成本免费随所有 Workers 自带。保留策略仅实时查看Dashboard 不做历史存储历史留存需依赖 Logpush 或 Tail Worker 转储。Workers Traces是什么包含时序、CPU 用量、执行结果的执行追踪execution traces。访问方式DashboardWorkers Analytics → Traces、Logpush。成本GA 定价自2026 年 3 月 1 日起为 $0.10/1M spans每月免费 10M spans。保留策略默认包含 14 天留存。Analytics Engine是什么面向高基数high-cardinality事件存储与 SQL 查询的时序分析数据库可支持数百万级唯一维度值如海量用户 ID、API Key而不产生性能劣化非常适合自定义用户分析面板、用量计费、按客户/按功能监控。访问方式SQL API、DashboardAnalytics → Analytics Engine。成本每月免费 10M 写入超出后 $0.25/1M writes。保留策略默认 90 天可配置延长至 1 年。Tail Workers是什么接收其他 Worker 日志与 traces 的专用 Worker在生产者 Worker 执行完成后被自动调用可捕获完整请求生命周期含 Service Bindings 与 Dynamic Dispatch 子请求。按 CPU 时间计费而非请求数适用于 Workers Paid 与 Enterprise 套餐。用途日志过滤、转换、外部导出、实时事件流处理。成本标准 Workers 定价。Logpush是什么将日志流式导出到外部存储S3、R2、GCS、Azure、Datadog 等。访问方式Dashboard、API。成本需要 Business/Enterprise 套餐。二、定价速查2026功能免费额度超出免费额度后套餐要求Workers Logs无限免费任意套餐Workers Traces10M spans/月$0.10/1M spansPaid WorkersGA2026-03-01Analytics Engine10M writes/月$0.25/1M writesPaid WorkersLogpush无已包含在套餐内Business/Enterprise补充说明来自 gotchas.mdWorkers Traces 在 2026 年 3 月 1 日 GA 之前的 Beta 使用免费Logpush 使用量包含在 Business/Enterprise 套餐中。三、如何使用这套参考决策树与阅读顺序在 Agent / LLM 场景下直接加载全部参考文件成本较高因此该模块提供决策树用于路由├─ How do I enable/configure X? → configuration.md ├─ Whats the API/method/binding for X? → api.md ├─ How do I implement X pattern? → patterns.md │ ├─ Usage tracking/billing → patterns.md │ ├─ Error tracking → patterns.md │ ├─ Performance monitoring → patterns.md │ ├─ Multi-tenant tracking → patterns.md │ ├─ Tail Worker filtering → patterns.md │ └─ OpenTelemetry export → patterns.md └─ Why isnt X working? / Limits? → gotchas.md不同任务类型的推荐阅读顺序任务类型加载顺序理由初始配置configuration.md → gotchas.md先配置避免踩坑实现功能patterns.md → api.md → gotchas.md模式 → API 细节 → 边界情况排查问题gotchas.md → configuration.md先看常见问题查询数据api.md → patterns.mdAPI 语法 → 查询示例四、配置实战从日志到 Logpush本节内容完整继承自 configuration.md并补充实现说明。1. 开启 Workers Logs在wrangler.jsonc中启用观测并控制头部采样率{ observability: { enabled: true, head_sampling_rate: 1 // 100% sampling (default) } }最佳实践使用结构化 JSON 日志便于后续索引与过滤// Good - structured logging console.log({ user_id: 123, action: login, status: success, duration_ms: 45 }); // Avoid - unstructured string console.log(user_id: 123 logged in successfully in 45ms);2. 开启 Workers Traces{ observability: { traces: { enabled: true, head_sampling_rate: 0.05 // 5% sampling } } }默认采样率为 100%对于高流量 Worker建议降低到 0.01–0.1 区间以控制成本与存储。3. 配置 Analytics Engine先在wrangler.toml中绑定数据集# wrangler.toml analytics_engine_datasets [ { binding ANALYTICS, dataset api_metrics } ]然后在 Worker 中写入数据点fire-and-forget无需 awaitexport interface Env { ANALYTICS: AnalyticsEngineDataset; } export default { async fetch(request: Request, env: Env): PromiseResponse { // Track metrics env.ANALYTICS.writeDataPoint({ blobs: [customer_123, POST, /api/v1/users], doubles: [1, 245.5], // request_count, response_time_ms indexes: [customer_123] // for efficient filtering }); return new Response(OK); } }关于数据点三要素详见 analytics-engine READMEBlobs字符串维度最多 20 个如 endpoint、method、status、user_idDoubles数值最多 20 个如 latency_ms、request_count、bytesIndexes用于高效过滤的索引字符串最多 20 个如 customer_id、api_key。4. 配置 Tail WorkersTail Worker 接收其他 Worker 的日志与 traces用于过滤、转换或导出。Setup生产者侧# wrangler.toml name log-processor main src/tail.ts [[tail_consumers]] service my-worker # Worker to tailTail Worker 示例仅过滤异常并上报外部监控export default { async tail(events: TraceItem[], env: Env, ctx: ExecutionContext) { // Filter errors only const errors events.filter(event event.outcome exception || event.outcome exceededCpu ); if (errors.length 0) { // Send to external monitoring ctx.waitUntil( fetch(https://monitoring.example.com/errors, { method: POST, body: JSON.stringify(errors) }) ); } } }outcome的合法取值在 api.md 的TraceEvent类型中定义ok | exception | exceededCpu | exceededMemory | unknown。决策提示来自 tail-workers README如果只是把日志/追踪批量导出到 Sentry、Grafana、Honeycomb 等已知工具应优先考虑OpenTelemetry 导出批量发送更高效、内置集成多、开销更低Tail Worker 仅适合需要自定义实时处理的场景如聚合指标Tail Worker Analytics Engine、错误追踪Tail Worker 外部服务、自定义日志/调试Tail Worker KV/HTTP 端点、复杂事件处理Tail Worker Durable Objects。5. 配置 Logpush将日志发送到外部存储S3、R2、GCS、Azure、Datadog 等需要 Business/Enterprise 套餐。Dashboard 方式进入 Analytics → Logs → Logpush选择目标类型提供凭据与 bucket/endpoint选择数据集如 Workers Trace Events配置过滤条件与字段。API 方式curl -X POST https://api.cloudflare.com/client/v4/accounts/{account_id}/logpush/jobs \ -H Authorization: Bearer API_TOKEN \ -H Content-Type: application/json \ -d { name: workers-logs-to-s3, destination_conf: s3://my-bucket/logs?regionus-east-1, dataset: workers_trace_events, enabled: true, frequency: high, filter: {\where\:{\and\:[{\key\:\ScriptName\,\operator\:\eq\,\value\:\my-worker\}]}} }6. 环境差异化配置开发环境verbose 日志、全量采样// wrangler.dev.jsonc { observability: { enabled: true, head_sampling_rate: 1.0, traces: { enabled: true } } }生产环境降低采样、结构化日志// wrangler.prod.jsonc { observability: { enabled: true, head_sampling_rate: 0.1, // 10% sampling traces: { enabled: true } } }按环境部署wrangler deploy --config wrangler.prod.jsonc --env production五、API 参考GraphQL、SQL 与绑定类型1. GraphQL Analytics API端点https://api.cloudflare.com/client/v4/graphql查询 Workers 指标请求数、错误数、子请求数、CPU/墙钟时间分位数query { viewer { accounts(filter: { accountTag: $accountId }) { workersInvocationsAdaptive( limit: 100 filter: { datetime_geq: 2025-01-01T00:00:00Z datetime_leq: 2025-01-31T23:59:59Z scriptName: my-worker } ) { sum { requests errors subrequests } quantiles { cpuTimeP50 cpuTimeP99 wallTimeP50 wallTimeP99 } } } } }2. Analytics Engine SQL API端点https://api.cloudflare.com/client/v4/accounts/{account_id}/analytics_engine/sql认证Authorization: Bearer API_TOKEN需要 Account Analytics Read 权限常用查询-- List all datasets SHOW TABLES; -- Time-series aggregation (5-minute buckets) SELECT intDiv(toUInt32(timestamp), 300) * 300 AS time_bucket, blob1 AS endpoint, SUM(_sample_interval) AS total_requests, AVG(double1) AS avg_response_time_ms FROM api_metrics WHERE timestamp NOW() - INTERVAL 24 HOUR GROUP BY time_bucket, endpoint ORDER BY time_bucket DESC; -- Top customers by usage SELECT index1 AS customer_id, SUM(_sample_interval * double1) AS total_api_calls, AVG(double2) AS avg_response_time_ms FROM api_usage WHERE timestamp NOW() - INTERVAL 7 DAY GROUP BY customer_id ORDER BY total_api_calls DESC LIMIT 100; -- Error rate analysis SELECT blob1 AS error_type, COUNT(*) AS occurrences, MAX(timestamp) AS last_seen FROM error_tracking WHERE timestamp NOW() - INTERVAL 1 HOUR GROUP BY error_type ORDER BY occurrences DESC;3. Console Logging API所有 console 方法都会进入 Workers Logs// Standard methods (all appear in Workers Logs) console.log(info message); console.info(info message); console.warn(warning message); console.error(error message); console.debug(debug message); // Structured logging (recommended) console.log({ level: info, user_id: 123, action: checkout, amount: 99.99, currency: USD });不同日志级别通过结构化字段区分例如console.log({ level: error, message: Payment failed, error_code: CARD_DECLINED });4. Analytics Engine 绑定类型与字段上限interface AnalyticsEngineDataset { writeDataPoint(event: AnalyticsEngineDataPoint): void; } interface AnalyticsEngineDataPoint { // Indexed strings (use for filtering/grouping) indexes?: string[]; // Non-indexed strings (metadata, IDs, URLs) blobs?: string[]; // Numeric values (counts, durations, amounts) doubles?: number[]; }字段限制硬性上限超出会被丢弃或拒绝最多 20 个 indexes最多 20 个 blobs最多 20 个 doubles每请求最多 25 次writeDataPoint调用5. Tail Consumer 事件类型interface TraceItem { event: TraceEvent; logs: TraceLog[]; exceptions: TraceException[]; scriptName?: string; } interface TraceEvent { outcome: ok | exception | exceededCpu | exceededMemory | unknown; cpuTime: number; // microseconds wallTime: number; // microseconds } interface TraceLog { timestamp: number; level: log | info | debug | warn | error; message: any; // string or structured object } interface TraceException { name: string; message: string; timestamp: number; }六、实战模式五种高频场景本节内容完整继承自 patterns.md全部基于 Analytics Engine 写入 SQL 聚合的组合。1. 基于用量的计费Usage-Based Billing写入侧将 customerId 同时放入 blobs 与 indexesdouble1记请求计数。env.ANALYTICS.writeDataPoint({ blobs: [customerId, request.url, request.method], doubles: [1], // request_count indexes: [customerId] });查询侧按月聚合每位客户的调用量注意用_sample_interval校正采样。SELECT blob1 AS customer_id, SUM(_sample_interval * double1) AS total_calls FROM api_usage WHERE timestamp DATE_TRUNC(month, NOW()) GROUP BY customer_id2. 性能监控写入侧记录外部 fetch 的耗时与状态码。const start Date.now(); const response await fetch(url); env.ANALYTICS.writeDataPoint({ blobs: [url, response.status.toString()], doubles: [Date.now() - start, response.status] });查询侧按 URL 计算平均耗时与 P95。SELECT blob1 AS url, AVG(double1) AS avg_ms, percentile(double1, 0.95) AS p95_ms FROM fetch_metrics WHERE timestamp NOW() - INTERVAL 1 HOUR GROUP BY url3. 错误追踪env.ANALYTICS.writeDataPoint({ blobs: [error.name, request.url, request.method], doubles: [1], indexes: [error.name] });4. 多租户追踪将 tenantId 同时作为索引高效过滤与 blob可读展示写入env.ANALYTICS.writeDataPoint({ indexes: [tenantId], // efficient filtering blobs: [tenantId, url.pathname, method, status], doubles: [1, duration, bytesSize] });5. Tail Worker 日志过滤与 OpenTelemetry 导出日志过滤过滤出含异常或墙钟时间超过 1 秒1,000,000μs的临界事件并携带鉴权头发往外部采集端点export default { async tail(events, env, ctx) { const critical events.filter(e e.exceptions.length 0 || e.event.wallTime 1000000 ); if (critical.length 0) return; ctx.waitUntil( fetch(https://logging.example.com/ingest, { method: POST, headers: { Authorization: Bearer ${env.API_KEY} }, body: JSON.stringify(critical.map(e ({ outcome: e.event.outcome, cpu_ms: e.event.cpuTime / 1000, errors: e.exceptions }))) }) ); } };OpenTelemetry 导出将 Tail 事件转换为 OTel Span 结构并批量 POST 到 Honeycomb 等后端export default { async tail(events, env, ctx) { const otelSpans events.map(e ({ traceId: generateId(32), spanId: generateId(16), name: e.scriptName || worker.request, attributes: [ { key: worker.outcome, value: { stringValue: e.event.outcome } }, { key: worker.cpu_time_us, value: { intValue: String(e.event.cpuTime) } } ] })); ctx.waitUntil( fetch(https://api.honeycomb.io/v1/traces, { method: POST, headers: { X-Honeycomb-Team: env.HONEYCOMB_KEY }, body: JSON.stringify({ resourceSpans: [{ scopeSpans: [{ spans: otelSpans }] }] }) }) ); } };七、常见错误与排查1. Logs not appearing日志不出现可能原因观测未启用、Worker 未重新部署、无流量、采样率过低、或日志超过 256 KB 被截断。排查步骤# Verify config cat wrangler.jsonc | jq .observability # Check deployment wrangler deployments list WORKER_NAME # Test with curl curl https://your-worker.workers.dev确保observability.enabled true重新部署 Worker检查head_sampling_rate并确认确有流量。2. Traces not being captured追踪未被采集可能原因Traces 未启用、采样率设置错误、Worker 未重新部署、目标不可用。排查方案临时将采样率调到 100% 调试{ observability: { enabled: true, head_sampling_rate: 1.0, traces: { enabled: true } } }确保observability.traces.enabled true测试期将head_sampling_rate设为 1.0重新部署并检查目标状态。八、硬性限制与性能陷阱1. 硬性限制速查表资源/限制数值说明单条日志最大体积256 KB超出会被截断默认采样率1.0100%高流量 Worker 建议降低最大 Logpush 目标数视套餐而定以 Dashboard 为准Trace 上下文传播最多 100 spans深调用链可能丢失 spanAnalytics Engine 写入速率每请求 25 次写入超出部分被静默丢弃2. Spectre 缓解导致的时间精度问题问题Date.now()与performance.now()的精度被粗化到 100μsV8 中针对 Spectre 漏洞的缓解措施。方案接受降低的精度或改用 Workers Traces 获取精确时序// Date.now() is coarsened - trace spans are accurate export default { async fetch(request: Request, env: Env, ctx: ExecutionContext): PromiseResponse { // For user-facing timing, Date.now() is fine const start Date.now(); const response await processRequest(request); const duration Date.now() - start; // For detailed performance analysis, use Workers Traces instead return response; } }3. Analytics Engine_sample_interval聚合陷阱问题Analytics Engine 存储的是采样后的数据点每个点代表多个真实事件聚合时若忘记乘以_sample_interval会得到偏小的计数。方案聚合时始终用_sample_interval校正-- WRONG: Undercounts actual events SELECT blob1 AS customer_id, COUNT(*) AS total_calls FROM api_usage GROUP BY customer_id; -- CORRECT: Accounts for sampling SELECT blob1 AS customer_id, SUM(_sample_interval) AS total_calls FROM api_usage GROUP BY customer_id;4. Trace 上下文传播上限问题超过 100 个 span 的深层调用链会丢失 trace 上下文Cloudflare 为控制性能影响而限制追踪深度。方案设计更扁平的系统架构或对深调用链使用自定义关联 ID// For deep call chains, add custom correlation ID const correlationId crypto.randomUUID(); console.log({ correlationId, event: request_start }); // Pass correlationId through headers to downstream services await fetch(https://api.example.com, { headers: { X-Correlation-ID: correlationId } });九、在仓库中如何定位与使用本套参考本参考位于 observability 目录 下共四份文件按职责拆分README.md产品总览、决策树、阅读顺序与定价摘要configuration.mdLogs / Traces / Analytics Engine / Tail Workers / Logpush 的启用与部署配置api.mdGraphQL 与 SQL API、绑定类型、字段限制patterns.md计费、性能监控、错误追踪、多租户、Tail 过滤、OTel 导出等模式gotchas.md常见错误、限制、性能陷阱与 2026 定价细则。它与仓库内的相关模块互为补充Tail Worker 的完整能力与决策树见 tail-workers 参考Analytics Engine 的数据集/数据点概念与快速上手见 analytics-engine 参考。在真实部署流程中该技能要求先执行npx wrangler whoami确认认证再按 SKILL.md 中的决策树定位产品模块最后加载对应参考文件执行配置与部署。十、总结Cloudflare 的可观测性体系可以按写入、存储、导出、查询四层理解Worker 内用console结构化日志与writeDataPoint写指标Workers Traces 自动采集执行链路Tail Worker 做实时过滤与自定义处理Logpush 负责批量导出到外部系统最终通过 GraphQL 与 SQL API 统一查询。实践中的关键纪律包括保持结构化日志、按流量调整head_sampling_rate、聚合时乘以_sample_interval、遵守字段与调用上限以及理解时间精度的取舍。掌握这些配置与模式即可在生产环境构建一套完整且成本可控的 Workers 可观测性方案。【免费下载链接】skillsSkills Catalog for Codex项目地址: https://gitcode.com/GitHub_Trending/skills4/skills创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考