@cubis/foundry 0.3.10

package/Ai Agent Workflow/powers/monitoring-expert/steering/dashboards.md

@@ -0,0 +1,126 @@
+# Dashboards
+
+## RED Method (Request-focused)
+
+```
+Rate     - Requests per second
+Errors   - Failed requests per second
+Duration - Response time distribution
+```
+
+```promql
+# Rate
+sum(rate(http_requests_total[5m]))
+
+# Errors
+sum(rate(http_requests_total{status=~"5.."}[5m]))
+  /
+sum(rate(http_requests_total[5m]))
+
+# Duration (p95)
+histogram_quantile(0.95, rate(http_request_duration_seconds_bucket[5m]))
+```
+
+## USE Method (Resource-focused)
+
+```
+Utilization - % time resource is busy
+Saturation  - Queue depth, backlog
+Errors      - Error events
+```
+
+```promql
+# CPU Utilization
+100 - (avg(rate(node_cpu_seconds_total{mode="idle"}[5m])) * 100)
+
+# Memory Saturation
+node_memory_SwapTotal_bytes - node_memory_SwapFree_bytes
+
+# Disk Errors
+rate(node_disk_io_time_weighted_seconds_total[5m])
+```
+
+## Dashboard Structure
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                    SERVICE OVERVIEW                         │
+│  Request Rate │ Error Rate │ p50 Latency │ p99 Latency     │
+├─────────────────────────────────────────────────────────────┤
+│                    REQUEST METRICS                          │
+│  [Graph: Requests/s by endpoint]                           │
+│  [Graph: Error rate over time]                             │
+├─────────────────────────────────────────────────────────────┤
+│                    LATENCY METRICS                          │
+│  [Heatmap: Latency distribution]                           │
+│  [Graph: p50, p95, p99 over time]                          │
+├─────────────────────────────────────────────────────────────┤
+│                    INFRASTRUCTURE                           │
+│  CPU │ Memory │ Disk │ Network                             │
+└─────────────────────────────────────────────────────────────┘
+```
+
+## Key Panels
+
+### Stat Panel (Single Value)
+
+```promql
+# Current RPS
+sum(rate(http_requests_total[5m]))
+
+# Error percentage
+sum(rate(http_requests_total{status=~"5.."}[5m]))
+  /
+sum(rate(http_requests_total[5m])) * 100
+```
+
+### Time Series
+
+```promql
+# Requests by status
+sum by (status) (rate(http_requests_total[5m]))
+
+# Latency percentiles
+histogram_quantile(0.50, rate(http_request_duration_seconds_bucket[5m]))
+histogram_quantile(0.95, rate(http_request_duration_seconds_bucket[5m]))
+histogram_quantile(0.99, rate(http_request_duration_seconds_bucket[5m]))
+```
+
+### Table
+
+```promql
+# Top endpoints by error rate
+topk(10,
+  sum by (path) (rate(http_requests_total{status=~"5.."}[5m]))
+  /
+  sum by (path) (rate(http_requests_total[5m]))
+)
+```
+
+## Business Metrics Dashboard
+
+```promql
+# Orders per minute
+sum(rate(orders_created_total[5m])) * 60
+
+# Revenue (if tracked)
+sum(increase(order_value_dollars_sum[1h]))
+
+# Active users (gauge)
+active_users_total
+```
+
+## Quick Reference
+
+| Method | Focus | Metrics |
+|--------|-------|---------|
+| RED | Services | Rate, Errors, Duration |
+| USE | Resources | Utilization, Saturation, Errors |
+
+| Panel Type | Use Case |
+|------------|----------|
+| Stat | Single KPI |
+| Time Series | Trends over time |
+| Heatmap | Latency distribution |
+| Table | Top N, details |
+| Gauge | Current vs threshold |

package/Ai Agent Workflow/powers/monitoring-expert/steering/opentelemetry.md

@@ -0,0 +1,123 @@
+# OpenTelemetry Tracing
+
+## Node.js Setup
+
+```typescript
+import { NodeSDK } from '@opentelemetry/sdk-node';
+import { getNodeAutoInstrumentations } from '@opentelemetry/auto-instrumentations-node';
+import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-http';
+import { Resource } from '@opentelemetry/resources';
+import { SemanticResourceAttributes } from '@opentelemetry/semantic-conventions';
+
+const sdk = new NodeSDK({
+  resource: new Resource({
+    [SemanticResourceAttributes.SERVICE_NAME]: 'my-service',
+    [SemanticResourceAttributes.SERVICE_VERSION]: '1.0.0',
+  }),
+  traceExporter: new OTLPTraceExporter({
+    url: 'http://jaeger:4318/v1/traces',
+  }),
+  instrumentations: [getNodeAutoInstrumentations()],
+});
+
+sdk.start();
+```
+
+## Manual Spans
+
+```typescript
+import { trace, SpanStatusCode } from '@opentelemetry/api';
+
+const tracer = trace.getTracer('my-service');
+
+async function processOrder(orderId: string) {
+  return tracer.startActiveSpan('processOrder', async (span) => {
+    span.setAttribute('order.id', orderId);
+
+    try {
+      // Child span for database
+      await tracer.startActiveSpan('db.getOrder', async (dbSpan) => {
+        const order = await db.orders.findById(orderId);
+        dbSpan.setAttribute('db.rows_affected', 1);
+        dbSpan.end();
+        return order;
+      });
+
+      // Child span for external API
+      await tracer.startActiveSpan('api.processPayment', async (apiSpan) => {
+        await paymentService.process(order);
+        apiSpan.end();
+      });
+
+      span.setStatus({ code: SpanStatusCode.OK });
+    } catch (error) {
+      span.setStatus({
+        code: SpanStatusCode.ERROR,
+        message: error.message,
+      });
+      span.recordException(error);
+      throw error;
+    } finally {
+      span.end();
+    }
+  });
+}
+```
+
+## Context Propagation
+
+```typescript
+import { propagation, context } from '@opentelemetry/api';
+
+// Extract from incoming request
+app.use((req, res, next) => {
+  const ctx = propagation.extract(context.active(), req.headers);
+  context.with(ctx, next);
+});
+
+// Inject into outgoing request
+async function callExternalService() {
+  const headers = {};
+  propagation.inject(context.active(), headers);
+
+  await fetch('http://other-service/api', { headers });
+}
+```
+
+## Python Setup
+
+```python
+from opentelemetry import trace
+from opentelemetry.sdk.trace import TracerProvider
+from opentelemetry.sdk.trace.export import BatchSpanProcessor
+from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter
+
+provider = TracerProvider()
+processor = BatchSpanProcessor(OTLPSpanExporter(endpoint="http://jaeger:4318/v1/traces"))
+provider.add_span_processor(processor)
+trace.set_tracer_provider(provider)
+
+tracer = trace.get_tracer(__name__)
+
+def process_order(order_id: str):
+    with tracer.start_as_current_span("process_order") as span:
+        span.set_attribute("order.id", order_id)
+        # ... process order
+```
+
+## Quick Reference
+
+| Concept | Purpose |
+|---------|---------|
+| Span | Single operation |
+| Trace | Full request flow |
+| Context | Correlation across services |
+| Attributes | Metadata on spans |
+| Events | Timestamped logs in span |
+
+| Attribute | Example |
+|-----------|---------|
+| `http.method` | GET, POST |
+| `http.status_code` | 200, 500 |
+| `db.system` | postgresql |
+| `db.statement` | SELECT ... |

package/Ai Agent Workflow/powers/monitoring-expert/steering/performance-testing.md

@@ -0,0 +1,269 @@
+# Performance Testing
+
+## Load Testing with k6
+
+```javascript
+import http from 'k6/http';
+import { check, sleep } from 'k6';
+import { Rate } from 'k6/metrics';
+
+const errorRate = new Rate('errors');
+
+export const options = {
+  stages: [
+    { duration: '2m', target: 100 },  // Ramp-up to 100 users
+    { duration: '5m', target: 100 },  // Stay at 100 users
+    { duration: '2m', target: 200 },  // Ramp-up to 200 users
+    { duration: '5m', target: 200 },  // Stay at 200 users
+    { duration: '2m', target: 0 },    // Ramp-down to 0 users
+  ],
+  thresholds: {
+    http_req_duration: ['p(95)<500', 'p(99)<1000'],
+    http_req_failed: ['rate<0.01'],
+    errors: ['rate<0.1'],
+  },
+};
+
+export default function () {
+  const res = http.get('https://api.example.com/products');
+
+  check(res, {
+    'status is 200': (r) => r.status === 200,
+    'response time < 500ms': (r) => r.timings.duration < 500,
+  }) || errorRate.add(1);
+
+  sleep(1);
+}
+```
+
+## Test Types
+
+### Load Test
+```javascript
+// Gradual ramp-up to expected production load
+export const options = {
+  stages: [
+    { duration: '5m', target: 100 },
+    { duration: '30m', target: 100 },
+    { duration: '5m', target: 0 },
+  ],
+};
+```
+
+### Stress Test
+```javascript
+// Push beyond normal capacity to find breaking point
+export const options = {
+  stages: [
+    { duration: '2m', target: 100 },
+    { duration: '5m', target: 200 },
+    { duration: '5m', target: 300 },
+    { duration: '5m', target: 400 },
+    { duration: '2m', target: 0 },
+  ],
+};
+```
+
+### Spike Test
+```javascript
+// Sudden increase in load
+export const options = {
+  stages: [
+    { duration: '1m', target: 100 },
+    { duration: '30s', target: 1000 }, // Spike
+    { duration: '3m', target: 100 },
+    { duration: '1m', target: 0 },
+  ],
+};
+```
+
+### Soak Test
+```javascript
+// Extended duration at normal load
+export const options = {
+  stages: [
+    { duration: '5m', target: 100 },
+    { duration: '8h', target: 100 },  // Long duration
+    { duration: '5m', target: 0 },
+  ],
+};
+```
+
+## Artillery.io
+
+```yaml
+# load-test.yml
+config:
+  target: 'https://api.example.com'
+  phases:
+    - duration: 60
+      arrivalRate: 10
+      name: "Warm up"
+    - duration: 300
+      arrivalRate: 50
+      name: "Sustained load"
+
+  processor: "./custom-functions.js"
+
+  variables:
+    userId:
+      - "user1"
+      - "user2"
+
+scenarios:
+  - name: "Product browsing"
+    weight: 70
+    flow:
+      - get:
+          url: "/products"
+      - think: 2
+      - get:
+          url: "/products/{{ $randomNumber(1, 100) }}"
+
+  - name: "Checkout"
+    weight: 30
+    flow:
+      - post:
+          url: "/cart"
+          json:
+            productId: "{{ $randomNumber(1, 100) }}"
+      - post:
+          url: "/checkout"
+          json:
+            userId: "{{ userId }}"
+```
+
+## Locust (Python)
+
+```python
+from locust import HttpUser, task, between
+
+class WebsiteUser(HttpUser):
+    wait_time = between(1, 3)
+
+    @task(3)
+    def view_products(self):
+        self.client.get("/products")
+
+    @task(1)
+    def view_product(self):
+        product_id = random.randint(1, 100)
+        self.client.get(f"/products/{product_id}")
+
+    @task(1)
+    def create_order(self):
+        self.client.post("/orders", json={
+            "product_id": random.randint(1, 100),
+            "quantity": random.randint(1, 5)
+        })
+
+    def on_start(self):
+        # Login or setup
+        self.client.post("/login", json={
+            "username": "test",
+            "password": "test"
+        })
+```
+
+## JMeter Thread Groups
+
+```xml
+<!-- Basic HTTP Request -->
+<ThreadGroup>
+  <stringProp name="ThreadGroup.num_threads">100</stringProp>
+  <stringProp name="ThreadGroup.ramp_time">60</stringProp>
+  <stringProp name="ThreadGroup.duration">300</stringProp>
+  <boolProp name="ThreadGroup.scheduler">true</boolProp>
+</ThreadGroup>
+```
+
+## Performance Metrics to Track
+
+```javascript
+// k6 custom metrics
+import { Counter, Trend, Gauge } from 'k6/metrics';
+
+const checkoutDuration = new Trend('checkout_duration');
+const cartSize = new Gauge('cart_size');
+const orderCounter = new Counter('orders_created');
+
+export default function () {
+  const startTime = Date.now();
+
+  const res = http.post('https://api.example.com/checkout', payload);
+
+  checkoutDuration.add(Date.now() - startTime);
+  orderCounter.add(1);
+  cartSize.add(payload.items.length);
+}
+```
+
+## Test Scenario Design
+
+```javascript
+// Realistic user journey
+import { scenario } from 'k6/execution';
+
+export const options = {
+  scenarios: {
+    browser_users: {
+      executor: 'ramping-vus',
+      startVUs: 0,
+      stages: [
+        { duration: '5m', target: 100 },
+        { duration: '10m', target: 100 },
+      ],
+      gracefulRampDown: '30s',
+    },
+    api_users: {
+      executor: 'constant-arrival-rate',
+      rate: 50,
+      timeUnit: '1s',
+      duration: '15m',
+      preAllocatedVUs: 100,
+    },
+  },
+};
+
+export default function () {
+  // Homepage
+  http.get('https://example.com/');
+  sleep(Math.random() * 3);
+
+  // Search
+  http.get('https://example.com/search?q=laptop');
+  sleep(Math.random() * 5);
+
+  // Product page
+  http.get('https://example.com/products/123');
+  sleep(Math.random() * 10);
+
+  // Add to cart (30% conversion)
+  if (Math.random() < 0.3) {
+    http.post('https://example.com/cart', { productId: 123 });
+  }
+}
+```
+
+## Quick Reference
+
+| Test Type | Purpose | Duration |
+|-----------|---------|----------|
+| Load | Normal capacity | 30m - 2h |
+| Stress | Find limits | 1h - 4h |
+| Spike | Sudden traffic | 15m - 30m |
+| Soak | Memory leaks | 4h - 24h |
+
+| Tool | Language | Best For |
+|------|----------|----------|
+| k6 | JavaScript | API testing, CI/CD |
+| Artillery | YAML/JS | Simple scenarios |
+| Locust | Python | Complex scenarios |
+| JMeter | GUI/XML | Legacy systems |
+
+| Metric | Target |
+|--------|--------|
+| p95 latency | < 500ms |
+| p99 latency | < 1s |
+| Error rate | < 1% |
+| RPS | 10x normal |

package/Ai Agent Workflow/powers/monitoring-expert/steering/prometheus-metrics.md

@@ -0,0 +1,136 @@
+# Prometheus Metrics
+
+## Metric Types
+
+```typescript
+import { Registry, Counter, Histogram, Gauge, Summary } from 'prom-client';
+
+const register = new Registry();
+
+// Counter - cumulative, only increases
+const httpRequests = new Counter({
+  name: 'http_requests_total',
+  help: 'Total HTTP requests',
+  labelNames: ['method', 'path', 'status'],
+  registers: [register],
+});
+
+// Histogram - distribution with buckets
+const httpDuration = new Histogram({
+  name: 'http_request_duration_seconds',
+  help: 'HTTP request duration in seconds',
+  labelNames: ['method', 'path'],
+  buckets: [0.01, 0.05, 0.1, 0.5, 1, 5],
+  registers: [register],
+});
+
+// Gauge - point-in-time value, can go up/down
+const activeConnections = new Gauge({
+  name: 'active_connections',
+  help: 'Number of active connections',
+  registers: [register],
+});
+
+// Summary - similar to histogram with percentiles
+const responseSummary = new Summary({
+  name: 'http_response_size_bytes',
+  help: 'HTTP response size',
+  percentiles: [0.5, 0.9, 0.99],
+  registers: [register],
+});
+```
+
+## HTTP Middleware
+
+```typescript
+app.use((req, res, next) => {
+  const end = httpDuration.startTimer({
+    method: req.method,
+    path: req.route?.path || req.path,
+  });
+
+  res.on('finish', () => {
+    httpRequests.inc({
+      method: req.method,
+      path: req.route?.path || req.path,
+      status: res.statusCode,
+    });
+    end();
+  });
+
+  next();
+});
+
+// Metrics endpoint
+app.get('/metrics', async (req, res) => {
+  res.set('Content-Type', register.contentType);
+  res.send(await register.metrics());
+});
+```
+
+## Business Metrics
+
+```typescript
+// Orders
+const ordersCreated = new Counter({
+  name: 'orders_created_total',
+  help: 'Total orders created',
+  labelNames: ['status', 'payment_method'],
+});
+
+const orderValue = new Histogram({
+  name: 'order_value_dollars',
+  help: 'Order value in dollars',
+  buckets: [10, 50, 100, 500, 1000],
+});
+
+// Usage
+ordersCreated.inc({ status: 'completed', payment_method: 'card' });
+orderValue.observe(order.total);
+```
+
+## Default Metrics
+
+```typescript
+import { collectDefaultMetrics } from 'prom-client';
+
+// Collect Node.js metrics (memory, CPU, etc.)
+collectDefaultMetrics({ register });
+```
+
+## Python (prometheus_client)
+
+```python
+from prometheus_client import Counter, Histogram, Gauge, generate_latest
+
+http_requests = Counter(
+    'http_requests_total',
+    'Total HTTP requests',
+    ['method', 'path', 'status']
+)
+
+http_duration = Histogram(
+    'http_request_duration_seconds',
+    'HTTP request duration',
+    ['method', 'path']
+)
+
+@app.get("/metrics")
+def metrics():
+    return Response(generate_latest(), media_type="text/plain")
+```
+
+## Quick Reference
+
+| Type | Use Case | Example |
+|------|----------|---------|
+| Counter | Cumulative totals | Requests, errors |
+| Gauge | Current value | Active users, queue size |
+| Histogram | Distributions | Response times |
+| Summary | Percentiles | Similar to histogram |
+
+| Naming | Convention |
+|--------|------------|
+| Unit suffix | `_seconds`, `_bytes`, `_total` |
+| Base unit | Use seconds, bytes (not ms, KB) |
+| Prefix | App/service name |