@vibesdotdev/logging 0.0.1

package/src/docs/levels.docs.descriptor.ts

@@ -0,0 +1,344 @@
+import type { DocsTopicDescriptor } from '@vibesdotdev/docs';
+
+const descriptor: DocsTopicDescriptor = {
+	kind: 'docs/topic',
+	id: 'logging.levels',
+	title: 'Log Levels',
+	summary: 'Log levels (debug, info, warn, error) and filtering',
+	body: {
+		type: 'markdown',
+		sourceType: 'raw',
+		source: `---
+title: Log Levels
+summary: Log levels (debug, info, warn, error) and filtering
+tags: [logging, levels, debug, info, warn, error, filtering]
+parent: logging
+order: 1
+surfaces: [cli, web, in-app]
+hardware: [consumer, cloud]
+---
+
+# Log Levels
+
+Log levels categorize log entries by severity. The logging system provides five standard levels with automatic filtering based on configuration.
+
+## Level Hierarchy
+
+\`\`\`
+trace < debug < info < warn < error
+\`\`\`
+
+Each level includes all levels above it. Setting level to \`warn\` logs \`warn\` and \`error\` only.
+
+## Level Definitions
+
+### Trace (0)
+
+Fine-grained debugging information:
+
+\`\`\`ts
+logger.trace('Entering function', { fn: 'processUser', userId: '123' });
+\`\`\`
+
+**Use for:**
+- Function entry/exit
+- Variable values during debugging
+- Detailed execution flow
+
+**Typical output:**
+\`\`\`
+[TRACE] [app:user] Entering function {"fn":"processUser","userId":"123"}
+\`\`\`
+
+### Debug (1)
+
+Debugging information for development:
+
+\`\`\`ts
+logger.debug('Database query executed', {
+  query: 'SELECT * FROM users',
+  duration: 45
+});
+\`\`\`
+
+**Use for:**
+- SQL queries
+- API requests
+- Configuration values
+- Performance metrics
+
+**Typical output:**
+\`\`\`
+[DEBUG] [app:db] Database query executed {"query":"SELECT * FROM users","duration":45}
+\`\`\`
+
+### Info (2)
+
+General informational messages:
+
+\`\`\`ts
+logger.info('Server started', {
+  port: 3000,
+  environment: 'development'
+});
+\`\`\`
+
+**Use for:**
+- Application lifecycle events
+- User actions (login, logout)
+- System state changes
+- Successful operations
+
+**Typical output:**
+\`\`\`
+[INFO] [app:server] Server started {"port":3000,"environment":"development"}
+\`\`\`
+
+### Warn (3)
+
+Warning conditions:
+
+\`\`\`ts
+logger.warn('High memory usage detected', {
+  usage: '85%',
+  threshold: '80%'
+});
+\`\`\`
+
+**Use for:**
+- Resource warnings
+- Deprecated API usage
+- Recoverable errors
+- Performance degradation
+
+**Typical output:**
+\`\`\`
+[WARN] [app:monitor] High memory usage detected {"usage":"85%","threshold":"80%"}
+\`\`\`
+
+### Error (4)
+
+Error conditions:
+
+\`\`\`ts
+logger.error('Database connection failed', {
+  error: error.message,
+  host: config.db.host
+});
+\`\`\`
+
+**Use for:**
+- Unhandled exceptions
+- Failed operations
+- System errors
+- External service failures
+
+**Typical output:**
+\`\`\`
+[ERROR] [app:db] Database connection failed {"error":"ECONNREFUSED","host":"localhost"}
+\`\`\`
+
+## Setting Log Level
+
+### Environment Variable
+
+\`\`\`bash
+# Set minimum level
+export LOG_LEVEL=debug
+
+# Levels: trace, debug, info, warn, error
+\`\`\`
+
+### Programmatic Configuration
+
+\`\`\`ts
+import { logger } from '@vibesdotdev/logging';
+
+logger.setLevel('debug');
+
+// Only debug, info, warn, error will be logged
+// trace will be filtered out
+\`\`\`
+
+### Config Manifest
+
+\`\`\`ts
+const loggingConfig = await runtime.query('config/manifest')
+  .filter(d => d.id === 'logging')
+  .resolve();
+
+const config = await loggingConfig.loadWithDefaults(context);
+
+console.log(config.level);  // 'info'
+\`\`\`
+
+## Level Filtering
+
+### Filter by Level
+
+\`\`\`ts
+logger.setLevel('warn');
+
+logger.trace('Will NOT be logged');  // filtered
+logger.debug('Will NOT be logged');  // filtered
+logger.info('Will NOT be logged');   // filtered
+logger.warn('Will be logged');       // ✓
+logger.error('Will be logged');      // ✓
+\`\`\`
+
+### Filter by Namespace
+
+\`\`\`ts
+import { createLogger } from '@vibesdotdev/logging';
+
+// Create logger with namespace
+const dbLogger = createLogger('app:db');
+const authLogger = createLogger('app:auth');
+
+dbLogger.setLevel('debug');
+authLogger.setLevel('error');
+
+dbLogger.debug('Query executed');    // logged
+authLogger.debug('Token validated');  // filtered
+\`\`\`
+
+### Filter by Context
+
+\`\`\`ts
+logger.debug('Debug message', {
+  context: {
+    userId: '123',
+    requestId: 'req-456'
+  }
+});
+
+// Output includes context
+// [DEBUG] [app] Debug message {"userId":"123","requestId":"req-456"}
+\`\`\`
+
+## Namespace Patterns
+
+### Namespace Hierarchy
+
+\`\`\`ts
+// Namespace structure
+app:server
+app:database
+app:auth
+app:api:users
+app:api:posts
+
+// Set level for namespace pattern
+logger.setLevel('app:api:*', 'debug');  // All API logs
+\`\`\`
+
+### Wildcard Patterns
+
+\`\`\`ts
+// Wildcard matching
+logger.setLevel('app:*', 'info');       // All app logs
+logger.setLevel('app:api:*', 'debug');  // All API logs
+logger.setLevel('*', 'warn');           // All logs
+\`\`\`
+
+## Level-Specific Methods
+
+### Convenience Methods
+
+\`\`\`ts
+logger.trace('Trace message');
+logger.debug('Debug message');
+logger.info('Info message');
+logger.warn('Warning message');
+logger.error('Error message');
+\`\`\`
+
+### Structured Logging
+
+\`\`\`ts
+logger.info('User logged in', {
+  userId: '123',
+  email: 'user@example.com',
+  timestamp: new Date().toISOString()
+});
+
+logger.error('Payment failed', {
+  userId: '123',
+  amount: 99.99,
+  error: 'Insufficient funds',
+  code: 'PAYMENT_FAILED'
+});
+\`\`\`
+
+## Conditional Logging
+
+### Level Guards
+
+\`\`\`ts
+if (logger.isLevelEnabled('debug')) {
+  // Expensive operation only if debug logging enabled
+  const debugData = computeExpensiveDebugData();
+  logger.debug('Debug info', debugData);
+}
+\`\`\`
+
+### Dynamic Level Changes
+
+\`\`\`ts
+// Temporarily increase verbosity
+const previousLevel = logger.getLevel();
+logger.setLevel('trace');
+
+// ... debug-heavy operation ...
+
+logger.setLevel(previousLevel);  // restore
+\`\`\`
+
+## Audit Logging
+
+Audit logs use special level handling:
+
+\`\`\`ts
+import { auditLogger } from '@vibesdotdev/logging';
+
+// Audit logs always logged regardless of level
+auditLogger.authentication({
+  userId: '123',
+  action: 'login',
+  success: true,
+  ipAddress: '192.168.1.1'
+});
+
+auditLogger.authorization({
+  userId: '123',
+  resource: 'users/456',
+  action: 'delete',
+  allowed: false
+});
+\`\`\`
+
+## Best Practices
+
+1. **Use appropriate levels** — Don't log everything as error
+2. **Include context** — Help debugging with relevant data
+3. **Avoid sensitive data** — Never log passwords, tokens, PII
+4. **Consistent namespaces** — Use hierarchical naming
+5. **Production level** — Typically 'info' or 'warn'
+6. **Development level** — Typically 'debug'
+
+:::card{title="See also"}
+- [\`logging.transports\`](logging.transports) — Transport layers
+- [\`logging.structured\`](logging.structured) — Structured logging
+- [\`config.environment\`](config.environment) — Environment configuration
+:::
+`
+	},
+	parent: 'logging',
+	order: 1,
+	tags: ['logging', 'levels', 'debug', 'info', 'warn', 'error', 'filtering'],
+	surfaces: ['cli', 'web', 'in-app'],
+	hardware: ['consumer', 'cloud'],
+	enabled: true
+};
+
+export default descriptor;