try-works/role-model / .agents/skills/cloudflare
cloudflare
UnverifiedComprehensive Cloudflare platform skill covering Workers, Pages, storage (KV, D1, R2), AI (Workers AI, Vectorize, Agents SDK), feature flags (Flagship), networking (Tunnel, Spectrum), security (WAF, DDoS), and infrastructure-as-code (Terraform, Pulumi). Use for any Cloudflare development task. Biases towards retrieval from Cloudflare docs over pre-trained knowledge.
references/analytics-engine/gotchas.md
View on GitHub# Analytics Engine Gotchas
## Critical Issues
### Sampling at High Volumes
**Problem:** Queries return fewer points than written at >1M writes/min.
**Solution:**
```typescript
// 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
```typescript
// ❌ 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 |
```typescript
// ✅ 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
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| rea-analysis-optimizationmorluto/reaOptimize REA providers and shared analysis workflows for agent context, latency, CPU, and memory while preserving correctness and Evidence. Use for analysis bottlenecks and cache or query design; CI/test-suite optimization belongs to rea-ci-tests-audit. | Stars: 471k | Updated | Claude CodeCodex | Verified | Install |
| rea-ci-tests-auditmorluto/reaAudit REA CI and test suites for correctness, fixture drift, false passes, and measured performance; use for suite or workflow investigations and efficiency changes, rather than ordinary feature testing or a single test failure. | Stars: 471k | Updated | Claude CodeCodex | Verified | Install |
| rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics. | Stars: 471k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |