Observability 常见陷阱

## 常见错误 ### "日志未显示" **原因：** 未启用可观测性、Worker 未重新部署、无流量、采样率过低或日志大小超过 256 KB **解决方案：** bash # 验证配置 cat wrangler.jsonc | jq '.observability' # 检查部署 wrangler deployments list # 使用 curl 测试 curl https://your-worker.workers.dev 确保 `observability.enabled = true`，重新部署 Worker，检查 `head_sampling_rate`，验证流量 ### "追踪未被捕获" **原因：** 未启用追踪、采样率不正确、Worker 未重新部署或目标不可用 **解决方案：** c // 临时设置为 100% 采样以进行调试 { "observability": { "enabled": true, "head_sampling_rate": 1.0, "traces": { "enabled": true } } } 确保 `observability.traces.enabled = true`，将 `head_sampling_rate` 设置为 1.0 进行测试，重新部署，检查目标状态 ## 限制 | 资源/限制 | 值 | 备注 | |----------------|-------|-------| | 最大日志大小 | 256 KB | 超过此大小的日志将被截断 | | 默认采样率 | 1.0 (100%) | 高流量 Workers 请降低此值 | | 最大目标数 | 因计划而异 | 检查仪表板 | | 追踪上下文传播 | 最多 100 个 span | 深层调用链可能会丢失 span | | 分析引擎写入速率 | 25 次写入/请求 | 超出的写入将被静默丢弃 | ## 性能注意事项 ### Spectre 缓解计时 **问题：** `Date.now()` 和 `performance.now()` 的精度降低（粗化至 100μs） **原因：** V8 中的 Spectre 漏洞缓解措施 **解决方案：** 接受较低的精度或使用 Workers Traces 进行精确计时 typescript // Date.now() 已被粗化 - 追踪 span 是精确的 export default { async fetch(request: Request, env: Env, ctx: ExecutionContext): Promise { // 对于面向用户的计时，Date.now() 足够了 const start = Date.now(); const response = await processRequest(request); const duration = Date.now() - start; // 对于详细的性能分析，请改用 Workers Traces return response; } } ### 分析引擎 _sample_interval 聚合 **问题：** 未乘以 `_sample_interval` 时查询返回错误的汇总值 **原因：** 分析引擎存储的是采样数据点，每个点代表多个事件 **解决方案：** 在聚合中始终将计数/总和乘以 `_sample_interval` sql -- 错误：低估了实际事件数 SELECT blob1 AS customer_id, COUNT(*) AS total_calls