@vibesdotdev/logging 0.0.1 → 1.0.0-rc.4

package/dist/docs/structured.docs.descriptor.js

@@ -18,7 +18,7 @@ hardware: [consumer, cloud]
 
 # Structured Logging
 
-Structured logging captures log entries as machine-readable data with consistent fields. This enables powerful querying, aggregation, and analysis.
+Structured logging captures log entries as machine-readable data with consistent fields. The \`@vibesdotdev/logging\` logger emits each entry as a \`RuntimeLogEntry\` whose \`context\` is an open key/value bag, enabling querying, aggregation, and analysis.
 
 ## Why Structured Logging
 
@@ -40,12 +40,11 @@ Structured logging captures log entries as machine-readable data with consistent
 {
   "timestamp": "2024-01-01T12:00:00.000Z",
   "level": "info",
-  "namespace": "app:auth",
+  "namespace": "vibes:auth",
   "message": "User logged in",
   "context": {
-    "email": "john@example.com",
-    "ipAddress": "192.168.1.1",
-    "userId": "usr_123"
+    "userId": "usr_123",
+    "ip": "192.168.1.1"
   }
 }
 \`\`\`
@@ -58,37 +57,39 @@ Structured logging captures log entries as machine-readable data with consistent
 
 ## Log Entry Structure
 
-### Standard Fields
+Every entry conforms to \`RuntimeLogEntry\` (exported from \`@vibesdotdev/logging\`). There is no separate \`metadata\` field — request, job, and ad-hoc data all live under \`context\` (a \`LogContext\`, i.e. \`Record<string, unknown>\`).
 
 \`\`\`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;
-  };
-}
+import type { RuntimeLogEntry, LogContext, LogLevel } from '@vibesdotdev/logging';
+
+// LogLevel = 'debug' | 'info' | 'warn' | 'error'
+// RuntimeLogEntry = {
+//   timestamp: string;   // ISO 8601
+//   level: LogLevel;
+//   namespace: string;   // e.g. 'vibes:payments'
+//   message: string;
+//   context: LogContext; // Record<string, unknown>
+// }
 \`\`\`
 
-### Example Entry
+### Getting a logger
+
+The default logger is exported directly; named loggers come from \`getLogger(id, runtime)\` where \`id\` is the **logging/logger descriptor id** (not a dotted namespace). Namespacing belongs in \`descriptor.namespace\` or \`.child()\`. Call \`initializeLoggers(runtime)\` after plugins register so sync \`getLogger\` resolves outputs/sinks from that runtime.
 
 \`\`\`ts
-logger.info('Payment processed', {
-  context: {
-    userId: 'usr_123',
-    amount: 99.99,
-    currency: 'USD',
-    paymentMethod: 'card'
-  },
-  metadata: {
-    requestId: 'req_456',
-    sessionId: 'ses_789'
-  }
+import { getLogger, initializeLoggers } from '@vibesdotdev/logging';
+
+// \`runtime\` is the runtime your host booted and handed to this code.
+await initializeLoggers(runtime);
+
+getLogger('server', runtime).info('Server started');
+
+const payments = getLogger('payments', runtime);
+payments.info('Payment processed', {
+  userId: 'usr_123',
+  amount: 99.99,
+  currency: 'USD',
+  paymentMethod: 'card'
 });
 \`\`\`
 
@@ -97,23 +98,23 @@ logger.info('Payment processed', {
 {
   "timestamp": "2024-01-01T12:00:00.000Z",
   "level": "info",
-  "namespace": "app:payments",
+  "namespace": "payments",
   "message": "Payment processed",
   "context": {
     "userId": "usr_123",
     "amount": 99.99,
     "currency": "USD",
     "paymentMethod": "card"
-  },
-  "metadata": {
-    "requestId": "req_456",
-    "sessionId": "ses_789"
   }
 }
 \`\`\`
 
+> The level/message/context method shape is \`(message: string, context?: unknown)\`. Static metadata configured on the logger descriptor is merged into \`context\` automatically.
+
 ## Context Objects
 
+The second argument to \`debug\`/\`info\`/\`warn\`/\`error\` is the context object — passed directly, not wrapped.
+
 ### Basic Context
 
 \`\`\`ts
@@ -124,310 +125,153 @@ logger.info('User action', {
 });
 \`\`\`
 
-### Nested Context
-
-\`\`\`ts
-logger.info('API request', {
-  request: {
-    method: 'POST',
-    path: '/api/users',
-    headers: {
-      'content-type': 'application/json'
-    }
-  },
-  response: {
-    status: 201,
-    duration: 45
-  }
-});
-\`\`\`
+### Nested / Array Context
 
-### Array Context
+Context values may be arbitrarily nested objects or arrays.
 
 \`\`\`ts
 logger.info('Batch operation', {
   items: [
     { id: 1, status: 'success' },
-    { id: 2, status: 'failed', error: 'Not found' },
-    { id: 3, status: 'success' }
+    { id: 2, status: 'failed', error: 'Not found' }
   ],
-  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 }
+  summary: { total: 2, success: 1, failed: 1 }
 });
-
-console.log(formatted);
-// [INFO] [app:server] Server started { port: 3000 }
 \`\`\`
 
-### JSON Formatter
+## Contextual Loggers
 
-Machine-readable output:
+Rather than a global mutable context, the logger exposes builder methods that each return a **new** logger carrying the merged context. The originals are unchanged.
 
-\`\`\`ts
-import { jsonFormatter } from '@vibesdotdev/logging';
-
-const formatted = jsonFormatter.format(entry);
-// {"timestamp":"2024-01-01T12:00:00.000Z","level":"info",...}
-\`\`\`
+### Request Context
 
-### Custom Formatter
+\`withRequestContext\` accepts a typed \`RequestLogContext\` (\`requestId\`, \`correlationId\`, \`sessionId\`, \`userId\`, \`userAgent\`, \`ip\`, \`route\`, \`method\`). Use it once per request and pass the returned logger down.
 
 \`\`\`ts
-import type { FormatterImplementation } from '@vibesdotdev/logging';
+import { getLogger } from '@vibesdotdev/logging';
+
+// runtime is the runtime your host booted and handed to this code.
+const base = getLogger('api', runtime);
+const reqLogger = base.withRequestContext({
+  requestId: crypto.randomUUID(),
+  route: '/api/users',
+  method: 'POST'
+});
 
-class CustomFormatter implements FormatterImplementation {
-  format(entry: LogEntry): string {
-    return \`[\${entry.level.toUpperCase()}] \${entry.timestamp} - \${entry.message}\`;
-  }
-}
+reqLogger.info('Request started');
+// ... handle request ...
+reqLogger.info('Request completed');
+// every entry carries requestId/route/method in context
 \`\`\`
 
-## Correlation IDs
+### Job Context
 
-### Request Tracking
+\`withJobContext\` accepts a typed \`JobLogContext\` (\`jobId\`, \`queueId\`, \`queueName\`, \`toolId\`, \`parentJobId\`, \`attempt\`, \`maxAttempts\`).
 
 \`\`\`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
+const jobLogger = getLogger('worker', runtime).withJobContext({
+  jobId: 'job_123',
+  queueName: 'emails',
+  attempt: 1
+});
+jobLogger.info('Job started');
 \`\`\`
 
-### Distributed Tracing
+### Arbitrary Context & Child Namespaces
 
 \`\`\`ts
-// Parent request
-const requestId = 'req_123';
-logger.setRequestContext({ requestId });
+// Pin arbitrary fields onto a derived logger
+const tenantLogger = logger.withContext({ tenantId: 'acme' });
 
-// Child span
-const spanId = 'span_456';
-logger.setRequestContext({ requestId, spanId });
-
-logger.info('Database query');
-// Links to parent request via requestId
+// Child logger appends to the namespace path
+const dbLogger = logger.child('database');
+dbLogger.debug('Connected'); // namespace: 'vibes:database'
 \`\`\`
 
 ## Error Logging
 
-### Error Context
+Pass the structured context directly. If you hand an \`Error\` instance as the context, the logger normalizes it to \`{ errorName, errorMessage, stack }\`.
 
 \`\`\`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
-    }
+    query: sql,
+    error // Error -> { errorName, errorMessage, stack }
   });
 }
 \`\`\`
 
-### Error Serialization
+## Performance Tracking
 
-\`\`\`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
+Use \`performanceTracker({ operation })\` to time an operation. It emits a \`debug\` start event and an \`info\`/\`error\` completion event with a computed \`duration\` (ms) in context.
 
 \`\`\`ts
-logger.info('Metrics', {
-  context: {
-    type: 'performance',
-    metrics: {
-      cpu: process.cpuUsage(),
-      memory: process.memoryUsage(),
-      requests: activeRequests
-    }
-  }
-});
+const tracker = logger.performanceTracker({ operation: 'expensiveOperation' });
+tracker.start();
+try {
+  await expensiveOperation();
+  tracker.end({ rows: 42 });          // info: operation.expensiveOperation.success
+} catch (error) {
+  tracker.fail(error);                // error: operation.expensiveOperation.failure
+}
 \`\`\`
 
-## Security Logging
+## Audit Logging
 
-### Sanitize Sensitive Data
+Audit events are a separate runtime kind (\`logging/audit\`) — there is no \`auditLogger\` singleton. Resolve an implementation from the runtime and call \`log\` with an \`AuditLogInput\`.
 
 \`\`\`ts
-import { sanitizeForLogging } from '@vibesdotdev/logging';
+import type { AuditDescriptor, AuditImplementation, AuditLogInput } from '@vibesdotdev/logging';
 
-const userData = {
-  email: 'user@example.com',
-  password: 'secret123',  // Will be redacted
-  token: 'abc123'         // Will be redacted
-};
+// \`runtime\` is the runtime your host booted and handed to this code.
+const auditor = await runtime.query<AuditDescriptor, AuditImplementation>('logging/audit').withId('default').resolve();
 
-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',
+await auditor.log({
+  category: 'authentication',   // authentication | authorization | data_access |
+                                // data_modification | configuration | system | security
+  severity: 'medium',           // low | medium | high | critical
   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'
-});
+  actor: { id: 'usr_123', type: 'user', ip: '192.168.1.1' },
+  outcome: 'success'            // success | failure | error | unknown
+} satisfies AuditLogInput);
 \`\`\`
 
+The core package owns the audit kind, schemas, and retention policy types; file-backed persistence is Logging's base (\`@vibesdotdev/logging/host-files\`) over each host's own file primitives: the Node host (\`nodeLoggingPlugin\`, also registered by the declared Node test host) and the Bun host each register it under their own plugin.
+
 ## 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 structured context, not string interpolation
+logger.info('User created', { userId: 'usr_123', email });
 
-// ✅ Use appropriate levels
-logger.debug('Debug info');
-logger.error('Error with context', { error: error.message });
+// Derive a request-scoped logger and pass it down
+const reqLogger = logger.withRequestContext({ requestId });
 
-// ✅ Sanitize sensitive data
-logger.info('Auth attempt', {
-  context: { username, password: '[REDACTED]' }
-});
+// Use appropriate levels (debug | info | warn | error)
+logger.debug('Cache miss', { key });
+logger.error('Payment failed', { orderId, error });
 \`\`\`
 
 ### DON'T
 
 \`\`\`ts
-// ❌ String concatenation
+// String concatenation loses structure
 logger.info('User ' + userId + ' logged in');
 
-// ❌ Logging sensitive data
+// Logging raw secrets
 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;
+// Wrong level
+logger.error('User logged in'); // this is info-level
 \`\`\`
 
 :::card{title="See also"}
-- [\`logging.levels\`](logging.levels) — Log levels
-- [\`logging.transports\`](logging.transports) — Transport layers
-- [\`config.environment\`](config.environment) — Environment configuration
+- [Log Levels](logging.levels) — \`debug\`/\`info\`/\`warn\`/\`error\` and namespace filtering
+- [Logging Transports](logging.transports) — sinks and outputs that write entries
 :::
 `
     },

package/dist/docs/structured.docs.descriptor.js.map

@@ -1 +1 @@
-{"version":3,"file":"structured.docs.descriptor.js","sourceRoot":"","sources":["../../src/docs/structured.docs.descriptor.ts"],"names":[],"mappings":"AAEA,MAAM,UAAU,GAAwB;IACvC,IAAI,EAAE,YAAY;IAClB,EAAE,EAAE,oBAAoB;IACxB,KAAK,EAAE,oBAAoB;IAC3B,OAAO,EAAE,iEAAiE;IAC1E,IAAI,EAAE;QACL,IAAI,EAAE,UAAU;QAChB,UAAU,EAAE,KAAK;QACjB,MAAM,EAAE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAuaT;KACC;IACD,MAAM,EAAE,SAAS;IACjB,KAAK,EAAE,CAAC;IACR,IAAI,EAAE,CAAC,SAAS,EAAE,YAAY,EAAE,SAAS,EAAE,YAAY,EAAE,MAAM,EAAE,gBAAgB,CAAC;IAClF,QAAQ,EAAE,CAAC,KAAK,EAAE,KAAK,EAAE,QAAQ,CAAC;IAClC,QAAQ,EAAE,CAAC,UAAU,EAAE,OAAO,CAAC;IAC/B,OAAO,EAAE,IAAI;CACb,CAAC;AAEF,eAAe,UAAU,CAAC"}
+{"version":3,"file":"structured.docs.descriptor.js","sourceRoot":"","sources":["../../src/docs/structured.docs.descriptor.ts"],"names":[],"mappings":"AAEA,MAAM,UAAU,GAAwB;IACvC,IAAI,EAAE,YAAY;IAClB,EAAE,EAAE,oBAAoB;IACxB,KAAK,EAAE,oBAAoB;IAC3B,OAAO,EAAE,iEAAiE;IAC1E,IAAI,EAAE;QACL,IAAI,EAAE,UAAU;QAChB,UAAU,EAAE,KAAK;QACjB,MAAM,EAAE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA2QT;KACC;IACD,MAAM,EAAE,SAAS;IACjB,KAAK,EAAE,CAAC;IACR,IAAI,EAAE,CAAC,SAAS,EAAE,YAAY,EAAE,SAAS,EAAE,YAAY,EAAE,MAAM,EAAE,gBAAgB,CAAC;IAClF,QAAQ,EAAE,CAAC,KAAK,EAAE,KAAK,EAAE,QAAQ,CAAC;IAClC,QAAQ,EAAE,CAAC,UAAU,EAAE,OAAO,CAAC;IAC/B,OAAO,EAAE,IAAI;CACb,CAAC;AAEF,eAAe,UAAU,CAAC"}

package/dist/docs/transports.docs.descriptor.d.ts

@@ -1,4 +1,4 @@
-import type { DocsTopicDescriptor } from '@vibesdotdev/docs';
+import type { DocsTopicDescriptor } from '@vibesdotdev/docs-contracts';
 declare const descriptor: DocsTopicDescriptor;
 export default descriptor;
 //# sourceMappingURL=transports.docs.descriptor.d.ts.map

package/dist/docs/transports.docs.descriptor.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"transports.docs.descriptor.d.ts","sourceRoot":"","sources":["../../src/docs/transports.docs.descriptor.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,mBAAmB,CAAC;AAE7D,QAAA,MAAM,UAAU,EAAE,mBAuajB,CAAC;AAEF,eAAe,UAAU,CAAC"}
+{"version":3,"file":"transports.docs.descriptor.d.ts","sourceRoot":"","sources":["../../src/docs/transports.docs.descriptor.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,6BAA6B,CAAC;AAEvE,QAAA,MAAM,UAAU,EAAE,mBAgNjB,CAAC;AAEF,eAAe,UAAU,CAAC"}