Analytics Engine 常见陷阱

# Analytics Engine 常见陷阱 ## 关键问题 ### 高流量下的采样 **问题：** 当写入速度超过 100 万次/分钟时，查询返回的数据点少于实际写入量。 **解决方案：** typescript // 写入前进行预聚合 let buffer = { count: 0, total: 0 }; buffer.count++; buffer.total += value; // 每秒写入一次，而不是每个请求写入一次 if (Date.now() % 1000 === 0) { env.ANALYTICS.writeDataPoint({ doubles: [buffer.count, buffer.total] }); } **检测：** `npx wrangler tail` → 查找 "sampling enabled" ### writeDataPoint 返回 void typescript // ❌ 无意义的 await await env.ANALYTICS.writeDataPoint({...}); // ✅ 即发即弃 env.ANALYTICS.writeDataPoint({...}); 写入可能会静默失败。请检查 tail 日志。 ### 索引 (Index) vs Blob | 基数 | 使用 | 示例 | |-------------|-----|---------| | 数百万 | **Index** | user_id, api_key | | 数百 | **Blob** | endpoint, status_code, country | typescript // ✅ 正确 { blobs: [method, path, status], indexes: [userId] } ### 无法从 Workers 查询 查询 API 需要 HTTP 认证。请使用外部服务或在 KV/D1 中缓存。 ### 无自定义时间戳 在写入时自动生成。如果需要，请将原始时间戳存储在 blob 中。 ## 常见错误 | 错误 | 修复 | |-------|-----| | 找不到绑定 | 检查 wrangler.jsonc，重新部署 | | 查询无数据 | 等待 30 秒；检查数据集名称；检查时间范围 | | 查询超时 | 添加时间过滤器；使用索引进行过滤 | ## 限制 | 资源 | 限制 | |----------|-------| | 每个点的 Blobs | 20 | | 每个点的 Doubles | 20 | | 每个点的 Indexes | 1 | | Blob/Index 大小 | 16KB | | 写入速率 (无采样) | ~100 万/分钟 | | 保留期 | 90 天 | | 查询超时 | 30 秒 | ## 最佳实践 ✅ 高流量下进行预聚合 ✅ 对高基数数据（数百万）使用索引 ✅ 查询时始终包含时间过滤器 ✅ 编码前设计好 Schema ❌ 不要 await writeDataPoint ❌ 不要对低基数数据使用索引 ❌ 不要查询不带时间范围的数据 ❌ 不要假设所有写入都会成功