Configuration

Config Array

The second argument to createLogger is an optional config array that defines the output pipeline:

import { createLogger } from "loggily"

const log = createLogger("myapp", [
  { level: "debug", ns: "-sql", format: "json" },
  console,
  { file: "/tmp/app.log", level: "error", format: "json" },
])

Config Object Keys

Key	Type	Description
level	LogLevel	Minimum log level
ns	string | string[]	Namespace filter pattern
format	"console" | "json"	Output format
spans	boolean	Enable/disable span output (per-pipeline)
metrics	boolean	Auto-create MetricsCollector, accessible via log.metrics
idFormat	"simple" | "w3c"	Trace/span ID format (default: "simple")
sampleRate	number (0.0 -- 1.0)	Head-based trace sampling rate (default: 1.0)

Sink Object Keys

Key	Type	Description
file	string	Path for file output
level	LogLevel (optional)	Override level for this sink
ns	string | string[] (optional)	Override ns for this sink
format	"console" | "json" (optional)	Override format for this sink

Stage Functions

Functions in the config array are called for every event:

type Stage = (event: Event) => Event | null | void

• Return the event (possibly modified) to pass it through
• Return null to filter it out
• Return void/undefined to pass the original event through

Branch Arrays

Arrays in the config array create sub-pipelines with their own scope:

const log = createLogger("myapp", [
  console,
  [{ ns: "myapp:metrics", format: "json" }, { file: "/tmp/metrics.log" }],
])

Namespace Filter Patterns

The ns config key and the DEBUG environment variable accept the same filter syntax:

Pattern	Matches
*	Everything
myapp	Exact match + children (myapp, myapp:db, myapp:db:query)
myapp:*	Same as myapp — explicit wildcard
myapp*	debug-package glob: * is any run of characters anywhere in the pattern (myapp, myapp:db, myappx; app:*:query matches app:db:query)
myapp:db	Exact match + children (myapp:db, myapp:db:query)
-myapp:sql	Exclude myapp:sql and its children
myapp,-myapp:sql	Include myapp, exclude sql subtree

Patterns are comma-separated. Include patterns are matched first; if any include pattern matches, the namespace passes. Exclude patterns (prefixed with -) take priority over includes.

When no include patterns are specified, all namespaces pass (only excludes are applied). When include patterns are present, a namespace must match at least one include and no excludes.

DEBUG='*' bun run app                     # Everything
DEBUG=myapp bun run app                   # myapp and all children
DEBUG='myapp,-myapp:sql' bun run app      # myapp tree, excluding sql subtree
DEBUG='myapp:db,myapp:cache' bun run app  # Only db and cache subtrees

Environment Variables

console literal and "console" string are both accepted as console sinks.

withEnvDefaults

createLogger includes the withEnvDefaults() plugin by default. When no config array is provided, it reads from environment variables:

Variable	Values	Default
LOG_LEVEL	trace, debug, info, warn, error, silent	info
LOG_FORMAT	console, json	console
LOG_FILE	file path	(none)
DEBUG	*, namespace prefixes, -prefix	(none)
TRACE	1, true, namespace prefixes	(none)
TRACE_FORMAT	json	(none)
TRACE_ID_FORMAT	simple, w3c	simple
TRACE_SAMPLE_RATE	0.0 -- 1.0	1.0
NODE_ENV	production	(none)

Pipeline Builder (power users)

import { buildPipeline } from "loggily"

// Build a custom pipeline
const pipeline = buildPipeline([
  { level: "debug" },
  console,
  { file: "/tmp/app.log", format: "json" },
])

Deprecated API

These functions still work but are deprecated. They map to environment variables internally:

// All deprecated — use config array or env vars instead
setLogLevel(level: LogLevel): void     // -> LOG_LEVEL env var
getLogLevel(): LogLevel

setLogFormat(format: LogFormat): void  // -> LOG_FORMAT env var
getLogFormat(): LogFormat

enableSpans(): void                    // -> TRACE=1 env var
disableSpans(): void
spansAreEnabled(): boolean

setTraceFilter(ns: string[] | null): void  // -> TRACE env var
getTraceFilter(): string[] | null

setDebugFilter(ns: string[] | null): void  // -> DEBUG env var
getDebugFilter(): string[] | null

setOutputMode(mode: OutputMode): void  // -> omit console from config array
getOutputMode(): OutputMode

setSuppressConsole(value: boolean): void // -> omit console from config array

Browser Support

Loggily includes a browser-optimized entry point that excludes Node.js-specific features (file writers, node:fs). Bundlers automatically select it via the browser condition in package.json exports.

Features available in browser: logging, spans, child loggers, custom stages, tracing utilities, OpenTelemetry bridge (loggily/otel).

Features Node.js only: file sinks ({ file: ... }), context propagation (loggily/context), worker threads (loggily/worker).

Calling createFileWriter() in a browser environment throws an error with a descriptive message.