Analytics Engine 说明文档

# Cloudflare Workers Analytics Engine 参考指南 使用 Cloudflare Workers Analytics Engine 在大规模环境下实现无限基数分析的专家指南。 ## 什么是 Analytics Engine？ 专为高基数数据（数百万个唯一维度）设计的时序分析数据库。从 Workers 写入数据点，通过 SQL API 进行查询。适用于： - 面向用户的自定义分析仪表板 - 基于用量的计费与计量 - 针对每个客户/功能的监控 - 高频埋点且不影响性能 **核心能力：** 追踪具有无限唯一值的指标（例如数百万个用户 ID、API 密钥），且不会导致性能下降。 ## 核心概念 | 概念 | 描述 | 示例 | |---------|-------------|---------| | **Dataset (数据集)** | 相关指标的逻辑表 | `api_requests`, `user_events` | | **Data Point (数据点)** | 带时间戳的单次测量 | 一次 API 请求的指标 | | **Blobs** | 字符串维度（最多 20 个） | endpoint, method, status, user_id | | **Doubles** | 数值（最多 20 个） | latency_ms, request_count, bytes | | **Indexes** | 用于高效查询的过滤 Blob | customer_id, api_key | ## 阅读顺序 | 任务 | 从这里开始 | 然后阅读 | |------|------------|-----------| | **首次设置** | [configuration.md](configuration.md) → [api.md](api.md) → [patterns.md](patterns.md) | | | **写入数据** | [api.md](api.md) → [gotchas.md](gotchas.md) (采样) | | | **查询数据** | [api.md](api.md) (SQL API) → [patterns.md](patterns.md) (示例) | | | **调试** | [gotchas.md](gotchas.md) → [api.md](api.md) (限制) | | | **优化** | [patterns.md](patterns.md) (反模式) → [gotchas.md](gotchas.md) | | ## 何时使用 Analytics Engine 需要追踪指标吗？ → 是 ↓ 有数百万个唯一维度值吗？ → 是 ↓ 需要实时查询吗？ → 是 ↓ 使用 Analytics Engine ✓ 替代方案： - 低基数 (<10k 唯一值) → Workers Analytics (免费层) - 复杂的连接/关系 → D1 数据库 - 日志/调试 → Tail Workers (logpush) - 外部工具 → 发送到外部分析服务 (Datadog 等) ## 快速开始 1. 在 `wrangler.jsonc` 中添加绑定： c { "analytics_engine_datasets": [ { "binding": "ANALYTICS", "dataset": "my_events" } ] } 2. 写入数据点（即发即弃，无需 await）： typescript env.ANALYTICS.writeDataPoint({ blobs: ["/api/users", "GET", "200"], doubles: [145.2, 1], // latency_ms, count indexes: [customerId] });