update skills

.agents/skills/cloudflare-deploy/references/analytics-engine/patterns.md

@@ -0,0 +1,83 @@
+# Analytics Engine Patterns
+
+## Use Cases
+
+| Use Case | Key Metrics | Index On |
+|----------|-------------|----------|
+| API Metering | requests, bytes, compute_units | api_key |
+| Feature Usage | feature, action, duration | user_id |
+| Error Tracking | error_type, endpoint, count | customer_id |
+| Performance | latency_ms, cache_status | endpoint |
+| A/B Testing | variant, conversions | user_id |
+
+## API Metering (Billing)
+
+```typescript
+env.ANALYTICS.writeDataPoint({
+  blobs: [pathname, method, status, tier],
+  doubles: [1, computeUnits, bytes, latencyMs],
+  indexes: [apiKey]
+});
+
+// Query: Monthly usage by customer
+// SELECT index1 AS api_key, SUM(double2) AS compute_units
+// FROM usage WHERE timestamp >= DATE_TRUNC('month', NOW()) GROUP BY index1
+```
+
+## Error Tracking
+
+```typescript
+env.ANALYTICS.writeDataPoint({
+  blobs: [endpoint, method, errorName, errorMessage.slice(0, 1000)],
+  doubles: [1, timeToErrorMs],
+  indexes: [customerId]
+});
+```
+
+## Performance Monitoring
+
+```typescript
+env.ANALYTICS.writeDataPoint({
+  blobs: [pathname, method, cacheStatus, status],
+  doubles: [latencyMs, 1],
+  indexes: [userId]
+});
+
+// Query: P95 latency by endpoint
+// SELECT blob1, quantile(0.95)(double1) AS p95_ms FROM perf GROUP BY blob1
+```
+
+## Anti-Patterns
+
+| ❌ Wrong | ✅ Correct |
+|----------|-----------|
+| `await writeDataPoint()` | `writeDataPoint()` (fire-and-forget) |
+| `indexes: [method]` (low cardinality) | `blobs: [method]`, `indexes: [userId]` |
+| `blobs: [JSON.stringify(obj)]` | Store ID in blob, full object in D1/KV |
+| Write every request at 10M/min | Pre-aggregate per second |
+| Query from Worker | Query from external service/API |
+
+## Best Practices
+
+1. **Design schema upfront** - Document blob/double/index assignments
+2. **Always include count metric** - `doubles: [latency, 1]` for AVG calculations
+3. **Use enums for blobs** - Consistent values like `Status.SUCCESS`
+4. **Handle sampling** - Use ratios (avg_latency = SUM(latency)/SUM(count))
+5. **Test queries early** - Validate schema before heavy writes
+
+## Schema Template
+
+```typescript
+/**
+ * Dataset: my_metrics
+ * 
+ * Blobs:
+ *   blob1: endpoint, blob2: method, blob3: status
+ * 
+ * Doubles:
+ *   double1: latency_ms, double2: count (always 1)
+ * 
+ * Indexes:
+ *   index1: customer_id (high cardinality)
+ */
+```