Mastering Node.js Logging: Active vs Passive Techniques and Best Practices

Logs are a crucial tool for developers to troubleshoot issues, often being the only source of insight, so choosing the right way to log is essential.

Active Logging

Active logging is typically used during development when the program state is uncertain. The simplest example is: console.log('hello world'); Most production code avoids console because it lacks performance and advanced features. Instead, developers use the popular debug module, which can color‑code output by namespace and be controlled via the DEBUG environment variable: $ DEBUG=* node app.js Node.js also provides a built‑in util.debuglog method (available since v0.11.3) that works similarly and is toggled with the NODE_DEBUG environment variable:

const util = require('util');
const debuglog = util.debuglog('foo');

debuglog('hello from foo [%d]', 123);

Passive Recording

Passive logging refers to the default output of logging libraries that record information silently and are consulted only when needed (e.g., errors, diagnostics). Common libraries include log4j, winston, and pino. Their core features are:

Output to various channels (console, files, etc.)

Customizable formats (plain text or JSON)

Log levels (warn, debug, error, etc.)

Additional capabilities such as file rotation and compression

Using a library is straightforward: obtain an instance and call its methods.

logger.info('hello world');

Log Format

A typical log line contains several fixed fields that have become a de‑facto standard, similar to Java’s Simple Logger or Nginx access logs:

Timestamp

Log level

Process ID (Node)

Label or tag (e.g., source module)

Message body (string or error stack)

Custom fields such as execution time, user ID, or payload size can also be added. In plain‑text logs, fields are space‑separated and terminated with a newline, which simplifies ingestion by log collection systems (e.g., Alibaba Cloud SLS). Many libraries now support JSON output for structured analysis.

Correct Logging Practices

When calling a remote service, wrap the call in a try/catch block and log errors with relevant context:

async function invokeRemoteAPI() {
  try {
    const result = await remoteService.got();
    return { result };
  } catch (err) {
    logger.error('got an error, err=', err);
    throw err;
  }
}

To avoid repetitive code, define a logger with a preset format that automatically includes fields like process ID and response time:

const logger = new CustomLogger({
  format: '${timestamp} ${level} ' + process.pid + ' ${rt}'
});

Then use it in functions, adding timing information only when an error occurs:

async function invokeRemoteAPI() {
  const pid = process.pid;
  const startTime = Date.now();
  try {
    const result = await remoteService.got();
    return { result };
  } catch (err) {
    const endTime = Date.now();
    logger.error('pid=%s, rt=%s, got an error, err=', pid, endTime - startTime, err);
    throw err;
  }
}

Contextual Logging

Beyond simple logs, context‑bound logging attaches request‑specific data (e.g., response time, client IP, route, trace ID) to each entry. An example using Koa demonstrates proxying the original logger to inject context without incurring the overhead of re‑initializing a new logger for every request:

// ordinary logger
const logger = new CustomLogger();

class CtxLogger {
  constructor(ctx, logger) {
    this.ctx = ctx;
    this.logger = logger;
  }
  format() {
    return `${timestamp} ${level} ` + process.pid + `[${this.ctx.refer} ${this.ctx.rt}]`;
  }
}

app.use(async (ctx, next) => {
  const ctxLogger = new CtxLogger(ctx, logger);
  ctx.logger = ctxLogger;
  await next();
});

This proxy approach reduces per‑request initialization cost while preserving the ability to pass context fields through the logger.

Quick Recap

We have reviewed common Node.js logging libraries, compared active and passive logging methods, examined log format conventions, and demonstrated both simple and context‑aware logging implementations, giving you a solid foundation for effective log management and troubleshooting.