Loggily — Clarity without the clutter

Debugs, logs, and spans — structured and dev, server and browser — one API.

Replace debug + your JSON logger + ad-hoc timers with one namespace tree and one output pipeline. Pure TypeScript, zero dependencies, ~3 KB.

import {
  baseCreateLogger,
  createLogger,
  pipe,
  withConfigMetrics,
  withEnvDefaults,
  withRedaction,
  withSpans,
} from "loggily"

const log = createLogger("myapp") // zero config — reads LOG_LEVEL, DEBUG from env

log.info?.("server started", { port: 3000 })
log.debug?.("cache hit", { key: "user:42" })
log.error?.(new Error("connection lost"))

The ?. optional chaining trick short-circuits the entire call when a log level is disabled, so nothing evaluates — not the string interpolation, not the function calls, nothing. In benchmarks, that's ~22x faster than conventional noop loggers. See how Loggily compares →

Getting Started

Install from npm; a git install resolves the TypeScript source and runs only under Bun.

$ npm install loggily

$ DEBUG='*' node app                        # show all debug output
$ DEBUG='myapp:db' node app                 # only database logs
$ LOG_FILE=/tmp/app.log node app            # write to file
$ LOG_FORMAT=json node app                  # structured JSON output
$ TRACE=1 node app                          # enable span timing

import { createLogger } from "loggily"
import { toOtel } from "loggily/otel"

// Config pipeline — objects configure, arrays branch, values write
const log = createLogger("myapp", [
  { level: "debug", metrics: true }, // config object — sets scope
  toOtel({ api: otelApi }), // stage — forwards to Jaeger/Grafana/Datadog
  pinoTransport, // writable — { write } receives events
  { file: "...", format: "json" }, // file sink — formatted strings
  [{ level: "warn" }, { file: "..." }], // branch — sub-pipeline with own scope
  console, // human output; select JSON explicitly when needed
])

// Structured logging
log.info?.("server started", { port: 3000 })
log.debug?.(`state: ${expensiveFunc()}`) // skipped if debug off
log.error?.(new Error("connection lost"))

// Child loggers — extend namespace, add context
const dbLog = log.child("db", { pool: "main" }) // namespace: "myapp:db"

// Spans — time any operation, auto-track parent/child + trace IDs
// AsyncLocalStorage propagation: logs in async chains inherit span context
{
  using span = dbLog.span?.("query", { table: "users" })
  const users = await queryUsers() // logs inside queryUsers() get trace IDs
  if (span) span.spanData.count = users.length
}
// → SPAN myapp:db:query (45ms) {count: 100, table: "users"}

// Metrics — p50/p95/p99 from spans
log.metrics.summary() // myapp:db:query: 42 spans, mean=3.2ms, p95=8.4ms

// Composable — build custom factories
const myCreateLogger = pipe(
  baseCreateLogger,
  withRedaction(), // included by createLogger; explicit for custom factories
  withEnvDefaults(),
  withSpans(),
  withConfigMetrics(),
)

A long-lived service whose stderr is a supervisor's capture can park on its next log line once the reader stalls (under Bun, ~10 KB unread on a pty). loggily/sink moves the one blocking write to a writer thread: openLineSink({ fd: 2 }) takes whole lines from any thread and returns at once, bounds the bytes in flight, and says on the next written line how many lines it dropped meanwhile. setStderrLineWriter((line) => sink.push(line + "\n")) then routes every line loggily would put on fd 2 through that sink; setStderrLineWriter(null) restores the direct path.

Also supports async context propagation, worker threads, and browser.

Works with: OpenTelemetry (Jaeger, Grafana, Datadog, any OTLP backend) · Pino transports · Sentry · Elasticsearch · AWS CloudWatch · Prometheus · W3C Trace Context · DEBUG= patterns · See all destinations →

About

Born from the frustration of juggling separate systems for debug logging, structured production logs, metrics, and spans — each with its own API, config, and propagation — and then duplicating the whole setup again because browser and terminal needed completely different pipelines and destinations. Loggily unifies it all: one API, one config, one pipeline that works everywhere, without the overhead when logs are off.

Requirements: Node.js ≥ 23.6 or Bun ≥ 1.0. ESM-only. TypeScript 5.2+ for using (.end() works on any version). Browser supported via conditional export.

When not to use Loggily: if you need auto-instrumentation (HTTP, database, gRPC) use OpenTelemetry's SDK directly; if you need log rotation or dozens of transport plugins, Pino's ecosystem is deeper.

Docs: Get Started · Full docs · Comparison · Why Loggily

MIT