Cloudflare Observability 全指南：Workers Logs、Traces、Analytics Engine 与 Logpush 实战手册

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输出。
• 访问方式：Dashboard（Real-time Logs）、Logpush、Tail Workers。
• 成本：免费，随所有 Workers 自带。
• 保留策略：仅实时查看（Dashboard 不做历史存储），历史留存需依赖 Logpush 或 Tail Worker 转储。

Workers Traces

• 是什么：包含时序、CPU 用量、执行结果的执行追踪（execution traces）。
• 访问方式：Dashboard（Workers Analytics → Traces）、Logpush。
• 成本：GA 定价自2026 年 3 月 1 日起为 $0.10/1M spans，每月免费 10M spans。
• 保留策略：默认包含 14 天留存。

Analytics Engine

• 是什么：面向高基数（high-cardinality）事件存储与 SQL 查询的时序分析数据库，可支持数百万级唯一维度值（如海量用户 ID、API Key）而不产生性能劣化，非常适合自定义用户分析面板、用量计费、按客户/按功能监控。
• 访问方式：SQL API、Dashboard（Analytics → 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）

补充说明（来自 gotchas.md）：Workers Traces 在 2026 年 3 月 1 日 GA 之前的 Beta 使用免费；Logpush 使用量包含在 Business/Enterprise 套餐中。

三、如何使用这套参考：决策树与阅读顺序

在 Agent / LLM 场景下，直接加载全部参考文件成本较高，因此该模块提供决策树用于路由：

├─ "How do I enable/configure X?" → configuration.md ├─ "What's 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 isn't X working?" / "Limits?" → gotchas.md

不同任务类型的推荐阅读顺序：

四、配置实战：从日志到 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，无需 await）：

export interface Env { ANALYTICS: AnalyticsEngineDataset; } export default { async fetch(request: Request, env: Env): Promise<Response> { // 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 README）：

• Blobs：字符串维度（最多 20 个），如 endpoint、method、status、user_id；
• Doubles：数值（最多 20 个），如 latency_ms、request_count、bytes；
• Indexes：用于高效过滤的索引字符串（最多 20 个），如 customer_id、api_key。

4. 配置 Tail Workers

Tail Worker 接收其他 Worker 的日志与 traces，用于过滤、转换或导出。

Setup（生产者侧）：

# wrangler.toml name = "log-processor" main = "src/tail.ts" [[tail_consumers]] service = "my-worker" # Worker to tail

Tail 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 方式：

1. 进入 Analytics → Logs → Logpush；
2. 选择目标类型；
3. 提供凭据与 bucket/endpoint；
4. 选择数据集（如 Workers Trace Events）；
5. 配置过滤条件与字段。

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?region=us-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 与 indexes，double1记请求计数。

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_id

2. 性能监控

写入侧：记录外部 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 url

3. 错误追踪

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. 硬性限制速查表

2. Spectre 缓解导致的时间精度问题

问题：Date.now()与performance.now()的精度被粗化到 100μs（V8 中针对 Spectre 漏洞的缓解措施）。

方案：接受降低的精度，或改用 Workers Traces 获取精确时序：

// Date.now() is coarsened - trace spans are accurate export default { async fetch(request: Request, env: Env, ctx: ExecutionContext): Promise<Response> { // 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.md：Logs / Traces / Analytics Engine / Tail Workers / Logpush 的启用与部署配置；
• api.md：GraphQL 与 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