@vibesdotdev/logging 0.0.1 → 1.0.0-rc.4

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

@@ -1,444 +0,0 @@
-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;