1# Analytics Engine Patterns
2 
3## Use Cases
4 
5| Use Case | Key Metrics | Index On |
6|----------|-------------|----------|
7| API Metering | requests, bytes, compute_units | api_key |
8| Feature Usage | feature, action, duration | user_id |
9| Error Tracking | error_type, endpoint, count | customer_id |
10| Performance | latency_ms, cache_status | endpoint |
11| A/B Testing | variant, conversions | user_id |
12 
13## API Metering (Billing)
14 
15```typescript
16env.ANALYTICS.writeDataPoint({
17  blobs: [pathname, method, status, tier],
18  doubles: [1, computeUnits, bytes, latencyMs],
19  indexes: [apiKey]
20});
21 
22// Query: Monthly usage by customer
23// SELECT index1 AS api_key, SUM(double2) AS compute_units
24// FROM usage WHERE timestamp >= DATE_TRUNC('month', NOW()) GROUP BY index1
25```
26 
27## Error Tracking
28 
29```typescript
30env.ANALYTICS.writeDataPoint({
31  blobs: [endpoint, method, errorName, errorMessage.slice(0, 1000)],
32  doubles: [1, timeToErrorMs],
33  indexes: [customerId]
34});
35```
36 
37## Performance Monitoring
38 
39```typescript
40env.ANALYTICS.writeDataPoint({
41  blobs: [pathname, method, cacheStatus, status],
42  doubles: [latencyMs, 1],
43  indexes: [userId]
44});
45 
46// Query: P95 latency by endpoint
47// SELECT blob1, quantile(0.95)(double1) AS p95_ms FROM perf GROUP BY blob1
48```
49 
50## Anti-Patterns
51 
52| ❌ Wrong | ✅ Correct |
53|----------|-----------|
54| `await writeDataPoint()` | `writeDataPoint()` (fire-and-forget) |
55| `indexes: [method]` (low cardinality) | `blobs: [method]`, `indexes: [userId]` |
56| `blobs: [JSON.stringify(obj)]` | Store ID in blob, full object in D1/KV |
57| Write every request at 10M/min | Pre-aggregate per second |
58| Query from Worker | Query from external service/API |
59 
60## Best Practices
61 
621. **Design schema upfront** - Document blob/double/index assignments
632. **Always include count metric** - `doubles: [latency, 1]` for AVG calculations
643. **Use enums for blobs** - Consistent values like `Status.SUCCESS`
654. **Handle sampling** - Use ratios (avg_latency = SUM(latency)/SUM(count))
665. **Test queries early** - Validate schema before heavy writes
67 
68## Schema Template
69 
70```typescript
71/**
72 * Dataset: my_metrics
73 * 
74 * Blobs:
75 *   blob1: endpoint, blob2: method, blob3: status
76 * 
77 * Doubles:
78 *   double1: latency_ms, double2: count (always 1)
79 * 
80 * Indexes:
81 *   index1: customer_id (high cardinality)
82 */
83```
84