node-bunyan

Bunyan is a JSON logging library for Node.js services created by Trent Mick and used extensively at Joyent. Every log record is emitted as a single line of JSON, with common fields like name, hostname, pid, level, and time added automatically, making logs easy to parse, stream to log-aggregation systems, and process with standard JSON tooling.

Alongside the library, Bunyan ships a bunyan CLI tool for pretty-printing and filtering its structured logs. Streams can fan a single logger out to multiple destinations at different levels, including stdout, rotating log files, or raw in-memory ring buffers, and child loggers let sub-components of an application bind additional fields without re-specifying the whole logger. The project is stable and widely used, though the 2.x line on the “master” branch has been in a long-running beta for years, with 1.x continuing as the version npm installs by default.

What You Get

• A Logger class with trace/debug/info/warn/error/fatal methods that emit structured JSON records
• A streams system for routing log output to stdout, files, rotating files, or raw destinations at independent levels
• The bunyan CLI for pretty-printing, coloring, and filtering JSON log streams with -c expressions
• log.child() for creating specialized sub-loggers that inherit and extend a parent’s bound fields
• Standard serializers for formatting common objects like HTTP requests, responses, and Error instances

Common Use Cases

• Structured application logging for services that ship logs to aggregators like ELK, Splunk, or Papertrail
• Local development debugging via the bunyan CLI piped from node app.js | bunyan
• Request/response logging in HTTP servers using the built-in req/res serializers
• DTrace-based runtime log snooping in production Node.js processes on supporting platforms

Under The Hood

Architecture Bunyan’s core is a single flat module (lib/bunyan.js, ~1600 lines) implementing a monolithic Logger constructor plus auxiliary RotatingFileStream and RingBuffer classes in the same file, with no internal layering or dependency injection — Logger.prototype methods (addStream, addSerializers, child, level, _emit) mutate instance state directly, mkLogEmitter() closures generate the six level methods, and _emit()/mkRecord() build the JSON record and fan it out over the streams array registered via addStream(). The bundled bunyan CLI is a separate execution path that parses piped JSON and renders it, so the logging path and the CLI’s rendering path share only the stability of the record’s JSON shape — changing mkRecord/fastAndSafeJsonStringify would ripple through every stream type and the CLI parser alike.

Tech Stack Bunyan is plain CommonJS Node.js written in ES5-era JavaScript (var-based, no TypeScript). Its only hard dependency is exeunt; optional dependencies (dtrace-provider, mv, safe-json-stringify, moment) unlock DTrace probing, rotating-file streams, safer JSON stringification, and local-time formatting respectively, and are gracefully skipped when absent. Build and style checks run through a Makefile (check-jsstyle, versioncheck) rather than a modern bundler, and it ships both as an importable library and a CLI binary (bin/bunyan). GitHub Actions runs npm ci plus npm test/npm run check across Ubuntu, Windows, and macOS.

Code Quality Real test coverage exists under test/ (numerous *.test.js files such as log.test.js, add-stream.test.js, serializers.test.js, ctor.test.js) using the tap framework, and CI exercises them on three operating systems. Error handling favors defensive assertions (assert.ok) and try/catch fallbacks for optional dependencies over typed error propagation, the codebase is untyped JavaScript with no shipped type definitions, and style is enforced via Joyent’s jsstyle tool rather than a modern linter like ESLint.

What Makes It Unique At release, treating every log line as canonical, self-describing JSON with a small stable set of core fields and deferring human-readable rendering to a separate CLI was a genuinely influential structured-logging design that shaped later Node.js loggers. Today the pattern is standard practice (seen in comparable loggers), and the project itself has been largely dormant, with its 2.x line stuck in a years-long beta and infrequent recent maintenance.