node-logfmt

logfmt is a small Node.js library for working with the logfmt convention popularized by Heroku for structured, greppable log lines (key=value key2="value two"). It exposes a single require(‘logfmt’) singleton with parse() and stringify() functions for converting between logfmt strings and JavaScript objects, a log() method for writing structured log lines to a stream, and streaming variants (streamParser(), streamStringify()) for piping logfmt data through Node streams.

Beyond the core parser, the library ships request-logging and body-parsing middleware for Express and restify (both buffered and streaming), a namespace() helper for attaching constant fields to every log call, and a time() helper for logging elapsed durations. A bundled logfmt/logfmt -r CLI converts between logfmt and JSON on STDIN, making round-tripping and ad hoc log inspection possible from the shell.

What You Get

• logfmt.parse(string) / logfmt.stringify(object) for converting between logfmt lines and plain JS objects, preserving big numbers as strings to avoid precision loss
• logfmt.log(object, [stream]) for writing a structured log line to any writable stream (defaults to stdout)
• logfmt.streamParser() and logfmt.streamStringify([options]) for piping logfmt data through Node.js Readable/Writable streams
• logfmt.bodyParser() / logfmt.bodyParserStream() Express/restify middleware for consuming application/logplex-1 request bodies (e.g. Logplex drains)
• logfmt.requestLogger([options], [formatter]) middleware that logs each HTTP request/response in an Apache-Common-Log-like logfmt line
• logfmt.namespace(object) and logfmt.time([label]) helpers for attaching constant fields or elapsed-time tracking to every subsequent log call
• A logfmt / logfmt -r command-line tool for converting logfmt lines to JSON and back from STDIN

Common Use Cases

• Emitting structured, greppable application logs from a Node service in the logfmt convention used by Heroku and similar platforms
• Writing a Logplex/HTTP drain that receives application/logplex-1 request bodies and needs to parse them into objects
• Adding request logging to an Express or restify app without pulling in a heavier logging framework
• Converting between logfmt and JSON on the command line when inspecting or reprocessing existing log files
• Tagging every log line from a given module or request with shared context fields via namespace()

Under The Hood

Architecture The package is a small, flat module tree: logfmt.js is a constructor function whose prototype is assembled from individual lib/*.js files (logfmt_parser, stringify, logger, streaming, body_parser, body_parser_stream, request_logger) via Object.assign, and the whole prototype is also copied onto the constructor itself so require('logfmt') works as both a ready-to-use singleton and a new logfmt factory for isolated instances (e.g. a separate error-stream logger). The bin/logfmt CLI is a thin wrapper that pipes STDIN through the same split/through-based streaming parser or stringifier used internally, so the CLI and the library share one code path with no separate parsing logic.

Tech Stack Plain CommonJS JavaScript with no build step or transpilation. Runtime dependencies are minimal — split (line-splitting a stream) and through (simple through-streams) — reflecting the library’s age and its stream-oriented design predating newer Node stream idioms. Express and restify appear only as devDependencies, used to exercise the bundled middleware in tests rather than as hard runtime dependencies, so the middleware is framework-agnostic beyond requiring an Express/restify-style (req, res, next) signature.

Code Quality Tests are written with Mocha (suite/test TDD-style interface, configured via test/mocha.opts) and cover parsing, stringifying, streaming, namespacing, timing, error formatting, and both request-logger and body-parser middleware in dedicated files. There is no TypeScript, no type annotations, and no linter/formatter configuration in the repo; error handling is minimal and mostly implicit (e.g. JSON.parse in the CLI’s reverse mode is not wrapped in a try/catch). The hand-rolled character-by-character parser in lib/logfmt_parser.js is dense and uses several boolean state flags rather than a more structured tokenizer, trading readability for a small, dependency-free implementation.

What Makes It Unique Unlike general-purpose structured loggers, this library treats the logfmt format itself as the primary abstraction — parser and stringifier are the base primitives, and logging, request-logging, and body-parsing are all thin layers built on top of them. That symmetry is what lets the same code parse incoming logs (e.g. from a Logplex drain) and emit outgoing ones, and lets the CLI round-trip logfmt through JSON and back using nothing but the library’s own public API.