memory-journal-mcp 7.7.1 → 8.0.0

package/skills/cloudflare/references/network-interconnect/gotchas.md

@@ -0,0 +1,175 @@
+# CNI Gotchas & Troubleshooting
+
+## Common Errors
+
+### "Status: Pending"
+
+**Cause:** Cross-connect not installed, RX/TX fibers reversed, wrong fiber type, or low light levels
+**Solution:**
+
+1. Verify cross-connect installed
+2. Check fiber at patch panel
+3. Swap RX/TX fibers
+4. Check light with optical power meter (target > -20 dBm)
+5. Contact account team
+
+### "Status: Unhealthy"
+
+**Cause:** Physical issue, low light (<-20 dBm), optic mismatch, or dirty connectors
+**Solution:**
+
+1. Check physical connections
+2. Clean fiber connectors
+3. Verify optic types (10GBASE-LR/100GBASE-LR4)
+4. Test with known-good optics
+5. Check patch panel
+6. Contact account team
+
+### "BGP Session Down"
+
+**Cause:** Wrong IP addressing, wrong ASN, password mismatch, or firewall blocking TCP/179
+**Solution:**
+
+1. Verify IPs match CNI object
+2. Confirm ASN correct
+3. Check BGP password
+4. Verify no firewall on TCP/179
+5. Check BGP logs
+6. Review BGP timers
+
+### "Low Throughput"
+
+**Cause:** MTU mismatch, fragmentation, single GRE tunnel (v1), or routing inefficiency
+**Solution:**
+
+1. Check MTU (1500↓/1476↑ for v1, 1500 both for v2)
+2. Test various packet sizes
+3. Add more GRE tunnels (v1)
+4. Consider upgrading to v2
+5. Review routing tables
+6. Use LACP for bundling (v1)
+
+## API Errors
+
+### 400 Bad Request: "slot_id already occupied"
+
+**Cause:** Another interconnect already uses this slot  
+**Solution:** Use `occupied=false` filter when listing slots:
+
+```typescript
+await client.networkInterconnects.slots.list({
+  account_id: id,
+  occupied: false,
+  facility: 'EWR1',
+})
+```
+
+### 400 Bad Request: "invalid facility code"
+
+**Cause:** Typo or unsupported facility  
+**Solution:** Check [locations PDF](https://developers.cloudflare.com/network-interconnect/static/cni-locations-2026-01.pdf) for valid codes
+
+### 403 Forbidden: "Enterprise plan required"
+
+**Cause:** Account not enterprise-level  
+**Solution:** Contact account team to upgrade
+
+### 422 Unprocessable: "validate_only request failed"
+
+**Cause:** Dry-run validation found issues (wrong slot, invalid config)  
+**Solution:** Review error message details, fix config before real creation
+
+### Rate Limiting
+
+**Limit:** 1200 requests/5min per token  
+**Solution:** Implement exponential backoff, cache slot listings
+
+## Cloud-Specific Issues
+
+### AWS Direct Connect: "VLAN not matching"
+
+**Cause:** VLAN ID from AWS LOA doesn't match CNI config  
+**Solution:**
+
+1. Get VLAN from AWS Console after ordering
+2. Send exact VLAN to CF account team
+3. Verify match in CNI object config
+
+### AWS: "Connection stuck in Pending"
+
+**Cause:** LOA not provided to CF or AWS connection not accepted  
+**Solution:**
+
+1. Verify AWS connection status is "Available"
+2. Confirm LOA sent to CF account team
+3. Wait for CF team acceptance (can take days)
+
+### GCP: "BGP routes not propagating"
+
+**Cause:** BGP routes from GCP Cloud Router **ignored by design**  
+**Solution:** Use [static routes](https://developers.cloudflare.com/magic-wan/configuration/manually/how-to/configure-routes/#configure-static-routes) in Magic WAN instead
+
+### GCP: "Cannot query VLAN attachment status via API"
+
+**Cause:** GCP Cloud Interconnect Dashboard-only (no API yet)  
+**Solution:** Check status in CF Dashboard or GCP Console
+
+## Partner Interconnect Issues
+
+### Equinix: "Virtual circuit not appearing"
+
+**Cause:** CF hasn't accepted Equinix connection request  
+**Solution:**
+
+1. Verify VC created in Equinix Fabric Portal
+2. Contact CF account team to accept
+3. Allow 2-3 business days
+
+### Console Connect/Megaport: "API creation fails"
+
+**Cause:** Partner interconnects require partner portal + CF approval  
+**Solution:** Cannot fully automate. Order in partner portal, notify CF account team.
+
+## Anti-Patterns
+
+| Anti-Pattern                           | Why Bad                              | Solution                             |
+| -------------------------------------- | ------------------------------------ | ------------------------------------ |
+| Single interconnect for production     | No SLA, single point of failure      | Use ≥2 with device diversity         |
+| No backup Internet                     | CNI fails = total outage             | Always maintain alternate path       |
+| Polling status every second            | Rate limits, wastes API calls        | Poll every 30-60s max                |
+| Using v1 for Magic WAN v2 workloads    | GRE overhead, complexity             | Use v2 for simplified routing        |
+| Assuming BGP session = traffic flowing | BGP up ≠ routes installed            | Verify routing tables + test traffic |
+| Not enabling maintenance alerts        | Surprise downtime during maintenance | Enable notifications immediately     |
+| Hardcoding VLAN in automation          | VLAN assigned by CF (v1)             | Get VLAN from CNI object response    |
+| Using Direct without colocation        | Can't access cross-connect           | Use Partner or Cloud interconnect    |
+
+## What's Not Queryable via API
+
+**Cannot retrieve:**
+
+- BGP session state (use Dashboard or BGP logs)
+- Light levels (contact account team)
+- Historical metrics (uptime, traffic)
+- Bandwidth utilization per interconnect
+- Maintenance window schedules (notifications only)
+- Fiber path details
+- Cross-connect installation status
+
+**Workarounds:**
+
+- External monitoring for BGP state
+- Log aggregation for historical data
+- Notifications for maintenance windows
+
+## Limits
+
+| Resource/Limit        | Value         | Notes                               |
+| --------------------- | ------------- | ----------------------------------- |
+| Max optical distance  | 10km          | Physical limit                      |
+| MTU (v1)              | 1500↓ / 1476↑ | Asymmetric                          |
+| MTU (v2)              | 1500 both     | Symmetric                           |
+| GRE tunnel throughput | 1 Gbps        | Per tunnel (v1)                     |
+| Recovery time         | Days          | No formal SLA                       |
+| Light level minimum   | -20 dBm       | Target threshold                    |
+| API rate limit        | 1200 req/5min | Per token                           |
+| Health check delay    | 6 hours       | New maintenance alert subscriptions |

package/skills/cloudflare/references/network-interconnect/patterns.md

@@ -0,0 +1,174 @@
+# CNI Patterns
+
+See [README.md](README.md) for overview.
+
+## High Availability
+
+**Critical:** Design for resilience from day one.
+
+**Requirements:**
+
+- Device-level diversity (separate hardware)
+- Backup Internet connectivity (no SLA on CNI)
+- Network-resilient locations preferred
+- Regular failover testing
+
+**Architecture:**
+
+```
+Your Network A ──10G CNI v2──> CF CCR Device 1
+                                     │
+Your Network B ──10G CNI v2──> CF CCR Device 2
+                                     │
+                            CF Global Network (AS13335)
+```
+
+**Capacity Planning:**
+
+- Plan across all links
+- Account for failover scenarios
+- Your responsibility
+
+## Pattern: Magic Transit + CNI v2
+
+**Use Case:** DDoS protection, private connectivity, no GRE overhead.
+
+```typescript
+// 1. Create interconnect
+const ic = await client.networkInterconnects.interconnects.create({
+  account_id: id,
+  type: 'direct',
+  facility: 'EWR1',
+  speed: '10G',
+  name: 'magic-transit-primary',
+})
+
+// 2. Poll until active
+const status = await pollUntilActive(id, ic.id)
+
+// 3. Configure Magic Transit tunnel via Dashboard/API
+```
+
+**Benefits:** 1500 MTU both ways, simplified routing.
+
+## Pattern: Multi-Cloud Hybrid
+
+**Use Case:** AWS/GCP workloads with Cloudflare.
+
+**AWS Direct Connect:**
+
+```typescript
+// 1. Order Direct Connect in AWS Console
+// 2. Get LOA + VLAN from AWS
+// 3. Send to CF account team (no API)
+// 4. Configure static routes in Magic WAN
+
+await configureStaticRoutes(id, {
+  prefix: '10.0.0.0/8',
+  nexthop: 'aws-direct-connect',
+})
+```
+
+**GCP Cloud Interconnect:**
+
+```
+1. Get VLAN attachment pairing key from GCP Console
+2. Create via Dashboard: Interconnects → Create → Cloud Interconnect → Google
+   - Enter pairing key, name, MTU, speed
+3. Configure static routes in Magic WAN (BGP routes from GCP ignored)
+4. Configure custom learned routes in GCP Cloud Router
+```
+
+**Note:** Dashboard-only. No API/SDK support yet.
+
+## Pattern: Multi-Location HA
+
+**Use Case:** 99.99%+ uptime.
+
+```typescript
+// Primary (NY)
+const primary = await client.networkInterconnects.interconnects.create({
+  account_id: id,
+  type: 'direct',
+  facility: 'EWR1',
+  speed: '10G',
+  name: 'primary-ewr1',
+})
+
+// Secondary (NY, different hardware)
+const secondary = await client.networkInterconnects.interconnects.create({
+  account_id: id,
+  type: 'direct',
+  facility: 'EWR2',
+  speed: '10G',
+  name: 'secondary-ewr2',
+})
+
+// Tertiary (LA, different geography)
+const tertiary = await client.networkInterconnects.interconnects.create({
+  account_id: id,
+  type: 'partner',
+  facility: 'LAX1',
+  speed: '10G',
+  name: 'tertiary-lax1',
+})
+
+// BGP local preferences:
+// Primary: 200
+// Secondary: 150
+// Tertiary: 100
+// Internet: Last resort
+```
+
+## Pattern: Partner Interconnect (Equinix)
+
+**Use Case:** Quick deployment, no colocation.
+
+**Setup:**
+
+1. Order virtual circuit in Equinix Fabric Portal
+2. Select Cloudflare as destination
+3. Choose facility
+4. Send details to CF account team
+5. CF accepts in portal
+6. Configure BGP
+
+**No API automation** – partner portals managed separately.
+
+## Failover & Security
+
+**Failover Best Practices:**
+
+- Use BGP local preferences for priority
+- Configure BFD for fast detection (v1)
+- Test regularly with traffic shift
+- Document runbooks
+
+**Security:**
+
+- BGP password authentication
+- BGP route filtering
+- Monitor unexpected routes
+- Magic Firewall for DDoS/threats
+- Minimum API token permissions
+- Rotate credentials periodically
+
+## Decision Matrix
+
+| Requirement        | Recommended |
+| ------------------ | ----------- |
+| Collocated with CF | Direct      |
+| Not collocated     | Partner     |
+| AWS/GCP workloads  | Cloud       |
+| 1500 MTU both ways | v2          |
+| VLAN tagging       | v1          |
+| Public peering     | v1          |
+| Simplest config    | v2          |
+| BFD fast failover  | v1          |
+| LACP bundling      | v1          |
+
+## Resources
+
+- [Magic Transit Docs](https://developers.cloudflare.com/magic-transit/)
+- [Magic WAN Docs](https://developers.cloudflare.com/magic-wan/)
+- [Argo Smart Routing](https://developers.cloudflare.com/argo/)

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

@@ -0,0 +1,93 @@
+# Cloudflare Observability Skill Reference
+
+**Purpose**: Comprehensive guidance for implementing observability in Cloudflare Workers, covering traces, logs, metrics, and analytics.
+
+**Scope**: Cloudflare Observability features ONLY - Workers Logs, Traces, Analytics Engine, Logpush, Metrics & Analytics, and OpenTelemetry exports.
+
+---
+
+## Decision Tree: Which File to Load?
+
+Use this to route to the correct file without loading all content:
+
+```
+├─ "How do I enable/configure X?"           → configuration.md
+├─ "What's the API/method/binding for X?"   → api.md
+├─ "How do I implement X pattern?"          → patterns.md
+│   ├─ Usage tracking/billing               → patterns.md
+│   ├─ Error tracking                       → patterns.md
+│   ├─ Performance monitoring               → patterns.md
+│   ├─ Multi-tenant tracking                → patterns.md
+│   ├─ Tail Worker filtering                → patterns.md
+│   └─ OpenTelemetry export                 → patterns.md
+└─ "Why isn't X working?" / "Limits?"       → gotchas.md
+```
+
+## Reading Order
+
+Load files in this order based on task:
+
+| Task Type             | Load Order                        | Reason                             |
+| --------------------- | --------------------------------- | ---------------------------------- |
+| **Initial setup**     | configuration.md → gotchas.md     | Setup first, avoid pitfalls        |
+| **Implement feature** | patterns.md → api.md → gotchas.md | Pattern → API details → edge cases |
+| **Debug issue**       | gotchas.md → configuration.md     | Common issues first                |
+| **Query data**        | api.md → patterns.md              | API syntax → query examples        |
+
+## Product Overview
+
+### Workers Logs
+
+- **What:** Console output from Workers (console.log/warn/error)
+- **Access:** Dashboard (Real-time Logs), Logpush, Tail Workers
+- **Cost:** Free (included with all Workers)
+- **Retention:** Real-time only (no historical storage in dashboard)
+
+### Workers Traces
+
+- **What:** Execution traces with timing, CPU usage, outcome
+- **Access:** Dashboard (Workers Analytics → Traces), Logpush
+- **Cost:** $0.10/1M spans (GA pricing starts March 1, 2026), 10M free/month
+- **Retention:** 14 days included
+
+### Analytics Engine
+
+- **What:** High-cardinality event storage and SQL queries
+- **Access:** SQL API, Dashboard (Analytics → Analytics Engine)
+- **Cost:** $0.25/1M writes beyond 10M free/month
+- **Retention:** 90 days (configurable up to 1 year)
+
+### Tail Workers
+
+- **What:** Workers that receive logs/traces from other Workers
+- **Use Cases:** Log filtering, transformation, external export
+- **Cost:** Standard Workers pricing
+
+### Logpush
+
+- **What:** Stream logs to external storage (S3, R2, Datadog, etc.)
+- **Access:** Dashboard, API
+- **Cost:** Requires Business/Enterprise plan
+
+## Pricing Summary (2026)
+
+| Feature          | Free Tier        | Cost Beyond Free Tier | Plan Requirement                 |
+| ---------------- | ---------------- | --------------------- | -------------------------------- |
+| Workers Logs     | Unlimited        | Free                  | Any                              |
+| Workers Traces   | 10M spans/month  | $0.10/1M spans        | Paid Workers (GA: March 1, 2026) |
+| Analytics Engine | 10M writes/month | $0.25/1M writes       | Paid Workers                     |
+| Logpush          | N/A              | Included in plan      | Business/Enterprise              |
+
+## In This Reference
+
+- **[configuration.md](configuration.md)** - Setup, deployment, configuration (Logs, Traces, Analytics Engine, Tail Workers, Logpush)
+- **[api.md](api.md)** - API endpoints, methods, interfaces (GraphQL, SQL, bindings, types)
+- **[patterns.md](patterns.md)** - Common patterns, use cases, examples (billing, monitoring, error tracking, exports)
+- **[gotchas.md](gotchas.md)** - Troubleshooting, best practices, limitations (common errors, performance gotchas, pricing)
+
+## See Also
+
+- [Cloudflare Workers Docs](https://developers.cloudflare.com/workers/)
+- [Analytics Engine Docs](https://developers.cloudflare.com/analytics/analytics-engine/)
+- [Workers Traces Docs](https://developers.cloudflare.com/workers/observability/traces/)
+- [GraphQL Analytics API Reference](../graphql-api/) - Query Workers metrics, HTTP analytics, and 70+ other datasets via GraphQL

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

@@ -0,0 +1,168 @@
+## API Reference
+
+### GraphQL Analytics API
+
+**Endpoint**: `https://api.cloudflare.com/client/v4/graphql`
+
+**Query Workers Metrics**:
+
+```graphql
+query {
+  viewer {
+    accounts(filter: { accountTag: $accountId }) {
+      workersInvocationsAdaptive(
+        limit: 100
+        filter: {
+          datetime_geq: "2025-01-01T00:00:00Z"
+          datetime_leq: "2025-01-31T23:59:59Z"
+          scriptName: "my-worker"
+        }
+      ) {
+        sum {
+          requests
+          errors
+          subrequests
+        }
+        quantiles {
+          cpuTimeP50
+          cpuTimeP99
+          wallTimeP50
+          wallTimeP99
+        }
+      }
+    }
+  }
+}
+```
+
+### Analytics Engine SQL API
+
+**Endpoint**: `https://api.cloudflare.com/client/v4/accounts/{account_id}/analytics_engine/sql`
+
+**Authentication**: `Authorization: Bearer <API_TOKEN>` (Account Analytics Read permission)
+
+**Common Queries**:
+
+```sql
+-- List all datasets
+SHOW TABLES;
+
+-- Time-series aggregation (5-minute buckets)
+SELECT
+  intDiv(toUInt32(timestamp), 300) * 300 AS time_bucket,
+  blob1 AS endpoint,
+  SUM(_sample_interval) AS total_requests,
+  AVG(double1) AS avg_response_time_ms
+FROM api_metrics
+WHERE timestamp >= NOW() - INTERVAL '24' HOUR
+GROUP BY time_bucket, endpoint
+ORDER BY time_bucket DESC;
+
+-- Top customers by usage
+SELECT
+  index1 AS customer_id,
+  SUM(_sample_interval * double1) AS total_api_calls,
+  AVG(double2) AS avg_response_time_ms
+FROM api_usage
+WHERE timestamp >= NOW() - INTERVAL '7' DAY
+GROUP BY customer_id
+ORDER BY total_api_calls DESC
+LIMIT 100;
+
+-- Error rate analysis
+SELECT
+  blob1 AS error_type,
+  COUNT(*) AS occurrences,
+  MAX(timestamp) AS last_seen
+FROM error_tracking
+WHERE timestamp >= NOW() - INTERVAL '1' HOUR
+GROUP BY error_type
+ORDER BY occurrences DESC;
+```
+
+### Console Logging API
+
+**Methods**:
+
+```typescript
+// Standard methods (all appear in Workers Logs)
+console.log('info message')
+console.info('info message')
+console.warn('warning message')
+console.error('error message')
+console.debug('debug message')
+
+// Structured logging (recommended)
+console.log({
+  level: 'info',
+  user_id: '123',
+  action: 'checkout',
+  amount: 99.99,
+  currency: 'USD',
+})
+```
+
+**Log Levels**: All console methods produce logs; use structured fields for filtering:
+
+```typescript
+console.log({
+  level: 'error',
+  message: 'Payment failed',
+  error_code: 'CARD_DECLINED',
+})
+```
+
+### Analytics Engine Binding Types
+
+```typescript
+interface AnalyticsEngineDataset {
+  writeDataPoint(event: AnalyticsEngineDataPoint): void
+}
+
+interface AnalyticsEngineDataPoint {
+  // Indexed strings (use for filtering/grouping)
+  indexes?: string[]
+
+  // Non-indexed strings (metadata, IDs, URLs)
+  blobs?: string[]
+
+  // Numeric values (counts, durations, amounts)
+  doubles?: number[]
+}
+```
+
+**Field Limits**:
+
+- Max 20 indexes
+- Max 20 blobs
+- Max 20 doubles
+- Max 25 `writeDataPoint` calls per request
+
+### Tail Consumer Event Type
+
+```typescript
+interface TraceItem {
+  event: TraceEvent
+  logs: TraceLog[]
+  exceptions: TraceException[]
+  scriptName?: string
+}
+
+interface TraceEvent {
+  outcome: 'ok' | 'exception' | 'exceededCpu' | 'exceededMemory' | 'unknown'
+  cpuTime: number // microseconds
+  wallTime: number // microseconds
+}
+
+interface TraceLog {
+  timestamp: number
+  level: 'log' | 'info' | 'debug' | 'warn' | 'error'
+  message: any // string or structured object
+}
+
+interface TraceException {
+  name: string
+  message: string
+  timestamp: number
+}
+```