Bunyan — Structured JSON Logging for Node.js

Introduction

Bunyan is a structured logging library for Node.js that outputs log records as JSON objects. This machine-readable format makes logs easy to parse, filter, and aggregate with tools like jq, Elasticsearch, or Splunk. A bundled CLI tool renders JSON logs as readable colored output during development.

What Bunyan Does

• Produces structured JSON log records with timestamp, level, hostname, pid, and message fields
• Supports named child loggers for adding context (request ID, user ID) to all downstream log entries
• Provides configurable output streams: stdout, files, rotating files, and custom writable streams
• Includes a CLI tool (bunyan) for pretty-printing, filtering by level, and searching JSON logs
• Serializes errors with full stack traces and common objects (HTTP req/res) automatically

Architecture Overview

Bunyan creates a logger instance with one or more output streams. Each log call constructs a plain JavaScript object with standard fields, merges in any user-supplied fields, serializes it to a single JSON line, and writes it to all configured streams. Child loggers inherit parent streams and fields, adding their own context without duplicating configuration. The design avoids string interpolation and formatting overhead — the JSON record is the canonical output.

Self-Hosting & Configuration

• Install via npm; the bunyan CLI is included as a bin script
• Configure log level per stream to separate debug logs from production error logs
• Use the rotating-file stream type for automatic log rotation by size or time
• Register custom serializers for application-specific objects
• Set the BUNYAN_NO_COLOR environment variable to disable CLI coloring in CI

Key Features

• JSON-first log records for structured log aggregation and querying
• Child loggers carry contextual fields (request ID, tenant) through the call chain
• Built-in rotating file stream with configurable period and file count
• CLI tool for filtering, pretty-printing, and searching log files
• Custom serializers for safe and consistent object representation

Comparison with Similar Tools

• Winston — more flexible transport system and wider community; outputs text by default, needs configuration for JSON
• Pino — newer, faster JSON logger inspired by Bunyan; lower overhead but a different API surface
• log4js — Java-style logging with appenders and categories; more configuration-heavy than Bunyan
• console.log — zero setup but unstructured; no levels, no machine-readable output, no child loggers

FAQ

Q: Why JSON logs instead of plain text? A: JSON logs are parseable by log aggregation systems, filterable with tools like jq, and carry structured metadata without regex parsing.

Q: How do child loggers work? A: Call log.child({ requestId: 'abc' }) to create a child that includes requestId in every log record it produces, without affecting the parent.

Q: Can I send logs to multiple destinations? A: Yes. Pass an array of stream objects to createLogger, each with its own level, type, and path or stream reference.

Q: How does Bunyan compare to Pino in performance? A: Pino is generally faster in benchmarks due to a more aggressive optimization strategy. Bunyan prioritizes a stable API and built-in features like rotating files.

Sources

• https://github.com/trentm/node-bunyan
• https://www.npmjs.com/package/bunyan