Registry / serialization / logfmt

logfmt

JSON →
library0.4jsnpmunverified

logfmt is a Node.js library for working with the key-value logging convention popularized by Heroku. It provides functionalities for both serializing JavaScript objects into logfmt strings (e.g., `foo=bar a=14 baz="hello kitty"`) and parsing logfmt strings back into objects. The library also includes streaming capabilities for processing logfmt data from sources like `stdin` or HTTP requests, making it suitable for creating logplex drains or general structured log consumption/production. Currently at version 1.4.0, the package has not seen active development or releases since 2018, indicating an abandoned status. Its key differentiator is its direct support for the logfmt format, unlike general-purpose JSON loggers, making it specific to ecosystems leveraging this convention.

serializationobservability
npm install logfmt
github ↗package ↗
INSTALL
IMPORT
SIG · LOGFMT
L
logfmt
serializationjavascriptv0.4
Install
—
Import
—
Disk
—
Pass rate
0/ 6
Env Coverage0 / 6
glibc
18–22
musl
18–22
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
node 18–226 runs
build_error
glibc
node 18–226 runs
build_error
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

logfmt
✓ const logfmt = require('logfmt');
✗ import logfmt from 'logfmt';
The library is primarily CommonJS. While some bundlers may shim `import logfmt from 'logfmt'`, `require()` is the intended and most reliable way to import the module.
logfmt.stringify
✓ const logfmt = require('logfmt'); logfmt.stringify({ key: 'value' });
✗ import { stringify } from 'logfmt';
Functions like `stringify` are properties of the main `logfmt` module object, not named exports for direct destructuring in CommonJS or ESM without specific configuration.
logfmt.parse
✓ const logfmt = require('logfmt'); logfmt.parse('key=value');
✗ const parse = require('logfmt').parse;
While `require('logfmt').parse` works, the module is designed as a singleton object, so accessing methods directly from the main `logfmt` constant is idiomatic.
logfmt.streamParser
✓ const logfmt = require('logfmt'); process.stdin.pipe(logfmt.streamParser());
Used for creating a readable stream that parses incoming logfmt lines into JavaScript objects. Requires piping from another stream.

Demonstrates basic `stringify` and `parse` operations, then shows how to use `streamParser` to process logfmt data from a simulated stream.

const logfmt = require('logfmt'); const through = require('through'); // often used for stream manipulation // --- Non-streaming usage --- const data = { status: 200, method: 'GET', path: '/api/items', duration_ms: 50 }; const logString = logfmt.stringify(data); console.log('Stringified:', logString); // Expected: Stringified: status=200 method=GET path=/api/items duration_ms=50 const parsedObject = logfmt.parse('status=200 method=GET path=/api/items duration_ms=50'); console.log('Parsed:', parsedObject); // Expected: Parsed: { status: '200', method: 'GET', path: '/api/items', duration_ms: '50' } // --- Streaming usage (parsing logfmt from a simulated input) --- const { Readable } = require('stream'); const simulatedInput = new Readable({ read() { this.push('metric=cpu_usage value=0.5 host=web-01\n'); this.push('metric=memory_free value=1024 host=db-01\n'); this.push(null); // No more data } }); console.log('\n--- Streaming Parse Output ---'); simulatedInput .pipe(logfmt.streamParser()) .pipe(through(function(obj) { console.log('Streamed Object:', obj); })); // Expected: Streamed Object: { metric: 'cpu_usage', value: '0.5', host: 'web-01' } // Expected: Streamed Object: { metric: 'memory_free', value: '1024', host: 'db-01' }
Debug
Known issues
breakingThe `logfmt` package appears to be abandoned. The last commit on GitHub was in June 2018, and the last release was in February 2018. This means there will be no further bug fixes, security patches, or feature development. Using this library in new projects is strongly discouraged.
fix
Consider alternatives for structured logging like `pino`, `winston`, or `bunyan` which offer active maintenance and modern features. If logfmt format is strictly required, fork the repository or use a more actively maintained logfmt parser/stringifier if one exists.
affects: >=1.0.0
gotchaThe `logfmt.parse()` method does not automatically convert all numeric strings to numbers. It only converts `true` and `false` strings to booleans. Numbers are parsed as strings to avoid precision loss issues with 32-bit representations.
fix
Manually cast values to numbers after parsing if numeric operations are required: `const parsed = logfmt.parse('count=123'); const count = parseInt(parsed.count, 10);`
affects: >=1.0.0
gotchaThe `logfmt` module is a singleton when imported via `require('logfmt')`. Any modifications to its properties (e.g., `logfmt.stringify = JSON.stringify`) will affect all parts of your application that use this global instance.
fix
To create an independent, configurable instance, use `const customLogfmt = new logfmt();`. This will allow you to modify `customLogfmt` without affecting the main singleton instance.
affects: >=1.0.0
gotchaThe library primarily targets CommonJS environments and does not officially support ES Modules (ESM). While bundlers might transpile it, direct ESM `import` statements may behave unexpectedly or require specific configuration.
fix
For Node.js projects, use `const logfmt = require('logfmt');`. If an ESM-only project needs this, consider a wrapper or transpilation, but be aware of potential issues due to its age and CJS-centric design.
affects: >=1.0.0
Errors
Common errors & fixes
TypeError: logfmt.stringify is not a function
Attempting to call `stringify` or other methods on an undefined `logfmt` object, or if the `logfmt` variable was reassigned.
fix
Ensure `const logfmt = require('logfmt');` is correctly placed and executed before calling any methods on `logfmt`. Verify no other code is inadvertently overwriting the `logfmt` variable.
TypeError: Cannot read properties of undefined (reading 'pipe')
This typically occurs when attempting to `pipe` to a `logfmt.streamParser()` or `logfmt.streamStringify()` instance, but the stream object itself is undefined or not a valid stream.
fix
Check that the stream being piped from (e.g., `process.stdin`, `req`, a `Readable` stream) is properly initialized and available. Ensure `logfmt.streamParser()` or `logfmt.streamStringify()` are correctly called without errors.
SyntaxError: Unexpected token 'o' at JSON.parse (<anonymous>)
This error happens when a logfmt string is accidentally passed to `JSON.parse()`. Logfmt is a key-value format, not JSON.
fix
Use `logfmt.parse(yourLogfmtString)` to correctly parse logfmt strings into JavaScript objects. Reserve `JSON.parse()` for actual JSON strings.
ReferenceError: logfmt is not defined
The `logfmt` variable was used without being declared or initialized, usually by omitting the `require` statement.
fix
Add `const logfmt = require('logfmt');` at the top of your file to properly import the module.
Upgrade
Version history
0.4latest on npm
Audit
Dependencies

No dependency data recorded yet.

Agent activity
10 hits · last 30 days
node
8
OpenAI (training)
2
Resources
githubhttps://github.com/csquared/node-logfmt ↗
packagehttps://www.npmjs.com/package/logfmt ↗