@vielzeug/rune

Structured browser/Node logger with levels, namespaces, pluggable transports, lazy bindings, and timing helpers.

Package: @vielzeug/rune  ·  Category: Logging

Key exports: createLogger, defaultLogger, lazy, consoleTransport, remoteTransport, jsonTransport, batchTransport, sampleTransport, redactTransport, pipe, isLevelEnabled

When to use: Structured browser/Node logging with log levels, namespaced scopes, lazy bindings, and a pluggable transport pipeline.

Related: @vielzeug/courier · @vielzeug/herald · @vielzeug/familiar

@vielzeug/rune is part of Vielzeug and ships as a zero-dependency TypeScript package with ESM+CJS output.

Installation

pnpm add @vielzeug/rune
npm install @vielzeug/rune
yarn add @vielzeug/rune

Quick Start

import { createLogger, defaultLogger, lazy } from '@vielzeug/rune';
import { consoleTransport, jsonTransport, remoteTransport, sampleTransport } from '@vielzeug/rune';

// Default singleton — uses consoleTransport() automatically
defaultLogger.info({ port: 3000 }, 'server started');
defaultLogger.warn('cache stale');
defaultLogger.error(new Error('connection lost')); // auto-serializes Error

// Namespaced child loggers
const api = createLogger('api');
api.info({ method: 'GET', path: '/users' }, 'request');

// Pinned bindings — lazy() evaluates only when the level passes
const reqLog = api.withBindings({
  requestId: 'abc-123',
  diagnostics: lazy(() => buildDiagnostics()),
});
reqLog.debug('processing'); // diagnostics() called only here

// Structured timing — label is the message; emits { duration_ms } in context
const users = await reqLog.time('db.query', () => db.query('SELECT * FROM users'));

// Custom transport pipeline
const log = createLogger({
  logLevel: 'info',
  namespace: 'server',
  transports: [
    consoleTransport({ timestamp: true }),
    remoteTransport({
      handler: async (type, data) => {
        await fetch('/api/logs', { body: JSON.stringify(data), method: 'POST' });
      },
      level: 'error',
    }),
  ],
});

// Node.js: NDJSON for log aggregation (ELK, Datadog, etc.)
const nodeLog = createLogger({
  transports: [jsonTransport({ level: 'warn' })],
});

// Fan-out to multiple transports independently (errors in one don't block others)
import { pipe } from '@vielzeug/rune';
const fanout = pipe(consoleTransport(), remoteTransport({ handler, level: 'error' }));

// Sampling — drop 90 % of debug entries before they reach the downstream transport
const sampledLog = createLogger({
  logLevel: 'debug',
  transports: [sampleTransport({ rate: 0.1, transport: consoleTransport() })],
});

Documentation

• Overview
• Usage Guide
• API Reference
• Examples

License

MIT © Helmuth Saatkamp — part of the Vielzeug monorepo.