Registry / observability / pino-http-send

pino-http-send

JSON →
library0.4.2jsnpmunverified

pino-http-send is a basic handler for Pino logs that facilitates sending batches of structured log data to a desired HTTP or HTTPS endpoint. Currently at version 0.4.2, it is pre-v1, meaning minor version changes may introduce breaking changes. The library supports configurable HTTP methods (POST, PUT, PATCH, GET), two body types (JSON array wrapped in a 'logs' object or newline-delimited JSON), and includes basic authentication and retry mechanisms for failed sends. It can be used either as a command-line interface tool, piping `pino` output directly, or programmatically via its `createWriteStream` API, which acts as a Pino destination. Its key differentiators include its simplicity in setting up a direct HTTP log sink, batching capabilities to optimize network requests, and built-in retry logic, making it a robust, low-overhead option for forwarding Pino logs.

npm install pino-http-send
INSTALL
IMPORT
SIG · PINO-HTTP-SEND
P
pino-http-send
observabilityjavascriptv0.4.2
Install
Import
Disk
Pass rate
0/ 6
Env Coverage0 / 6
glibc
1822
musl
1822
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 18226 runs
build_error
glibc
node 18226 runs
build_error
Code
Verified usage

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

createWriteStream
import { createWriteStream } from 'pino-http-send';
const createWriteStream = require('pino-http-send').createWriteStream;
While CommonJS `require` works, ESM `import` is preferred in modern Node.js environments. The function is a named export.
PinoHttpSendOptions
import type { PinoHttpSendOptions } from 'pino-http-send';
The options for `createWriteStream` are type-exported as PinoHttpSendOptions for TypeScript users, enabling strong typing for configuration.

Demonstrates programmatic usage of `pino-http-send` by creating a dummy HTTP server to receive logs and configuring Pino to send logs to it via `createWriteStream`.

import { createWriteStream } from 'pino-http-send'; import pino from 'pino'; import http from 'http'; // 1. Setup a dummy HTTP server to receive logs (your actual log ingestion endpoint) const server = http.createServer((req, res) => { if (req.url === '/logs' && req.method === 'POST') { let body = ''; req.on('data', (chunk) => { body += chunk.toString(); }); req.on('end', () => { try { console.log(`\n--- Received Batch (${req.headers['content-type']}) ---\n`); if (req.headers['content-type']?.includes('application/json')) { console.log(JSON.parse(body).logs); // 'json' bodyType wraps logs in { logs: [...] } } else { console.log(body); // 'ndjson' is raw new-line delimited JSON } console.log(`--- End Batch ---\n`); res.writeHead(200, { 'Content-Type': 'application/json' }); res.end(JSON.stringify({ status: 'ok', receivedLogsCount: body.split('\n').filter(Boolean).length })); } catch (e) { console.error('Error parsing received logs:', e); res.writeHead(400).end('Bad Request'); } }); } else { res.writeHead(404).end('Not Found'); } }); server.listen(3000, () => { console.log('Dummy log server listening on http://localhost:3000'); console.log('Sending logs via pino-http-send...'); // 2. Configure pino-http-send as a Pino destination const pinoSendStream = createWriteStream({ url: 'http://localhost:3000/logs', method: 'POST', bodyType: 'json', // or 'ndjson' batchSize: 2, // Send every 2 logs timeout: 1000, // or flush after 1 second if batch not full log: true, // Enable internal logging for pino-http-send itself headers: { 'X-Custom-Header': 'pino-test' } }); // 3. Create a Pino logger instance using the pino-http-send stream const logger = pino(pinoSendStream); let count = 0; const interval = setInterval(() => { logger.info({ id: ++count, service: 'my-app', event: 'data_processed', timestamp: new Date().toISOString() }); if (count >= 5) { clearInterval(interval); logger.flush(); // Ensure any buffered logs are sent setTimeout(() => { server.close(() => console.log('Dummy server closed. Exiting.')); }, 2000); // Give time for the last batch to be sent } }, 500); });
pino-http-send --version
Debug
Known issues
breakingAs a pre-v1 package (current version 0.4.2), `pino-http-send` explicitly states that it is 'subject to breaking changes on minor version change'. Users should expect potential API shifts and review changelogs when updating.
fix
Always pin to exact minor versions (e.g., `~0.4.0` or `0.4.2`) and review release notes carefully before upgrading minor versions.
affects: >=0.1.0
gotchaThe CLI usage for `pino-http-send` only supports basic authentication via `--username` and `--password` flags. Custom HTTP headers for authentication (e.g., Bearer tokens) or other purposes are not supported via the CLI and must be configured when using the programmatic `createWriteStream` API.
fix
For custom headers, use the `createWriteStream` API and pass a `headers` object in the options. Example: `createWriteStream({ url: '...', headers: { 'Authorization': 'Bearer YOUR_TOKEN' } })`.
affects: >=0.1.0
gotchaWhen using `bodyType: 'json'`, `pino-http-send` wraps the batch of logs in an object with a `logs` key (e.g., `{ logs: [...] }`). If your receiving endpoint expects a direct JSON array of logs, this will cause parsing issues. Conversely, `ndjson` sends new-line delimited JSON objects.
fix
Ensure your log ingestion endpoint is aware of and correctly parses the specific `bodyType` used by `pino-http-send`. If `json` is used, it should expect an object with a `logs` property containing the array. If `ndjson` is used, it should parse each line as a separate JSON object.
affects: >=0.1.0
Errors
Common errors & fixes
Error: Missing required argument: url
Attempting to run `pino-http-send` via the CLI without providing the `--url` argument, which is mandatory.
fix
Specify the target URL using `--url` or `-u` flag. Example: `pino-http-send --url=http://your-log-endpoint.com/logs`.
TypeError: createWriteStream is not a function
Incorrectly importing `createWriteStream` using a default import or a CommonJS `require` statement that expects a default export.
fix
Ensure `createWriteStream` is imported as a named export. For ESM: `import { createWriteStream } from 'pino-http-send';`. For CommonJS: `const { createWriteStream } = require('pino-http-send');`.
Received logs are not in expected format (e.g., missing 'logs' array or not NDJSON)
Mismatch between the `bodyType` configured in `pino-http-send` (e.g., 'json') and what the receiving server expects (e.g., 'ndjson' or a raw array).
fix
Verify that the `bodyType` option (`json` or `ndjson`) passed to `createWriteStream` or the CLI `--bodyType` flag matches the format your log ingestion endpoint is designed to consume. Adjust either the client configuration or the server's parsing logic accordingly.
Upgrade
Version history
0.4.2latest on npm
Audit
Dependencies
pinorequiredThis package acts as a transport for Pino logs; `pino` is required to generate the logs that `pino-http-send` will process and send.
Agent activity
20 hits · last 30 days
node
14
OpenAI (training)
2
Amazon
1
Resources