1# Analytics Engine Gotchas
2 
3## Critical Issues
4 
5### Sampling at High Volumes
6 
7**Problem:** Queries return fewer points than written at >1M writes/min.
8 
9**Solution:**
10```typescript
11// Pre-aggregate before writing
12let buffer = { count: 0, total: 0 };
13buffer.count++; buffer.total += value;
14 
15// Write once per second instead of per request
16if (Date.now() % 1000 === 0) {
17  env.ANALYTICS.writeDataPoint({ doubles: [buffer.count, buffer.total] });
18}
19```
20 
21**Detection:** `npx wrangler tail` → look for "sampling enabled"
22 
23### writeDataPoint Returns void
24 
25```typescript
26// ❌ Pointless await
27await env.ANALYTICS.writeDataPoint({...});
28 
29// ✅ Fire-and-forget
30env.ANALYTICS.writeDataPoint({...});
31```
32 
33Writes can fail silently. Check tail logs.
34 
35### Index vs Blob
36 
37| Cardinality | Use | Example |
38|-------------|-----|---------|
39| Millions | **Index** | user_id, api_key |
40| Hundreds | **Blob** | endpoint, status_code, country |
41 
42```typescript
43// ✅ Correct
44{ blobs: [method, path, status], indexes: [userId] }
45```
46 
47### Can't Query from Workers
48 
49Query API requires HTTP auth. Use external service or cache in KV/D1.
50 
51### No Custom Timestamps
52 
53Auto-generated at write time. Store original in blob if needed.
54 
55## Common Errors
56 
57| Error | Fix |
58|-------|-----|
59| Binding not found | Check wrangler.jsonc, redeploy |
60| No data in query | Wait 30s; check dataset name; check time range |
61| Query timeout | Add time filter; use index for filtering |
62 
63## Limits
64 
65| Resource | Limit |
66|----------|-------|
67| Blobs per point | 20 |
68| Doubles per point | 20 |
69| Indexes per point | 1 |
70| Blob/Index size | 16KB |
71| Write rate (no sampling) | ~1M/min |
72| Retention | 90 days |
73| Query timeout | 30s |
74 
75## Best Practices
76 
77✅ Pre-aggregate at high volumes  
78✅ Use index for high-cardinality (millions)  
79✅ Always include time filter in queries  
80✅ Design schema before coding  
81 
82❌ Don't await writeDataPoint  
83❌ Don't use index for low-cardinality  
84❌ Don't query without time range  
85❌ Don't assume all writes succeed
86