@getlogflow/js

Official JavaScript/TypeScript SDK for LogFlow — cloud log management for developers.

Installation

npm install @getlogflow/js

Quick Start

import LogFlow from '@getlogflow/js'

const logger = new LogFlow({
  apiKey: process.env.LOGFLOW_API_KEY!,
  service: 'api',           // rename per microservice
  environment: 'production',
  release: 'v1.4.2',        // optional — shown in log details
})

logger.info('Server started', { port: 3000 })
logger.warn('Rate limit approaching', { userId: 'u_123', remaining: 5 })
logger.error('Payment failed', { orderId: 'ord_456', code: 'CARD_DECLINED' })

Logs are batched and sent automatically every 5 seconds (or when 10 logs accumulate). No need to manually flush during normal operation.

Log Levels

logger.trace('Detailed debug info')
logger.debug('Query executed', { sql: '...', durationMs: 12 })
logger.info('User signed up', { userId: 'u_123' })
logger.warn('Disk usage high', { percent: 87 })
logger.error('Request failed', { path: '/checkout', status: 500 })
logger.fatal('Database unreachable', { host: 'db.prod' })

Attributes

Pass any key/value pairs as the second argument. Values are automatically converted to strings.

logger.info('Order shipped', {
  orderId: 'ord_789',
  userId: 'u_123',
  amount: 4999,           // number → "4999"
  items: ['book', 'pen'], // array → '["book","pen"]'
  carrier: { name: 'UPS', tracking: '1Z...' }, // object → JSON string
})

Trace ID — Request Correlation

Pass traceId (and optionally spanId) to group all logs from a single request. In LogFlow you can click View trace to see the full request timeline.

import { randomUUID } from 'crypto'

app.use((req, res, next) => {
  req.traceId = req.headers['x-trace-id'] || randomUUID()
  res.setHeader('x-trace-id', req.traceId)
  next()
})

app.post('/orders', async (req, res) => {
  logger.info('Order received', { traceId: req.traceId, userId: req.user.id })

  const order = await createOrder(req.body)
  logger.info('Order created', { traceId: req.traceId, orderId: order.id })

  res.json(order)
})

Child Loggers

Create child loggers that automatically include fixed attributes in every log. Ideal for per-request or per-user context.

// Root logger
const logger = new LogFlow({ apiKey: '...', service: 'api' })

// Per-request child — carries requestId and userId automatically
app.use((req, res, next) => {
  req.log = logger.child({ traceId: req.traceId, userId: req.user?.id })
  next()
})

app.post('/checkout', async (req, res) => {
  req.log.info('Checkout started')                          // traceId + userId included
  req.log.info('Cart validated', { items: cart.length })   // traceId + userId + items
  req.log.error('Stock check failed', { sku: 'ABC-123' })  // traceId + userId + sku
})

// Nest further — child of a child
const dbLog = req.log.child({ layer: 'database' })
dbLog.debug('Query start', { table: 'orders' })

Auto-Flush on Exit

By default the SDK registers handlers for SIGTERM, SIGINT, and beforeExit so pending logs are flushed before the process exits. No manual setup needed.

// These are registered automatically (autoFlushOnExit: true by default)
// process.on('SIGTERM', ...) ← handled
// process.on('SIGINT',  ...) ← handled
// process.on('beforeExit', ...) ← handled

// To opt out and manage shutdown yourself:
const logger = new LogFlow({ apiKey: '...', autoFlushOnExit: false })

process.on('SIGTERM', async () => {
  await logger.destroy()
  process.exit(0)
})

Winston Transport

import winston from 'winston'
import { LogFlowWinstonTransport } from '@getlogflow/js/transports/winston'

const logger = winston.createLogger({
  level: 'info',
  transports: [
    new winston.transports.Console(),
    new LogFlowWinstonTransport({
      apiKey: process.env.LOGFLOW_API_KEY!,
      service: 'api',
      environment: 'production',
    }),
  ],
})

logger.info('Server started', { port: 3000 })
logger.error('Unhandled error', { stack: err.stack })

Pino Transport

import pino from 'pino'
import { createLogFlowStream } from '@getlogflow/js/transports/pino'

const logger = pino(
  { level: 'info' },
  createLogFlowStream({
    apiKey: process.env.LOGFLOW_API_KEY!,
    service: 'api',
    environment: 'production',
  })
)

logger.info({ userId: 'u_123' }, 'User signed in')
logger.error({ err }, 'Request failed')

Multi-stream (console + LogFlow):

import pino from 'pino'
import { multistream } from 'pino-multi-stream'
import { createLogFlowStream } from '@getlogflow/js/transports/pino'

const logger = pino({ level: 'info' }, multistream([
  { stream: process.stdout },
  { stream: createLogFlowStream({ apiKey: process.env.LOGFLOW_API_KEY!, service: 'api' }) },
]))

Options

| Option | Default | Description | |--------|---------|-------------| | apiKey | required | Your LogFlow API key (lf_...) | | service | — | Service name tag for all logs (e.g. 'api', 'worker') | | environment | — | Environment tag added to every log (e.g. 'production') | | release | — | Release/version tag (e.g. 'v1.4.2') | | host | — | Hostname/instance tag | | batchSize | 10 | Flush after N logs are queued | | flushInterval | 5000 | Auto-flush every N ms | | maxRetries | 3 | Retry attempts on network failure | | maxQueueSize | 1000 | Max logs held offline (oldest dropped) | | autoFlushOnExit | true | Flush on SIGTERM / SIGINT / beforeExit | | baseUrl | https://api.getlogflow.com | API base URL | | onError | — | Callback when all retries are exhausted |

API Reference

| Method | Description | |--------|-------------| | logger.info(msg, attrs?) | Log at info level | | logger.warn(msg, attrs?) | Log at warn level | | logger.error(msg, attrs?) | Log at error level | | logger.debug(msg, attrs?) | Log at debug level | | logger.trace(msg, attrs?) | Log at trace level | | logger.fatal(msg, attrs?) | Log at fatal level | | logger.child(defaults) | Create child logger with fixed attributes | | logger.flush() | Force-send all queued logs now | | logger.destroy() | Flush + clean up timers and listeners |