@vibesdotdev/logging 0.0.1

package/src/docs/structured.docs.descriptor.ts

@@ -0,0 +1,444 @@
+import type { DocsTopicDescriptor } from '@vibesdotdev/docs';
+
+const descriptor: DocsTopicDescriptor = {
+	kind: 'docs/topic',
+	id: 'logging.structured',
+	title: 'Structured Logging',
+	summary: 'Structured logging with context, formatters, and best practices',
+	body: {
+		type: 'markdown',
+		sourceType: 'raw',
+		source: `---
+title: Structured Logging
+summary: Structured logging with context, formatters, and best practices
+tags: [logging, structured, context, formatters, json, best-practices]
+parent: logging
+order: 3
+surfaces: [cli, web, in-app]
+hardware: [consumer, cloud]
+---
+
+# Structured Logging
+
+Structured logging captures log entries as machine-readable data with consistent fields. This enables powerful querying, aggregation, and analysis.
+
+## Why Structured Logging
+
+### Unstructured (Traditional)
+
+\`\`\`
+2024-01-01 12:00:00 INFO User john@example.com logged in from 192.168.1.1
+\`\`\`
+
+**Problems:**
+- Hard to parse programmatically
+- Inconsistent format
+- Difficult to aggregate
+- No schema enforcement
+
+### Structured
+
+\`\`\`json
+{
+  "timestamp": "2024-01-01T12:00:00.000Z",
+  "level": "info",
+  "namespace": "app:auth",
+  "message": "User logged in",
+  "context": {
+    "email": "john@example.com",
+    "ipAddress": "192.168.1.1",
+    "userId": "usr_123"
+  }
+}
+\`\`\`
+
+**Benefits:**
+- Machine-parseable
+- Consistent schema
+- Easy aggregation
+- Queryable fields
+
+## Log Entry Structure
+
+### Standard Fields
+
+\`\`\`ts
+interface LogEntry {
+  timestamp: string;      // ISO 8601 timestamp
+  level: string;          // trace, debug, info, warn, error
+  namespace: string;      // e.g., "app:auth"
+  message: string;        // Human-readable message
+  context?: Record<string, unknown>;  // Structured data
+  metadata?: {
+    requestId?: string;
+    userId?: string;
+    sessionId?: string;
+  };
+}
+\`\`\`
+
+### Example Entry
+
+\`\`\`ts
+logger.info('Payment processed', {
+  context: {
+    userId: 'usr_123',
+    amount: 99.99,
+    currency: 'USD',
+    paymentMethod: 'card'
+  },
+  metadata: {
+    requestId: 'req_456',
+    sessionId: 'ses_789'
+  }
+});
+\`\`\`
+
+**Output:**
+\`\`\`json
+{
+  "timestamp": "2024-01-01T12:00:00.000Z",
+  "level": "info",
+  "namespace": "app:payments",
+  "message": "Payment processed",
+  "context": {
+    "userId": "usr_123",
+    "amount": 99.99,
+    "currency": "USD",
+    "paymentMethod": "card"
+  },
+  "metadata": {
+    "requestId": "req_456",
+    "sessionId": "ses_789"
+  }
+}
+\`\`\`
+
+## Context Objects
+
+### Basic Context
+
+\`\`\`ts
+logger.info('User action', {
+  action: 'login',
+  userId: 'usr_123',
+  success: true
+});
+\`\`\`
+
+### Nested Context
+
+\`\`\`ts
+logger.info('API request', {
+  request: {
+    method: 'POST',
+    path: '/api/users',
+    headers: {
+      'content-type': 'application/json'
+    }
+  },
+  response: {
+    status: 201,
+    duration: 45
+  }
+});
+\`\`\`
+
+### Array Context
+
+\`\`\`ts
+logger.info('Batch operation', {
+  items: [
+    { id: 1, status: 'success' },
+    { id: 2, status: 'failed', error: 'Not found' },
+    { id: 3, status: 'success' }
+  ],
+  summary: {
+    total: 3,
+    success: 2,
+    failed: 1
+  }
+});
+\`\`\`
+
+## Formatters
+
+### Pretty Formatter
+
+Human-readable output for development:
+
+\`\`\`ts
+import { prettyFormatter } from '@vibesdotdev/logging';
+
+const formatted = prettyFormatter.format({
+  timestamp: '2024-01-01T12:00:00.000Z',
+  level: 'info',
+  namespace: 'app:server',
+  message: 'Server started',
+  context: { port: 3000 }
+});
+
+console.log(formatted);
+// [INFO] [app:server] Server started { port: 3000 }
+\`\`\`
+
+### JSON Formatter
+
+Machine-readable output:
+
+\`\`\`ts
+import { jsonFormatter } from '@vibesdotdev/logging';
+
+const formatted = jsonFormatter.format(entry);
+// {"timestamp":"2024-01-01T12:00:00.000Z","level":"info",...}
+\`\`\`
+
+### Custom Formatter
+
+\`\`\`ts
+import type { FormatterImplementation } from '@vibesdotdev/logging';
+
+class CustomFormatter implements FormatterImplementation {
+  format(entry: LogEntry): string {
+    return \`[\${entry.level.toUpperCase()}] \${entry.timestamp} - \${entry.message}\`;
+  }
+}
+\`\`\`
+
+## Correlation IDs
+
+### Request Tracking
+
+\`\`\`ts
+import { logger } from '@vibesdotdev/logging';
+
+// Generate correlation ID
+const requestId = crypto.randomUUID();
+
+// Include in all logs for this request
+logger.setRequestContext({ requestId });
+
+logger.info('Request started');
+// ... handle request ...
+logger.info('Request completed');
+
+// All logs include requestId for correlation
+\`\`\`
+
+### Distributed Tracing
+
+\`\`\`ts
+// Parent request
+const requestId = 'req_123';
+logger.setRequestContext({ requestId });
+
+// Child span
+const spanId = 'span_456';
+logger.setRequestContext({ requestId, spanId });
+
+logger.info('Database query');
+// Links to parent request via requestId
+\`\`\`
+
+## Error Logging
+
+### Error Context
+
+\`\`\`ts
+try {
+  await db.query(sql);
+} catch (error) {
+  logger.error('Database query failed', {
+    context: {
+      query: sql,
+      parameters: params,
+      error: {
+        name: error.name,
+        message: error.message,
+        stack: error.stack
+      }
+    },
+    metadata: {
+      requestId
+    }
+  });
+}
+\`\`\`
+
+### Error Serialization
+
+\`\`\`ts
+import { serializeError } from '@vibesdotdev/logging';
+
+logger.error('Operation failed', {
+  error: serializeError(error)
+});
+
+// Output:
+// {
+//   "name": "Error",
+//   "message": "Something went wrong",
+//   "stack": "...",
+//   "code": "ECONNREFUSED"
+// }
+\`\`\`
+
+## Performance Logging
+
+### Duration Tracking
+
+\`\`\`ts
+const start = performance.now();
+await expensiveOperation();
+const duration = performance.now() - start;
+
+logger.info('Operation completed', {
+  context: {
+    operation: 'expensiveOperation',
+    duration: Math.round(duration * 100) / 100  // ms
+  }
+});
+\`\`\`
+
+### Metrics Collection
+
+\`\`\`ts
+logger.info('Metrics', {
+  context: {
+    type: 'performance',
+    metrics: {
+      cpu: process.cpuUsage(),
+      memory: process.memoryUsage(),
+      requests: activeRequests
+    }
+  }
+});
+\`\`\`
+
+## Security Logging
+
+### Sanitize Sensitive Data
+
+\`\`\`ts
+import { sanitizeForLogging } from '@vibesdotdev/logging';
+
+const userData = {
+  email: 'user@example.com',
+  password: 'secret123',  // Will be redacted
+  token: 'abc123'         // Will be redacted
+};
+
+logger.info('User data', {
+  context: sanitizeForLogging(userData, ['password', 'token'])
+});
+
+// Output:
+// { "email": "user@example.com", "password": "[REDACTED]", "token": "[REDACTED]" }
+\`\`\`
+
+### Audit Logging
+
+\`\`\`ts
+import { auditLogger } from '@vibesdotdev/logging';
+
+auditLogger.authentication({
+  userId: 'usr_123',
+  action: 'login',
+  success: true,
+  ipAddress: '192.168.1.1',
+  userAgent: 'Mozilla/5.0...'
+});
+
+auditLogger.authorization({
+  userId: 'usr_123',
+  resource: 'users/456',
+  action: 'delete',
+  allowed: false,
+  reason: 'Insufficient permissions'
+});
+\`\`\`
+
+## Best Practices
+
+### DO
+
+\`\`\`ts
+// ✅ Use structured context
+logger.info('User created', {
+  context: { userId: 'usr_123', email: 'user@example.com' }
+});
+
+// ✅ Include correlation IDs
+logger.setRequestContext({ requestId: 'req_123' });
+
+// ✅ Use appropriate levels
+logger.debug('Debug info');
+logger.error('Error with context', { error: error.message });
+
+// ✅ Sanitize sensitive data
+logger.info('Auth attempt', {
+  context: { username, password: '[REDACTED]' }
+});
+\`\`\`
+
+### DON'T
+
+\`\`\`ts
+// ❌ String concatenation
+logger.info('User ' + userId + ' logged in');
+
+// ❌ Logging sensitive data
+logger.info('Auth', { password, token });
+
+// ❌ Logging everything as error
+logger.error('User logged in');  // This is info level!
+
+// ❌ Unstructured messages
+logger.info('Something happened with user ' + userId + ' at ' + new Date());
+\`\`\`
+
+## Query Examples
+
+### Log Aggregation Queries
+
+\`\`\`sql
+-- Count errors by namespace
+SELECT namespace, COUNT(*) as error_count
+FROM logs
+WHERE level = 'error'
+GROUP BY namespace;
+
+-- Average response time by endpoint
+SELECT 
+  context->>'endpoint' as endpoint,
+  AVG(context->>'duration') as avg_duration
+FROM logs
+WHERE message = 'API request completed'
+GROUP BY endpoint;
+
+-- User activity timeline
+SELECT 
+  context->>'userId' as user_id,
+  timestamp,
+  message
+FROM logs
+WHERE context->>'userId' = 'usr_123'
+ORDER BY timestamp;
+\`\`\`
+
+:::card{title="See also"}
+- [\`logging.levels\`](logging.levels) — Log levels
+- [\`logging.transports\`](logging.transports) — Transport layers
+- [\`config.environment\`](config.environment) — Environment configuration
+:::
+`
+	},
+	parent: 'logging',
+	order: 3,
+	tags: ['logging', 'structured', 'context', 'formatters', 'json', 'best-practices'],
+	surfaces: ['cli', 'web', 'in-app'],
+	hardware: ['consumer', 'cloud'],
+	enabled: true
+};
+
+export default descriptor;