tessl/npm-bunyan

A JSON logging library for Node.js services with structured logging and CLI tools

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Overview

Eval results

Files

Core Logging

Name: tessl/npm-bunyan
Author: tessl

Primary logging functionality providing structured JSON logging with configurable levels, printf-style formatting, and flexible output options.

Capabilities

Logger Creation

Create logger instances with comprehensive configuration options for name, level, streams, and behavior.

/**
 * Create a new logger instance
 * @param options - Logger configuration options
 * @returns Configured logger instance
 */
function createLogger(options: LoggerOptions): Logger;

interface LoggerOptions {
  name: string;                    // Required: Logger name for identification
  level?: string | number;         // Minimum log level (default: INFO)
  stream?: NodeJS.WritableStream;  // Single output stream (cannot be used with streams)
  streams?: StreamConfig[];        // Multiple streams with different configurations
  serializers?: Serializers;      // Custom field serializers
  src?: boolean;                   // Include source file/line info (performance impact)
  hostname?: string;               // Override hostname in log records
}

// Direct constructor (advanced usage)
class Logger {
  constructor(options: LoggerOptions, childOptions?: any, childSimple?: boolean);
}

Logging Methods

Log messages at different severity levels with structured data and printf-style formatting.

class Logger {
  /**
   * Log at TRACE level (10) - most detailed logging
   * @param fields - Object with additional log fields (optional)
   * @param msg - Log message with printf-style placeholders
   * @param args - Arguments for printf-style formatting
   */
  trace(msg: string, ...args: any[]): void;
  trace(fields: object, msg: string, ...args: any[]): void;

  /**
   * Log at DEBUG level (20) - debugging information
   */
  debug(msg: string, ...args: any[]): void;
  debug(fields: object, msg: string, ...args: any[]): void;

  /**
   * Log at INFO level (30) - general operational messages
   */
  info(msg: string, ...args: any[]): void;
  info(fields: object, msg: string, ...args: any[]): void;

  /**
   * Log at WARN level (40) - warnings that should be investigated
   */
  warn(msg: string, ...args: any[]): void;
  warn(fields: object, msg: string, ...args: any[]): void;

  /**
   * Log at ERROR level (50) - errors that affect specific requests
   */
  error(msg: string, ...args: any[]): void;
  error(fields: object, msg: string, ...args: any[]): void;

  /**
   * Log at FATAL level (60) - service-stopping errors
   */
  fatal(msg: string, ...args: any[]): void;
  fatal(fields: object, msg: string, ...args: any[]): void;
}

Level Management

Query and modify logger levels at runtime for dynamic log level control.

class Logger {
  /**
   * Get or set the logger level
   * @param value - New level to set (optional)
   * @returns Current level if getting, void if setting
   */
  level(): number;
  level(value: string | number): void;

  /**
   * Get or set level for named streams  
   * @param name - Stream name to modify
   * @param value - New level (optional)
   * @returns Current level if getting, void if setting
   */
  levels(): {[streamName: string]: number};
  levels(name: string): number;
  levels(name: string, value: string | number): void;
}

Level Constants and Utilities

Constants and utility functions for working with log levels.

// Log level constants
const TRACE: 10;
const DEBUG: 20;
const INFO: 30;
const WARN: 40;
const ERROR: 50;
const FATAL: 60;

/**
 * Resolve level name or number to numeric level
 * @param nameOrNum - Level name ('info') or number (30)
 * @returns Numeric level value
 */
function resolveLevel(nameOrNum: string | number): number;

/**
 * Get numeric level from level name
 * @param name - Level name (case insensitive)
 * @returns Numeric level value
 */
function levelFromName(name: string): number;

/**
 * Get level name from numeric level
 * @param level - Numeric level value
 * @returns Level name in uppercase
 */
function nameFromLevel(level: number): string;

Usage Examples:

const bunyan = require('bunyan');

// Basic logger creation
const log = bunyan.createLogger({name: 'myapp'});

// Logger with specific level
const debugLog = bunyan.createLogger({
  name: 'debug-app',
  level: 'debug'
});

// Logger with custom stream
const fileLog = bunyan.createLogger({
  name: 'file-app',
  stream: process.stdout
});

// Various logging patterns
log.info('Simple message');
log.info('Message with %s formatting', 'printf-style');
log.info({user: 'alice', action: 'login'}, 'User action');
log.error({err: error}, 'Error occurred');

// Dynamic level changes
console.log(log.level()); // 30 (INFO)
log.level('warn');
console.log(log.level()); // 40 (WARN)

// Level utilities
console.log(bunyan.levelFromName('error')); // 50
console.log(bunyan.nameFromLevel(40)); // 'WARN'

Error Logging Best Practices

When logging errors, use the first parameter to pass the error object for proper serialization:

try {
  riskyOperation();
} catch (err) {
  // Correct: Error object in fields parameter
  log.error({err: err}, 'Operation failed');
  
  // Also correct: Error object with additional context
  log.error({err: err, operation: 'riskyOperation'}, 'Failed operation');
}