references/analytics-engine/gotchas.md
Analytics Engine Gotchas
Critical Issues
Sampling at High Volumes
Problem: Queries return fewer points than written at >1M writes/min.
Solution:
// Pre-aggregate before writing
let buffer = { count: 0, total: 0 };
buffer.count++; buffer.total += value;
// Write once per second instead of per request
if (Date.now() % 1000 === 0) {
env.ANALYTICS.writeDataPoint({ doubles: [buffer.count, buffer.total] });
}
Detection: npx wrangler tail → look for "sampling enabled"
writeDataPoint Returns void
// ❌ Pointless await
await env.ANALYTICS.writeDataPoint({...});
// ✅ Fire-and-forget
env.ANALYTICS.writeDataPoint({...});
Writes can fail silently. Check tail logs.
Index vs Blob
| Cardinality | Use | Example | |-------------|-----|---------| | Millions | Index | user_id, api_key | | Hundreds | Blob | endpoint, status_code, country |
// ✅ Correct
{ blobs: [method, path, status], indexes: [userId] }
Can't Query from Workers
Query API requires HTTP auth. Use external service or cache in KV/D1.
No Custom Timestamps
Auto-generated at write time. Store original in blob if needed.
Common Errors
| Error | Fix | |-------|-----| | Binding not found | Check wrangler.jsonc, redeploy | | No data in query | Wait 30s; check dataset name; check time range | | Query timeout | Add time filter; use index for filtering |
Limits
| Resource | Limit | |----------|-------| | Blobs per point | 20 | | Doubles per point | 20 | | Indexes per point | 1 | | Blob/Index size | 16KB | | Write rate (no sampling) | ~1M/min | | Retention | 90 days | | Query timeout | 30s |
Best Practices
✅ Pre-aggregate at high volumes
✅ Use index for high-cardinality (millions)
✅ Always include time filter in queries
✅ Design schema before coding
❌ Don't await writeDataPoint
❌ Don't use index for low-cardinality
❌ Don't query without time range
❌ Don't assume all writes succeed