@untools/logger

An enhanced, context-aware logger for JavaScript/TypeScript designed for Wide Events and Canonical Log Lines. It features premium aesthetics for both Node.js and Browser environments, handles DOM elements, and safely manages circular references.

Inspired by Logging Sucks and the philosophy of observability wide events.

Features

• 🚀 Wide Events: Consolidation of request context into single, rich log lines.
• 🔗 Context Accumulation: Persistent metadata that follows your execution flow.
• 👶 Child Loggers: Easily create request-scoped loggers with inherited context.
• 🎨 Premium Aesthetics: High-contrast dark theme for Terminal; modern, clean CSS for Browser.
• 🧩 DOM Support: Specialized formatting for DOM elements (Browser only).
• 🔄 Circular Safety: Robust handling of circular references in objects.
• 🛠 Environment Aware: Automatic inclusion of _ts, _env, and _pid metadata.

Best Practices

This logger is built to support Wide Events (Canonical Log Lines). Instead of scattering log lines throughout your handler, accumulate context and emit a single structured event at completion.

1. Initialize Context

Start a "service hop" by creating a child logger with request context.

import { logger } from '@untools/logger';

const requestLogger = logger.child({
  _rid: 'req_a7b2...', // Request ID
  userId: 'user_123',
  path: '/api/checkout'
});

2. Accumulate Business Context

Add context as it becomes available during process execution.

requestLogger.addContext({
  cart_value: 2499,
  item_count: 3,
  subscription: 'premium'
});

3. Emit at Completion

Use a finally block or completion handler to emit the final wide event.

try {
  // ... business logic
  requestLogger.info({ outcome: 'success', status_code: 200 });
} catch (error) {
  requestLogger.error({ outcome: 'error', error: error.message });
}

Usage

Server (Node.js)

The server output uses premium ANSI color coding and bold keys for high readability in dark terminals.

logger.info("Server started", { port: 3000 });

Browser

In the browser, logs are beautifully styled with CSS and include collapsed groups for raw object inspection.

logger.debug("Component mounted", { props, state });

Log Levels

Default level is INFO (2). Change it via:

import { LogLevel } from '@untools/logger';
logger.setLogLevel(LogLevel.DEBUG); // 3

Credits & References

Special thanks to Boris Tane (@boristane) for the foundational concepts of Wide Events and Canonical Log Lines.

Key References:

• Logging Sucks
• Observability Wide Events 101 by Boris Tane
• Stripe - Canonical Log Lines

License

MIT