Log Driver

Common errors

• TypeError [ERR_UNKNOWN_FILE_EXTENSION]: Unknown file extension in <module path> for <log-driver module path>

  cause Attempting to `import` the CommonJS-only `log-driver` package in an ES Module context (e.g., a `.mjs` file or a project with `"type": "module"` in `package.json`).
  fix Use `const logDriver = require('log-driver');` instead of `import` statements. If your project is pure ESM, consider migrating to an ESM-compatible logging library.

• TypeError: logger.trace is not a function

  cause The logger instance was initialized with a `level` option that is higher (less verbose) than 'trace', effectively disabling the `trace` method. For example, setting `level: 'info'` will disable `debug` and `trace` methods.
  fix Ensure the logger is configured with a sufficiently low `level` to enable the desired methods. For 'trace' output, initialize with `require('log-driver')({ level: 'trace' })` or lower.

• ReferenceError: require is not defined

  cause `log-driver` is a Node.js-specific package that uses Node.js's `require` function, which is not available in client-side browser environments.
  fix This package is not designed for browser use. For client-side logging, use browser-native `console` methods or a browser-compatible logging library (e.g., `loglevel`).

Warnings

• breaking The `log-driver` package is abandoned and has not received updates since February 2018. This implies a lack of security patches, bug fixes, and compatibility updates for newer Node.js versions or evolving ecosystem standards. Continued use in production environments is highly risky.
  Fix: Migrate to a actively maintained logging solution such as Winston, Pino, or pino-pretty, which offer robust features, performance, and ongoing support.
• gotcha This package is CommonJS-only and does not support ES Modules (`import`/`export`). Attempting to use `log-driver` in an ESM context will lead to runtime errors.
  Fix: Ensure `log-driver` is used only in CommonJS modules with `require()`. For projects using ES Modules, consider migrating to an ESM-compatible logging library or using a CommonJS wrapper.
• gotcha Log Driver's design relies heavily on operating system-level piping for log persistence and transport (e.g., sending to files, syslog, or external services). It does not provide built-in transports like modern logging libraries.
  Fix: Users must implement external piping mechanisms (e.g., shell redirection `>>`, or piping to tools like `logger` or custom scripts) to achieve log storage or forwarding beyond `stdout`/`stderr`.
• gotcha The package's `engines` field specifies Node.js `>=0.8.6`, which is an extremely old and unsupported version of Node.js. While it might still function on newer Node.js runtimes, unexpected behavior, deprecation warnings, or outright compatibility issues are highly probable due to unmaintained dependencies or breaking changes in Node.js itself.
  Fix: Thoroughly test `log-driver` on your target Node.js version. For production, prioritize migration to a actively maintained logger that explicitly supports modern Node.js versions.

Install

• npm install log-driver npm
• yarn add log-driver yarn
• pnpm add log-driver pnpm

Imports

• logger
  wrong:

  import { logger } from 'log-driver';

  correct:

  const logger = require('log-driver').logger;

  This package is CommonJS-only and primarily used via direct property access on the module export. Attempting to use `import` syntax will result in errors in an ESM context.
• default export (factory)
  wrong:

  import customLogger from 'log-driver';

  correct:

  const customLogger = require('log-driver')({ level: 'info' });

  The default export is a factory function for creating new logger instances with custom configurations. It is CommonJS-only; direct ESM default imports are not supported.
• Logger instances
  wrong:

  logger.log('info', 'message');

  correct:

  logger.info('message');

  Logger instances expose level-specific methods (e.g., `.info()`, `.warn()`, `.error()`) rather than a generic `.log()` with a level argument.

Quickstart

Demonstrates how to get the default logger, configure a logger with custom levels and thresholds, and apply a custom JSON formatting function, highlighting its stdout-centric design.

const logDriver = require('log-driver');

// Get the default logger instance
const defaultLogger = logDriver.logger;

defaultLogger.info('Application started at %s', new Date().toISOString());
defaultLogger.warn('Potential issue: %j', {
  severity: 'medium',
  reason: 'Resource nearing limit'
});
defaultLogger.error(new Error('Something critical happened!'), 'An unexpected error occurred.');

// Configure a custom logger with specific levels and a lower threshold
const customLevelsLogger = logDriver({
  levels: ['audit', 'critical', 'notify'],
  level: 'critical' // Only log 'critical' and 'audit'
});

customLevelsLogger.audit('User %s performed action %s', 'admin', 'login');
customLevelsLogger.critical('Database connection lost!');
customLevelsLogger.notify('New update available (this will not show)'); // Below 'critical' level

// Demonstrate a custom formatter for JSON output
const jsonLogger = logDriver({
  format: function() {
    const args = Array.from(arguments);
    const level = args.shift(); // First arg is the log level implicitly passed by the method
    const timestamp = new Date().toISOString();
    return JSON.stringify({
      timestamp,
      level,
      message: args.map(arg => typeof arg === 'object' ? JSON.stringify(arg) : String(arg)).join(' ')
    });
  }
});

jsonLogger.info('This is a JSON log message', { data: 'example', id: 123 });

// To experience log-driver's full effect, run this script and pipe its output:
// node your-app.js 2>&1 | tee app.log | some-log-processor.js