codecruise 0.1.0

package/config/skills/observability/SKILL.md

@@ -0,0 +1,430 @@
+---
+name: observability-patterns
+description: Logging, metrics, tracing, health checks, alerting
+keywords: [observability, logging, metrics, tracing, health check, prometheus, correlation id, pii redaction]
+---
+
+# Observability Standards
+
+Logging, metrics, and tracing for production systems.
+
+## Core Principle
+
+**Observability must never block, crash, or slow down the application.**
+
+Any exception inside logging/metrics logic must be isolated and safely handled.
+
+## Structured Logging
+
+### No Console.log
+
+```typescript
+// ❌ NEVER
+console.log('User created:', user);
+console.error('Failed to process:', error);
+
+// ✅ ALWAYS use structured logger
+logger.info('User created', { userId: user.id, email: redact(user.email) });
+logger.error('Failed to process', { error: serializeError(error), context });
+```
+
+### Required Log Fields
+
+Every log entry must include:
+
+```typescript
+interface LogEntry {
+  timestamp: string;        // ISO8601
+  level: LogLevel;          // debug, info, warn, error
+  correlationId: string;    // Request/trace ID
+  service: string;          // Service name
+  message: string;          // Human-readable message
+  context?: object;         // Structured data (sanitized)
+}
+
+type LogLevel = 'debug' | 'info' | 'warn' | 'error';
+```
+
+### Logger Implementation
+
+```typescript
+import { randomUUID } from 'crypto';
+
+interface Logger {
+  debug(message: string, context?: object): void;
+  info(message: string, context?: object): void;
+  warn(message: string, context?: object): void;
+  error(message: string, context?: object): void;
+  child(context: object): Logger;
+}
+
+class StructuredLogger implements Logger {
+  private baseContext: object;
+
+  constructor(
+    private service: string,
+    private correlationId: string = randomUUID(),
+    context: object = {}
+  ) {
+    this.baseContext = context;
+  }
+
+  private log(level: LogLevel, message: string, context?: object): void {
+    try {
+      const entry: LogEntry = {
+        timestamp: new Date().toISOString(),
+        level,
+        correlationId: this.correlationId,
+        service: this.service,
+        message,
+        ...(context && { context: { ...this.baseContext, ...context } }),
+      };
+
+      // Non-blocking write
+      process.stdout.write(JSON.stringify(entry) + '\n');
+    } catch {
+      // Never let logging crash the app
+    }
+  }
+
+  debug(message: string, context?: object): void {
+    if (process.env.LOG_LEVEL === 'debug') {
+      this.log('debug', message, context);
+    }
+  }
+
+  info(message: string, context?: object): void {
+    this.log('info', message, context);
+  }
+
+  warn(message: string, context?: object): void {
+    this.log('warn', message, context);
+  }
+
+  error(message: string, context?: object): void {
+    this.log('error', message, context);
+  }
+
+  child(context: object): Logger {
+    return new StructuredLogger(
+      this.service,
+      this.correlationId,
+      { ...this.baseContext, ...context }
+    );
+  }
+}
+```
+
+### Correlation IDs
+
+Every request gets a correlation ID that flows through all operations.
+
+```typescript
+// Middleware to extract/generate correlation ID
+function correlationMiddleware(req: Request, res: Response, next: NextFunction) {
+  const correlationId = req.headers['x-correlation-id'] as string || randomUUID();
+
+  // Attach to request
+  req.correlationId = correlationId;
+
+  // Include in response
+  res.setHeader('x-correlation-id', correlationId);
+
+  // Create request-scoped logger
+  req.logger = new StructuredLogger('api', correlationId, {
+    method: req.method,
+    path: req.path,
+    userAgent: req.headers['user-agent'],
+  });
+
+  next();
+}
+
+// Pass through to downstream services
+async function callExternalService(req: Request, payload: unknown) {
+  return fetch('https://api.external.com/endpoint', {
+    method: 'POST',
+    headers: {
+      'Content-Type': 'application/json',
+      'x-correlation-id': req.correlationId, // Propagate!
+    },
+    body: JSON.stringify(payload),
+  });
+}
+```
+
+### Log Levels
+
+| Level | When to Use |
+|-------|-------------|
+| `debug` | Development troubleshooting, detailed flow |
+| `info` | Business events, state changes, milestones |
+| `warn` | Recoverable issues, degraded state, approaching limits |
+| `error` | Failures requiring attention, unhandled exceptions |
+
+```typescript
+// DEBUG: Detailed internal state
+logger.debug('Cache lookup', { key, hit: !!result });
+
+// INFO: Business events
+logger.info('Order created', { orderId, userId, total });
+logger.info('Payment processed', { orderId, amount, provider });
+
+// WARN: Recoverable issues
+logger.warn('Rate limit approaching', { current: 980, limit: 1000 });
+logger.warn('Retry succeeded', { attempt: 3, operation: 'sendEmail' });
+
+// ERROR: Failures
+logger.error('Payment failed', { orderId, error: serializeError(err) });
+logger.error('Database connection lost', { error: serializeError(err) });
+```
+
+## PII Redaction
+
+**Never log sensitive data.**
+
+```typescript
+const SENSITIVE_FIELDS = ['password', 'token', 'secret', 'apiKey', 'ssn', 'creditCard'];
+
+function redact(value: string): string {
+  if (!value) return value;
+  if (value.length <= 4) return '****';
+  return value.slice(0, 2) + '****' + value.slice(-2);
+}
+
+function sanitize(obj: unknown): unknown {
+  if (typeof obj !== 'object' || obj === null) return obj;
+
+  const sanitized: Record<string, unknown> = {};
+
+  for (const [key, value] of Object.entries(obj)) {
+    if (SENSITIVE_FIELDS.some(f => key.toLowerCase().includes(f))) {
+      sanitized[key] = '[REDACTED]';
+    } else if (key.toLowerCase().includes('email')) {
+      sanitized[key] = redact(String(value));
+    } else if (typeof value === 'object') {
+      sanitized[key] = sanitize(value);
+    } else {
+      sanitized[key] = value;
+    }
+  }
+
+  return sanitized;
+}
+
+// Usage
+logger.info('User updated', sanitize({ userId, email, password }));
+// Output: { userId: '123', email: 'jo****om', password: '[REDACTED]' }
+```
+
+## Error Serialization
+
+```typescript
+function serializeError(error: unknown): object {
+  if (error instanceof AppError) {
+    return {
+      name: error.name,
+      code: error.code,
+      message: error.message,
+      statusCode: error.statusCode,
+      context: error.context,
+      stack: process.env.NODE_ENV !== 'production' ? error.stack : undefined,
+    };
+  }
+
+  if (error instanceof Error) {
+    return {
+      name: error.name,
+      message: error.message,
+      stack: process.env.NODE_ENV !== 'production' ? error.stack : undefined,
+    };
+  }
+
+  return { message: String(error) };
+}
+```
+
+## Metrics
+
+### Key Metrics to Track
+
+| Category | Metrics |
+|----------|---------|
+| **HTTP** | Request count, latency histogram, error rate by status |
+| **Database** | Query count, latency, connection pool usage |
+| **Cache** | Hit/miss ratio, latency |
+| **Queue** | Queue depth, processing time, error rate |
+| **Business** | Signups, orders, payments, conversions |
+
+### Implementation Pattern
+
+```typescript
+interface MetricsClient {
+  increment(metric: string, tags?: Record<string, string>): void;
+  gauge(metric: string, value: number, tags?: Record<string, string>): void;
+  histogram(metric: string, value: number, tags?: Record<string, string>): void;
+  timing(metric: string, duration: number, tags?: Record<string, string>): void;
+}
+
+// Request timing middleware
+function metricsMiddleware(metrics: MetricsClient) {
+  return (req: Request, res: Response, next: NextFunction) => {
+    const start = Date.now();
+
+    res.on('finish', () => {
+      const duration = Date.now() - start;
+      const tags = {
+        method: req.method,
+        path: req.route?.path || 'unknown',
+        status: String(res.statusCode),
+      };
+
+      metrics.timing('http.request.duration', duration, tags);
+      metrics.increment('http.request.count', tags);
+
+      if (res.statusCode >= 500) {
+        metrics.increment('http.request.error', tags);
+      }
+    });
+
+    next();
+  };
+}
+```
+
+## Distributed Tracing
+
+### Trace Context Propagation
+
+```typescript
+interface TraceContext {
+  traceId: string;
+  spanId: string;
+  parentSpanId?: string;
+}
+
+function extractTraceContext(headers: Record<string, string>): TraceContext {
+  // W3C Trace Context format
+  const traceparent = headers['traceparent'];
+
+  if (traceparent) {
+    const [, traceId, parentSpanId] = traceparent.split('-');
+    return {
+      traceId,
+      spanId: randomUUID().replace(/-/g, '').slice(0, 16),
+      parentSpanId,
+    };
+  }
+
+  return {
+    traceId: randomUUID().replace(/-/g, ''),
+    spanId: randomUUID().replace(/-/g, '').slice(0, 16),
+  };
+}
+
+function injectTraceContext(ctx: TraceContext): Record<string, string> {
+  return {
+    traceparent: `00-${ctx.traceId}-${ctx.spanId}-01`,
+  };
+}
+```
+
+### Sampling
+
+```typescript
+const SAMPLE_RATE = {
+  production: 0.1,   // 10%
+  staging: 1.0,      // 100%
+  development: 1.0,  // 100%
+};
+
+function shouldSample(): boolean {
+  const rate = SAMPLE_RATE[process.env.NODE_ENV as keyof typeof SAMPLE_RATE] || 0.1;
+  return Math.random() < rate;
+}
+```
+
+## Health Checks
+
+```typescript
+interface HealthCheck {
+  name: string;
+  check: () => Promise<{ healthy: boolean; message?: string }>;
+}
+
+const healthChecks: HealthCheck[] = [
+  {
+    name: 'database',
+    check: async () => {
+      try {
+        await db.raw('SELECT 1');
+        return { healthy: true };
+      } catch (error) {
+        return { healthy: false, message: 'Database unreachable' };
+      }
+    },
+  },
+  {
+    name: 'redis',
+    check: async () => {
+      try {
+        await redis.ping();
+        return { healthy: true };
+      } catch (error) {
+        return { healthy: false, message: 'Redis unreachable' };
+      }
+    },
+  },
+];
+
+// Health endpoint
+app.get('/health', async (req, res) => {
+  const results = await Promise.all(
+    healthChecks.map(async (hc) => ({
+      name: hc.name,
+      ...await hc.check(),
+    }))
+  );
+
+  const healthy = results.every(r => r.healthy);
+
+  res.status(healthy ? 200 : 503).json({
+    status: healthy ? 'healthy' : 'unhealthy',
+    checks: results,
+    timestamp: new Date().toISOString(),
+  });
+});
+
+// Liveness probe (basic)
+app.get('/health/live', (req, res) => {
+  res.status(200).json({ status: 'alive' });
+});
+
+// Readiness probe (full)
+app.get('/health/ready', async (req, res) => {
+  // Same as /health
+});
+```
+
+## Alerting Thresholds
+
+| Metric | Warning | Critical |
+|--------|---------|----------|
+| Error rate | > 1% | > 5% |
+| P99 latency | > 500ms | > 2s |
+| CPU usage | > 70% | > 90% |
+| Memory usage | > 70% | > 90% |
+| Queue depth | > 1000 | > 5000 |
+| DB connections | > 70% pool | > 90% pool |
+
+## Quality Checklist
+
+- [ ] Structured logger used (no console.log)
+- [ ] Correlation IDs on all requests
+- [ ] PII redacted from logs
+- [ ] Log levels used appropriately
+- [ ] Key metrics tracked
+- [ ] Health check endpoints exist
+- [ ] Trace context propagated
+- [ ] Errors serialized properly
+- [ ] Logging never blocks main thread