memory-journal-mcp 7.7.0 → 8.0.0

package/skills/cloudflare/references/observability/configuration.md

@@ -0,0 +1,178 @@
+## Configuration Patterns
+
+### Enable Workers Logs
+
+```jsonc
+{
+  "observability": {
+    "enabled": true,
+    "head_sampling_rate": 1, // 100% sampling (default)
+  },
+}
+```
+
+**Best Practice**: Use structured JSON logging for better indexing
+
+```typescript
+// Good - structured logging
+console.log({
+  user_id: 123,
+  action: 'login',
+  status: 'success',
+  duration_ms: 45,
+})
+
+// Avoid - unstructured string
+console.log('user_id: 123 logged in successfully in 45ms')
+```
+
+### Enable Workers Traces
+
+```jsonc
+{
+  "observability": {
+    "traces": {
+      "enabled": true,
+      "head_sampling_rate": 0.05, // 5% sampling
+    },
+  },
+}
+```
+
+**Note**: Default sampling is 100%. For high-traffic Workers, use lower sampling (0.01-0.1).
+
+### Configure Analytics Engine
+
+**Bind to Worker**:
+
+```toml
+# wrangler.toml
+analytics_engine_datasets = [
+  { binding = "ANALYTICS", dataset = "api_metrics" }
+]
+```
+
+**Write Data Points**:
+
+```typescript
+export interface Env {
+  ANALYTICS: AnalyticsEngineDataset
+}
+
+export default {
+  async fetch(request: Request, env: Env): Promise<Response> {
+    // Track metrics
+    env.ANALYTICS.writeDataPoint({
+      blobs: ['customer_123', 'POST', '/api/v1/users'],
+      doubles: [1, 245.5], // request_count, response_time_ms
+      indexes: ['customer_123'], // for efficient filtering
+    })
+
+    return new Response('OK')
+  },
+}
+```
+
+### Configure Tail Workers
+
+Tail Workers receive logs/traces from other Workers for filtering, transformation, or export.
+
+**Setup**:
+
+```toml
+# wrangler.toml
+name = "log-processor"
+main = "src/tail.ts"
+
+[[tail_consumers]]
+service = "my-worker" # Worker to tail
+```
+
+**Tail Worker Example**:
+
+```typescript
+export default {
+  async tail(events: TraceItem[], env: Env, ctx: ExecutionContext) {
+    // Filter errors only
+    const errors = events.filter(
+      (event) => event.outcome === 'exception' || event.outcome === 'exceededCpu'
+    )
+
+    if (errors.length > 0) {
+      // Send to external monitoring
+      ctx.waitUntil(
+        fetch('https://monitoring.example.com/errors', {
+          method: 'POST',
+          body: JSON.stringify(errors),
+        })
+      )
+    }
+  },
+}
+```
+
+### Configure Logpush
+
+Send logs to external storage (S3, R2, GCS, Azure, Datadog, etc.). Requires Business/Enterprise plan.
+
+**Via Dashboard**:
+
+1. Navigate to Analytics → Logs → Logpush
+2. Select destination type
+3. Provide credentials and bucket/endpoint
+4. Choose dataset (e.g., Workers Trace Events)
+5. Configure filters and fields
+
+**Via API**:
+
+```bash
+curl -X POST "https://api.cloudflare.com/client/v4/accounts/{account_id}/logpush/jobs" \
+  -H "Authorization: Bearer <API_TOKEN>" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "name": "workers-logs-to-s3",
+    "destination_conf": "s3://my-bucket/logs?region=us-east-1",
+    "dataset": "workers_trace_events",
+    "enabled": true,
+    "frequency": "high",
+    "filter": "{\"where\":{\"and\":[{\"key\":\"ScriptName\",\"operator\":\"eq\",\"value\":\"my-worker\"}]}}"
+  }'
+```
+
+### Environment-Specific Configuration
+
+**Development** (verbose logs, full sampling):
+
+```jsonc
+// wrangler.dev.jsonc
+{
+  "observability": {
+    "enabled": true,
+    "head_sampling_rate": 1.0,
+    "traces": {
+      "enabled": true,
+    },
+  },
+}
+```
+
+**Production** (reduced sampling, structured logs):
+
+```jsonc
+// wrangler.prod.jsonc
+{
+  "observability": {
+    "enabled": true,
+    "head_sampling_rate": 0.1, // 10% sampling
+    "traces": {
+      "enabled": true,
+    },
+  },
+}
+```
+
+Deploy with env-specific config:
+
+```bash
+wrangler deploy --config wrangler.prod.jsonc --env production
+```

package/skills/cloudflare/references/observability/gotchas.md

@@ -0,0 +1,125 @@
+## Common Errors
+
+### "Logs not appearing"
+
+**Cause:** Observability disabled, Worker not redeployed, no traffic, low sampling rate, or log size exceeds 256 KB
+**Solution:**
+
+```bash
+# Verify config
+cat wrangler.jsonc | jq '.observability'
+
+# Check deployment
+wrangler deployments list <WORKER_NAME>
+
+# Test with curl
+curl https://your-worker.workers.dev
+```
+
+Ensure `observability.enabled = true`, redeploy Worker, check `head_sampling_rate`, verify traffic
+
+### "Traces not being captured"
+
+**Cause:** Traces not enabled, incorrect sampling rate, Worker not redeployed, or destination unavailable
+**Solution:**
+
+```jsonc
+// Temporarily set to 100% sampling for debugging
+{
+  "observability": {
+    "enabled": true,
+    "head_sampling_rate": 1.0,
+    "traces": {
+      "enabled": true,
+    },
+  },
+}
+```
+
+Ensure `observability.traces.enabled = true`, set `head_sampling_rate` to 1.0 for testing, redeploy, check destination status
+
+## Limits
+
+| Resource/Limit              | Value             | Notes                             |
+| --------------------------- | ----------------- | --------------------------------- |
+| Max log size                | 256 KB            | Logs exceeding this are truncated |
+| Default sampling rate       | 1.0 (100%)        | Reduce for high-traffic Workers   |
+| Max destinations            | Varies by plan    | Check dashboard                   |
+| Trace context propagation   | 100 spans max     | Deep call chains may lose spans   |
+| Analytics Engine write rate | 25 writes/request | Excess writes dropped silently    |
+
+## Performance Gotchas
+
+### Spectre Mitigation Timing
+
+**Problem:** `Date.now()` and `performance.now()` have reduced precision (coarsened to 100μs)
+**Cause:** Spectre vulnerability mitigation in V8
+**Solution:** Accept reduced precision or use Workers Traces for accurate timing
+
+```typescript
+// Date.now() is coarsened - trace spans are accurate
+export default {
+  async fetch(request: Request, env: Env, ctx: ExecutionContext): Promise<Response> {
+    // For user-facing timing, Date.now() is fine
+    const start = Date.now()
+    const response = await processRequest(request)
+    const duration = Date.now() - start
+
+    // For detailed performance analysis, use Workers Traces instead
+    return response
+  },
+}
+```
+
+### Analytics Engine \_sample_interval Aggregation
+
+**Problem:** Queries return incorrect totals when not multiplying by `_sample_interval`
+**Cause:** Analytics Engine stores sampled data points, each representing multiple events
+**Solution:** Always multiply counts/sums by `_sample_interval` in aggregations
+
+```sql
+-- WRONG: Undercounts actual events
+SELECT blob1 AS customer_id, COUNT(*) AS total_calls
+FROM api_usage GROUP BY customer_id;
+
+-- CORRECT: Accounts for sampling
+SELECT blob1 AS customer_id, SUM(_sample_interval) AS total_calls
+FROM api_usage GROUP BY customer_id;
+```
+
+### Trace Context Propagation Limits
+
+**Problem:** Deep call chains lose trace context after 100 spans
+**Cause:** Cloudflare limits trace depth to prevent performance impact
+**Solution:** Design for flatter architectures or use custom correlation IDs for deep chains
+
+```typescript
+// For deep call chains, add custom correlation ID
+const correlationId = crypto.randomUUID()
+console.log({ correlationId, event: 'request_start' })
+
+// Pass correlationId through headers to downstream services
+await fetch('https://api.example.com', {
+  headers: { 'X-Correlation-ID': correlationId },
+})
+```
+
+## Pricing (2026)
+
+### Workers Traces
+
+- **GA Pricing (starts March 1, 2026):**
+  - $0.10 per 1M trace spans captured
+  - Retention: 14 days included
+- **Free tier:** 10M trace spans/month
+- **Note:** Beta usage (before March 1, 2026) is free
+
+### Workers Logs
+
+- **Included:** Free for all Workers
+- **Logpush:** Requires Business/Enterprise plan
+
+### Analytics Engine
+
+- **Included:** 10M writes/month on Paid Workers plan
+- **Additional:** $0.25 per 1M writes beyond included quota

package/skills/cloudflare/references/observability/patterns.md

@@ -0,0 +1,105 @@
+# Observability Patterns
+
+## Usage-Based Billing
+
+```typescript
+env.ANALYTICS.writeDataPoint({
+  blobs: [customerId, request.url, request.method],
+  doubles: [1], // request_count
+  indexes: [customerId],
+})
+```
+
+```sql
+SELECT blob1 AS customer_id, SUM(_sample_interval * double1) AS total_calls
+FROM api_usage WHERE timestamp >= DATE_TRUNC('month', NOW())
+GROUP BY customer_id
+```
+
+## Performance Monitoring
+
+```typescript
+const start = Date.now()
+const response = await fetch(url)
+env.ANALYTICS.writeDataPoint({
+  blobs: [url, response.status.toString()],
+  doubles: [Date.now() - start, response.status],
+})
+```
+
+```sql
+SELECT blob1 AS url, AVG(double1) AS avg_ms, percentile(double1, 0.95) AS p95_ms
+FROM fetch_metrics WHERE timestamp >= NOW() - INTERVAL '1' HOUR
+GROUP BY url
+```
+
+## Error Tracking
+
+```typescript
+env.ANALYTICS.writeDataPoint({
+  blobs: [error.name, request.url, request.method],
+  doubles: [1],
+  indexes: [error.name],
+})
+```
+
+## Multi-Tenant Tracking
+
+```typescript
+env.ANALYTICS.writeDataPoint({
+  indexes: [tenantId], // efficient filtering
+  blobs: [tenantId, url.pathname, method, status],
+  doubles: [1, duration, bytesSize],
+})
+```
+
+## Tail Worker Log Filtering
+
+```typescript
+export default {
+  async tail(events, env, ctx) {
+    const critical = events.filter((e) => e.exceptions.length > 0 || e.event.wallTime > 1000000)
+    if (critical.length === 0) return
+
+    ctx.waitUntil(
+      fetch('https://logging.example.com/ingest', {
+        method: 'POST',
+        headers: { Authorization: `Bearer ${env.API_KEY}` },
+        body: JSON.stringify(
+          critical.map((e) => ({
+            outcome: e.event.outcome,
+            cpu_ms: e.event.cpuTime / 1000,
+            errors: e.exceptions,
+          }))
+        ),
+      })
+    )
+  },
+}
+```
+
+## OpenTelemetry Export
+
+```typescript
+export default {
+  async tail(events, env, ctx) {
+    const otelSpans = events.map((e) => ({
+      traceId: generateId(32),
+      spanId: generateId(16),
+      name: e.scriptName || 'worker.request',
+      attributes: [
+        { key: 'worker.outcome', value: { stringValue: e.event.outcome } },
+        { key: 'worker.cpu_time_us', value: { intValue: String(e.event.cpuTime) } },
+      ],
+    }))
+
+    ctx.waitUntil(
+      fetch('https://api.honeycomb.io/v1/traces', {
+        method: 'POST',
+        headers: { 'X-Honeycomb-Team': env.HONEYCOMB_KEY },
+        body: JSON.stringify({ resourceSpans: [{ scopeSpans: [{ spans: otelSpans }] }] }),
+      })
+    )
+  },
+}
+```

package/skills/cloudflare/references/pages/README.md

@@ -0,0 +1,92 @@
+# Cloudflare Pages
+
+JAMstack platform for full-stack apps on Cloudflare's global network.
+
+## Key Features
+
+- **Git-based deploys**: Auto-deploy from GitHub/GitLab
+- **Preview deployments**: Unique URL per branch/PR
+- **Pages Functions**: File-based serverless routing (Workers runtime)
+- **Static + dynamic**: Smart asset caching + edge compute
+- **Smart Placement**: Automatic function optimization based on traffic patterns
+- **Framework optimized**: SvelteKit, Astro, Nuxt, Qwik, Solid Start
+
+## Deployment Methods
+
+### 1. Git Integration (Production)
+
+Dashboard → Workers & Pages → Create → Connect to Git → Configure build
+
+### 2. Direct Upload
+
+```bash
+npx wrangler pages deploy ./dist --project-name=my-project
+npx wrangler pages deploy ./dist --project-name=my-project --branch=staging
+```
+
+### 3. C3 CLI
+
+```bash
+npm create cloudflare@latest my-app
+# Select framework → auto-setup + deploy
+```
+
+## vs Workers
+
+- **Pages**: Static sites, JAMstack, frameworks, git workflow, file-based routing
+- **Workers**: Pure APIs, complex routing, WebSockets, scheduled tasks, email handlers
+- **Combine**: Pages Functions use Workers runtime, can bind to Workers
+
+## Quick Start
+
+```bash
+# Create
+npm create cloudflare@latest
+
+# Local dev
+npx wrangler pages dev ./dist
+
+# Deploy
+npx wrangler pages deploy ./dist --project-name=my-project
+
+# Types
+npx wrangler types --path='./functions/types.d.ts'
+
+# Secrets
+echo "value" | npx wrangler pages secret put KEY --project-name=my-project
+
+# Logs
+npx wrangler pages deployment tail --project-name=my-project
+```
+
+## Resources
+
+- [Pages Docs](https://developers.cloudflare.com/pages/)
+- [Functions API](https://developers.cloudflare.com/pages/functions/api-reference/)
+- [Framework Guides](https://developers.cloudflare.com/pages/framework-guides/)
+- [Discord #functions](https://discord.com/channels/595317990191398933/910978223968518144)
+
+## Reading Order
+
+**New to Pages?** Start here:
+
+1. README.md (you are here) - Overview & quick start
+2. [configuration.md](./configuration.md) - Project setup, wrangler.jsonc, bindings
+3. [api.md](./api.md) - Functions API, routing, context
+4. [patterns.md](./patterns.md) - Common implementations
+5. [gotchas.md](./gotchas.md) - Troubleshooting & pitfalls
+
+**Quick reference?** Jump to relevant file above.
+
+## In This Reference
+
+- [configuration.md](./configuration.md) - wrangler.jsonc, build, env vars, Smart Placement
+- [api.md](./api.md) - Functions API, bindings, context, advanced mode
+- [patterns.md](./patterns.md) - Full-stack patterns, framework integration
+- [gotchas.md](./gotchas.md) - Build issues, limits, debugging, framework warnings
+
+## See Also
+
+- [pages-functions](../pages-functions/) - File-based routing, middleware
+- [d1](../d1/) - SQL database for Pages Functions
+- [kv](../kv/) - Key-value storage for caching/state

package/skills/cloudflare/references/pages/api.md

@@ -0,0 +1,205 @@
+# Functions API
+
+## File-Based Routing
+
+```
+/functions/index.ts              → example.com/
+/functions/api/users.ts          → example.com/api/users
+/functions/api/users/[id].ts     → example.com/api/users/:id
+/functions/api/users/[[path]].ts → example.com/api/users/* (catchall)
+/functions/_middleware.ts        → Runs before all routes
+```
+
+**Rules**: `[param]` = single segment, `[[param]]` = multi-segment catchall, more specific wins.
+
+## Request Handlers
+
+```typescript
+import type { PagesFunction } from '@cloudflare/workers-types'
+
+interface Env {
+  DB: D1Database
+  KV: KVNamespace
+}
+
+// All methods
+export const onRequest: PagesFunction<Env> = async (context) => {
+  return new Response('All methods')
+}
+
+// Method-specific
+export const onRequestGet: PagesFunction<Env> = async (context) => {
+  const { request, env, params, data } = context
+
+  const user = await env.DB.prepare('SELECT * FROM users WHERE id = ?').bind(params.id).first()
+
+  return Response.json(user)
+}
+
+export const onRequestPost: PagesFunction<Env> = async (context) => {
+  const body = await context.request.json()
+  return Response.json({ success: true })
+}
+
+// Also: onRequestPut, onRequestPatch, onRequestDelete, onRequestHead, onRequestOptions
+```
+
+## Context Object
+
+```typescript
+interface EventContext<Env, Params, Data> {
+  request: Request // HTTP request
+  env: Env // Bindings (KV, D1, R2, etc.)
+  params: Params // Route parameters
+  data: Data // Middleware-shared data
+  waitUntil: (promise: Promise<any>) => void // Background tasks
+  next: () => Promise<Response> // Next handler
+  passThroughOnException: () => void // Error fallback (not in advanced mode)
+}
+```
+
+## Dynamic Routes
+
+```typescript
+// Single segment: functions/users/[id].ts
+export const onRequestGet: PagesFunction = async ({ params }) => {
+  // /users/123 → params.id = "123"
+  return Response.json({ userId: params.id })
+}
+
+// Multi-segment: functions/files/[[path]].ts
+export const onRequestGet: PagesFunction = async ({ params }) => {
+  // /files/docs/api/v1.md → params.path = ["docs", "api", "v1.md"]
+  const filePath = (params.path as string[]).join('/')
+  return new Response(filePath)
+}
+```
+
+## Middleware
+
+```typescript
+// functions/_middleware.ts
+// Single
+export const onRequest: PagesFunction = async (context) => {
+  const response = await context.next()
+  response.headers.set('X-Custom-Header', 'value')
+  return response
+}
+
+// Chained (runs in order)
+const errorHandler: PagesFunction = async (context) => {
+  try {
+    return await context.next()
+  } catch (err) {
+    return new Response(err.message, { status: 500 })
+  }
+}
+
+const auth: PagesFunction = async (context) => {
+  const token = context.request.headers.get('Authorization')
+  if (!token) return new Response('Unauthorized', { status: 401 })
+  context.data.userId = await verifyToken(token)
+  return context.next()
+}
+
+export const onRequest = [errorHandler, auth]
+```
+
+**Scope**: `functions/_middleware.ts` → all; `functions/api/_middleware.ts` → `/api/*` only
+
+## Bindings Usage
+
+```typescript
+export const onRequestGet: PagesFunction<Env> = async ({ env }) => {
+  // KV
+  const cached = await env.KV.get('key', 'json')
+  await env.KV.put('key', JSON.stringify({ data: 'value' }), { expirationTtl: 3600 })
+
+  // D1
+  const result = await env.DB.prepare('SELECT * FROM users WHERE id = ?').bind(userId).first()
+
+  // R2, Queue, AI - see respective reference docs
+
+  return Response.json({ success: true })
+}
+```
+
+## Advanced Mode
+
+Full Workers API, bypasses file-based routing:
+
+```javascript
+// functions/_worker.js
+export default {
+  async fetch(request, env, ctx) {
+    const url = new URL(request.url)
+
+    // Custom routing
+    if (url.pathname.startsWith('/api/')) {
+      return new Response('API response')
+    }
+
+    // REQUIRED: Serve static assets
+    return env.ASSETS.fetch(request)
+  },
+}
+```
+
+**When to use**: WebSockets, complex routing, scheduled handlers, email handlers.
+
+## Smart Placement
+
+Automatically optimizes function execution location based on traffic patterns.
+
+**Configuration** (in wrangler.jsonc):
+
+```jsonc
+{
+  "placement": {
+    "mode": "smart", // Enables optimization (default: off)
+  },
+}
+```
+
+**How it works**: Analyzes traffic patterns over time and places functions closer to users or data sources (e.g., D1 databases). Requires no code changes.
+
+**Trade-offs**: Initial requests may see slightly higher latency during learning period (hours-days). Performance improves as system optimizes.
+
+**When to use**: Global apps with centralized databases or geographically concentrated traffic sources.
+
+## getRequestContext (Framework SSR)
+
+Access bindings in framework code:
+
+```typescript
+// SvelteKit
+import type { RequestEvent } from '@sveltejs/kit'
+export async function load({ platform }: RequestEvent) {
+  const data = await platform.env.DB.prepare('SELECT * FROM users').all()
+  return { users: data.results }
+}
+
+// Astro
+const { DB } = Astro.locals.runtime.env
+const data = await DB.prepare('SELECT * FROM users').all()
+
+// Solid Start (server function)
+import { getRequestEvent } from 'solid-js/web'
+const event = getRequestEvent()
+const data = await event.locals.runtime.env.DB.prepare('SELECT * FROM users').all()
+```
+
+**✅ Supported adapters** (2026):
+
+- **SvelteKit**: `@sveltejs/adapter-cloudflare`
+- **Astro**: Built-in Cloudflare adapter
+- **Nuxt**: Set `nitro.preset: 'cloudflare-pages'` in `nuxt.config.ts`
+- **Qwik**: Built-in Cloudflare adapter
+- **Solid Start**: `@solidjs/start-cloudflare-pages`
+
+**❌ Deprecated/Unsupported**:
+
+- **Next.js**: Official adapter (`@cloudflare/next-on-pages`) deprecated. Use Vercel or self-host on Workers.
+- **Remix**: Official adapter (`@remix-run/cloudflare-pages`) deprecated. Migrate to supported frameworks.
+
+See [gotchas.md](./gotchas.md#framework-specific) for migration guidance.