@pulsar/node

Node.js SDK for Pulsar — automatic trace context, console interception, and structured logging.

Install

npm install @pulsar/node

Quick Start

Mode 1 — Intercept console automatically

import { Pulsar } from '@pulsar/node'

Pulsar.init({
  url: 'https://your-pulsar-instance.com',
  apiKey: 'psk_your_api_key',
  interceptConsole: true,
})

console.log('This goes to Pulsar')
console.error('This too')

Mode 2 — Structured logger

import { Pulsar } from '@pulsar/node'

Pulsar.init({
  url: 'https://your-pulsar-instance.com',
  apiKey: 'psk_your_api_key',
})

const logger = Pulsar.createLogger({ serviceName: 'my-api' })

logger.info('Server started')
logger.error('Request failed', { traceId: '123' })

Express Middleware (Automatic Trace ID)

The middleware uses AsyncLocalStorage to automatically attach a traceId to every log within a request lifecycle. Zero config needed.

import express from 'express'
import { Pulsar } from '@pulsar/node'

Pulsar.init({
  url: 'https://your-pulsar-instance.com',
  apiKey: 'psk_your_api_key',
  interceptConsole: true,
})

const app = express()
app.use(Pulsar.middleware())

app.get('/api/users', (req, res) => {
  // traceId is automatically included in these logs
  console.log('Fetching users')
  console.log('Found 42 users')
  res.json([])
})

In Pulsar, clicking on any log shows all other logs from the same request — Magic Context.

The middleware:

1. Reads x-trace-id header if present, otherwise generates a UUID
2. Stores { traceId, method, url } in AsyncLocalStorage
3. All console.log/warn/error and logger.* calls within that request automatically include the traceId

Options

| Option | Type | Default | Description | |--------|------|---------|-------------| | url | string | — | Pulsar server URL (required) | | apiKey | string | — | API key (required) | | serviceName | string | 'default' | Service name in Pulsar | | interceptConsole | boolean | false | Monkey-patch console.log/warn/error | | batchSize | number | 50 | Logs buffered before flush | | flushInterval | number | 2000 | Flush interval in ms |

Shutdown

// Flush remaining logs before exiting
await Pulsar.shutdown()

Features

• Automatic trace ID via AsyncLocalStorage + Express middleware
• Console interception (original output preserved)
• Structured logger with levels (trace, debug, info, warn, error, fatal)
• Batched delivery with retry and exponential backoff
• In-memory queue — no logs lost on temporary failures
• Zero runtime dependencies
• TypeScript types included
• Dual CJS/ESM package

License

MIT