@girardmedia/bootspring 3.3.2 → 3.4.0

package/assets/skills/load-testing.md

@@ -0,0 +1,303 @@
+---
+name: load-testing
+description: Load testing patterns with k6 and Artillery for scenarios, thresholds, spike testing, stress testing, and reporting.
+---
+
+# Load Testing Patterns
+
+## When to Use
+Run load tests before major releases, after infrastructure changes, and regularly in CI to catch performance regressions. Use k6 for script-based testing with built-in metrics, or Artillery for YAML-based declarative scenarios. These patterns cover gradual ramp-up, spike testing, soak testing, and threshold-based pass/fail criteria. Test against staging environments that mirror production, never against production directly.
+
+## How It Works
+
+### k6 Basic Load Test
+
+```javascript
+// load-tests/api-load.js
+import http from 'k6/http';
+import { check, sleep } from 'k6';
+import { Rate, Trend } from 'k6/metrics';
+
+const errorRate = new Rate('errors');
+const latency = new Trend('api_latency');
+
+export const options = {
+  stages: [
+    { duration: '1m', target: 20 },   // ramp up to 20 VUs
+    { duration: '3m', target: 20 },   // hold at 20 VUs
+    { duration: '2m', target: 50 },   // ramp up to 50 VUs
+    { duration: '3m', target: 50 },   // hold at 50 VUs
+    { duration: '1m', target: 0 },    // ramp down
+  ],
+  thresholds: {
+    http_req_duration: ['p(95)<500', 'p(99)<1000'],  // 95th < 500ms, 99th < 1s
+    http_req_failed: ['rate<0.01'],                    // error rate < 1%
+    errors: ['rate<0.05'],                              // custom error rate < 5%
+  },
+};
+
+const BASE_URL = __ENV.BASE_URL || 'http://localhost:3000';
+
+export default function () {
+  // GET endpoint
+  const listRes = http.get(`${BASE_URL}/api/posts`, {
+    headers: { Authorization: `Bearer ${__ENV.TOKEN}` },
+    tags: { name: 'GET /api/posts' },
+  });
+
+  check(listRes, {
+    'GET /api/posts status 200': (r) => r.status === 200,
+    'GET /api/posts has items': (r) => JSON.parse(r.body).length > 0,
+  }) || errorRate.add(1);
+
+  latency.add(listRes.timings.duration);
+
+  sleep(1);
+
+  // POST endpoint
+  const createRes = http.post(
+    `${BASE_URL}/api/posts`,
+    JSON.stringify({ title: `Post ${Date.now()}`, body: 'Load test content' }),
+    {
+      headers: {
+        'Content-Type': 'application/json',
+        Authorization: `Bearer ${__ENV.TOKEN}`,
+      },
+      tags: { name: 'POST /api/posts' },
+    }
+  );
+
+  check(createRes, {
+    'POST /api/posts status 201': (r) => r.status === 201,
+  }) || errorRate.add(1);
+
+  sleep(1);
+}
+```
+
+### k6 Spike Test
+
+```javascript
+// load-tests/spike-test.js
+export const options = {
+  stages: [
+    { duration: '30s', target: 10 },   // warm up
+    { duration: '10s', target: 200 },   // spike to 200 VUs
+    { duration: '1m', target: 200 },    // hold spike
+    { duration: '10s', target: 10 },    // drop back
+    { duration: '2m', target: 10 },     // recover
+    { duration: '30s', target: 0 },     // cool down
+  ],
+  thresholds: {
+    http_req_duration: ['p(95)<2000'],  // allow higher latency during spike
+    http_req_failed: ['rate<0.05'],     // allow up to 5% errors during spike
+  },
+};
+```
+
+### k6 Soak Test
+
+```javascript
+// load-tests/soak-test.js
+export const options = {
+  stages: [
+    { duration: '2m', target: 30 },    // ramp up
+    { duration: '4h', target: 30 },    // hold for 4 hours
+    { duration: '2m', target: 0 },     // ramp down
+  ],
+  thresholds: {
+    http_req_duration: ['p(95)<500'],
+    http_req_failed: ['rate<0.01'],
+  },
+};
+
+// Soak tests catch:
+// - Memory leaks (watch RSS growth)
+// - Connection pool exhaustion
+// - Log file growth
+// - Certificate/token expiry during test
+```
+
+### Artillery YAML Scenario
+
+```yaml
+# load-tests/artillery.yml
+config:
+  target: "http://localhost:3000"
+  phases:
+    - duration: 60
+      arrivalRate: 5
+      name: "Warm up"
+    - duration: 180
+      arrivalRate: 20
+      name: "Sustained load"
+    - duration: 60
+      arrivalRate: 50
+      name: "Peak load"
+  defaults:
+    headers:
+      Content-Type: "application/json"
+  plugins:
+    expect: {}
+  ensure:
+    p95: 500
+    maxErrorRate: 1
+
+scenarios:
+  - name: "Browse and create"
+    weight: 70
+    flow:
+      - get:
+          url: "/api/posts"
+          expect:
+            - statusCode: 200
+          capture:
+            - json: "$[0].id"
+              as: "postId"
+      - think: 2
+      - get:
+          url: "/api/posts/{{ postId }}"
+          expect:
+            - statusCode: 200
+
+  - name: "Create post"
+    weight: 30
+    flow:
+      - post:
+          url: "/api/posts"
+          json:
+            title: "Load test {{ $randomString() }}"
+            body: "Content for load testing"
+          expect:
+            - statusCode: 201
+```
+
+### Custom k6 Scenario with Lifecycle
+
+```javascript
+// load-tests/realistic-scenario.js
+import http from 'k6/http';
+import { check, group, sleep } from 'k6';
+import { SharedArray } from 'k6/data';
+
+// Load test data once (shared across VUs)
+const users = new SharedArray('users', function () {
+  return JSON.parse(open('./test-users.json'));
+});
+
+export function setup() {
+  // Run once before all VUs
+  const res = http.post(`${BASE_URL}/api/auth/login`, JSON.stringify({
+    email: 'admin@test.com',
+    password: 'admin123',
+  }), { headers: { 'Content-Type': 'application/json' } });
+
+  return { adminToken: JSON.parse(res.body).token };
+}
+
+export default function (data) {
+  const user = users[__VU % users.length];
+
+  group('Authentication', () => {
+    const loginRes = http.post(`${BASE_URL}/api/auth/login`, JSON.stringify({
+      email: user.email,
+      password: user.password,
+    }), { headers: { 'Content-Type': 'application/json' } });
+
+    check(loginRes, { 'login successful': (r) => r.status === 200 });
+
+    const token = JSON.parse(loginRes.body).token;
+    const headers = { Authorization: `Bearer ${token}`, 'Content-Type': 'application/json' };
+
+    group('Browse content', () => {
+      const posts = http.get(`${BASE_URL}/api/posts`, { headers });
+      check(posts, { 'posts loaded': (r) => r.status === 200 });
+      sleep(2);
+    });
+
+    group('Create content', () => {
+      const newPost = http.post(`${BASE_URL}/api/posts`, JSON.stringify({
+        title: `VU${__VU} Post ${__ITER}`,
+        body: 'Load test generated content',
+      }), { headers });
+      check(newPost, { 'post created': (r) => r.status === 201 });
+    });
+  });
+
+  sleep(Math.random() * 3 + 1); // random think time 1-4s
+}
+
+export function teardown(data) {
+  // Cleanup after all VUs complete
+  http.del(`${BASE_URL}/api/test/cleanup`, null, {
+    headers: { Authorization: `Bearer ${data.adminToken}` },
+  });
+}
+```
+
+### CI Integration and Reporting
+
+```yaml
+# .github/workflows/load-test.yml
+name: Load Test
+on:
+  schedule:
+    - cron: '0 2 * * 1'  # weekly Monday 2am
+  workflow_dispatch:
+
+jobs:
+  load-test:
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+    services:
+      app:
+        image: myapp:latest
+        ports: ['3000:3000']
+    steps:
+      - uses: actions/checkout@v4
+      - uses: grafana/k6-action@v0.3.1
+        with:
+          filename: load-tests/api-load.js
+          flags: --out json=results.json
+        env:
+          BASE_URL: http://localhost:3000
+          TOKEN: ${{ secrets.LOAD_TEST_TOKEN }}
+      - uses: actions/upload-artifact@v4
+        with:
+          name: k6-results
+          path: results.json
+```
+
+### Analyzing Results
+
+```bash
+# Run k6 with JSON output
+k6 run --out json=results.json load-tests/api-load.js
+
+# Run k6 with summary export
+k6 run --summary-export=summary.json load-tests/api-load.js
+
+# Run Artillery with HTML report
+npx artillery run load-tests/artillery.yml --output report.json
+npx artillery report report.json --output report.html
+```
+
+## Examples
+
+| Test Type | VU Pattern | Purpose |
+|-----------|-----------|---------|
+| Load | 10 to 50 VUs, hold | Normal expected traffic |
+| Stress | Ramp to breaking point | Find maximum capacity |
+| Spike | Sudden jump to 10x | Test auto-scaling and recovery |
+| Soak | Constant 30 VUs for 4h | Memory leaks, resource exhaustion |
+| Breakpoint | Increment until failure | Absolute system limits |
+
+## Checklist
+- [ ] Thresholds set for p95 latency, p99 latency, and error rate
+- [ ] Test stages include ramp-up, hold, and ramp-down phases
+- [ ] `check()` validates response status and body content
+- [ ] Test data loaded via `SharedArray` to minimize memory per VU
+- [ ] Think time (`sleep()`) simulates realistic user behavior
+- [ ] Tests run against staging, never production
+- [ ] CI pipeline runs load tests on schedule with artifact upload
+- [ ] Spike and soak tests run before major releases

package/assets/skills/logging-observability.md

@@ -0,0 +1,228 @@
+---
+name: logging-observability
+description: Logging and observability patterns with structured logging, OpenTelemetry, distributed tracing, log levels, and dashboards.
+---
+
+# Logging and Observability
+
+## When to Use
+Apply to every production service. Observability is the ability to understand what your system is doing from its outputs. Use structured logging for searchable logs, OpenTelemetry for distributed tracing, metrics for dashboards and alerts, and correlation IDs to trace requests across services. Set this up before the first outage, not after.
+
+## How It Works
+
+### Structured Logging with Pino
+
+Never use `console.log` in production. Use structured JSON logs:
+
+```typescript
+import pino from "pino";
+
+const logger = pino({
+  level: process.env.LOG_LEVEL ?? "info",
+  formatters: {
+    level: (label) => ({ level: label }),
+  },
+  redact: ["req.headers.authorization", "password", "token"],
+  serializers: {
+    err: pino.stdSerializers.err,
+    req: pino.stdSerializers.req,
+    res: pino.stdSerializers.res,
+  },
+});
+
+// Structured log with context -- every field is searchable
+logger.info(
+  { userId: "u_123", orderId: "o_456", amount: 99.99 },
+  "Order created"
+);
+// Output: {"level":"info","time":1716700000,"userId":"u_123","orderId":"o_456",
+//          "amount":99.99,"msg":"Order created"}
+
+// Child logger inherits context
+const reqLogger = logger.child({ requestId: "req_abc", userId: "u_123" });
+reqLogger.info("Processing payment");
+// All logs from reqLogger include requestId and userId automatically
+```
+
+### Log Levels -- When to Use Each
+
+```typescript
+logger.fatal("Database connection lost, shutting down");     // process crash imminent
+logger.error({ err }, "Payment processing failed");          // operation failed, needs attention
+logger.warn("Rate limit approaching: 85% capacity");         // degraded, not broken yet
+logger.info("Order #456 shipped to customer");                // significant business events
+logger.debug({ query, params }, "Executing SQL");             // dev-only detail
+logger.trace({ headers }, "Incoming request headers");        // extremely verbose
+```
+
+Production runs at `info`. Set `debug` only for targeted troubleshooting.
+
+### Request Correlation Middleware
+
+```typescript
+import { randomUUID } from "crypto";
+import { AsyncLocalStorage } from "async_hooks";
+import { Request, Response, NextFunction } from "express";
+
+interface RequestContext {
+  requestId: string;
+  userId?: string;
+}
+
+const requestContext = new AsyncLocalStorage<RequestContext>();
+
+function correlationMiddleware(req: Request, res: Response, next: NextFunction) {
+  const requestId = (req.headers["x-request-id"] as string) ?? randomUUID();
+  res.setHeader("x-request-id", requestId);
+
+  const ctx: RequestContext = { requestId, userId: req.user?.id };
+  requestContext.run(ctx, () => {
+    const start = Date.now();
+    res.on("finish", () => {
+      logger.child(ctx).info({
+        method: req.method,
+        path: req.path,
+        statusCode: res.statusCode,
+        durationMs: Date.now() - start,
+      }, "Request completed");
+    });
+    next();
+  });
+}
+
+// Get logger anywhere in the call stack
+function getLogger() {
+  const ctx = requestContext.getStore();
+  return logger.child(ctx ?? {});
+}
+```
+
+### OpenTelemetry -- Distributed Tracing
+
+```typescript
+import { NodeSDK } from "@opentelemetry/sdk-node";
+import { getNodeAutoInstrumentations } from "@opentelemetry/auto-instrumentations-node";
+import { OTLPTraceExporter } from "@opentelemetry/exporter-trace-otlp-http";
+
+const sdk = new NodeSDK({
+  traceExporter: new OTLPTraceExporter({
+    url: process.env.OTEL_EXPORTER_OTLP_ENDPOINT ?? "http://localhost:4318/v1/traces",
+  }),
+  instrumentations: [
+    getNodeAutoInstrumentations({
+      "@opentelemetry/instrumentation-http": { enabled: true },
+      "@opentelemetry/instrumentation-express": { enabled: true },
+      "@opentelemetry/instrumentation-pg": { enabled: true },
+    }),
+  ],
+  serviceName: "order-service",
+});
+sdk.start();
+```
+
+Custom spans for business logic:
+
+```typescript
+import { trace, SpanStatusCode } from "@opentelemetry/api";
+
+const tracer = trace.getTracer("order-service");
+
+async function processOrder(order: Order) {
+  return tracer.startActiveSpan("processOrder", async (span) => {
+    span.setAttribute("order.id", order.id);
+    span.setAttribute("order.total", order.total);
+    try {
+      await validateOrder(order);
+      await chargePayment(order);
+      await sendConfirmation(order);
+      span.setStatus({ code: SpanStatusCode.OK });
+    } catch (err: any) {
+      span.setStatus({ code: SpanStatusCode.ERROR, message: err.message });
+      span.recordException(err);
+      throw err;
+    } finally {
+      span.end();
+    }
+  });
+}
+```
+
+### Prometheus Metrics
+
+```typescript
+import { Counter, Histogram, Registry } from "prom-client";
+
+const registry = new Registry();
+
+const httpDuration = new Histogram({
+  name: "http_request_duration_seconds",
+  help: "HTTP request duration in seconds",
+  labelNames: ["method", "route", "status"] as const,
+  buckets: [0.01, 0.05, 0.1, 0.5, 1, 5],
+  registers: [registry],
+});
+
+const httpTotal = new Counter({
+  name: "http_requests_total",
+  help: "Total HTTP requests",
+  labelNames: ["method", "route", "status"] as const,
+  registers: [registry],
+});
+
+function metricsMiddleware(req: Request, res: Response, next: NextFunction) {
+  const end = httpDuration.startTimer();
+  res.on("finish", () => {
+    const labels = {
+      method: req.method,
+      route: req.route?.path ?? req.path,
+      status: String(res.statusCode),
+    };
+    end(labels);
+    httpTotal.inc(labels);
+  });
+  next();
+}
+
+app.get("/metrics", async (_req, res) => {
+  res.set("Content-Type", registry.contentType);
+  res.end(await registry.metrics());
+});
+```
+
+### Health Check Endpoint
+
+```typescript
+app.get("/health", async (_req, res) => {
+  const checks = {
+    database: await checkDatabase().catch(() => false),
+    redis: await checkRedis().catch(() => false),
+    uptime: process.uptime(),
+    memoryMB: Math.round(process.memoryUsage().heapUsed / 1024 / 1024),
+  };
+  const healthy = checks.database && checks.redis;
+  res.status(healthy ? 200 : 503).json({
+    status: healthy ? "ok" : "degraded",
+    checks,
+  });
+});
+```
+
+## Examples
+
+| Signal | Tool | Use Case |
+|--------|------|----------|
+| Structured logs | Pino + ELK/Datadog | Search and filter by any field |
+| Distributed traces | OpenTelemetry + Jaeger | Follow request across services |
+| Metrics | Prometheus + Grafana | Dashboards, SLO tracking, alerts |
+| Correlation IDs | AsyncLocalStorage | Link logs per request |
+| Health checks | /health endpoint | Load balancer, K8s probes |
+
+## Checklist
+- [ ] All logs are structured JSON, not string concatenation
+- [ ] Sensitive data redacted from logs (tokens, passwords, PII)
+- [ ] Correlation ID propagated across all service calls
+- [ ] Log levels used correctly (fatal/error/warn/info/debug)
+- [ ] OpenTelemetry traces span critical business operations
+- [ ] Prometheus metrics track duration, error rate, throughput
+- [ ] Health check endpoint reports dependency status
+- [ ] Alerts configured for error rate and p99 latency thresholds