Configuration

lumber.config(options)

Call once at application startup, before any logging. Calling a log method before lumber.config() throws.

Calling lumber.config() again replaces the client. Logs still queued in the previous client keep sending in the background, but lumber.flush() only waits for the new client's queue, so call await lumber.flush() before reconfiguring if you need to be sure they're delivered. Use LumberClient if you need more than one configured instance.

import lumber from '@infinitetoken/lumber'

lumber.config({
  apiKey: process.env.LUMBER_API_KEY!,
  encryptionKey: process.env.LUMBER_ENCRYPTION_KEY!,
})

Options reference

apiKey · string · required

Bearer token for API authentication: a 32-character hexadecimal string. Create one in the Lumber mobile app on your app's Secrets screen. It's shown only once. See Authentication.

apiKey: process.env.LUMBER_API_KEY!

encryptionKey · string · required

32-byte AES-256-GCM symmetric key, base64-encoded. All log content is encrypted with this key before leaving your process. The Lumber app generates it on your device when you create an app, and you can copy it from the app's Secrets screen. lumber.config() (and new LumberClient()) throws a RangeError if the value doesn't decode to exactly 32 bytes.

encryptionKey: process.env.LUMBER_ENCRYPTION_KEY!

endpoint · string · optional

Override the Lumber API base URL (no trailing path). Defaults to the official Lumber API, https://api.lumber.infinitetoken.com. Useful for routing through a proxy. The SDK posts each log to {endpoint}/logs.

endpoint: 'https://your-proxy.example.com'

console · boolean | ConsoleOptions · optional

Echo logs to stdout/stderr. Disabled by default.

true - all levels, message only, colored prefix when TTY.

Object form:

console: {
  levels?: Partial<Record<'debug' | 'info' | 'warn' | 'error' | 'fatal', boolean>>
  prefix?: boolean    // show [DEBUG]/[INFO]/etc label - default true
  color?: boolean     // ANSI colors when TTY - default true
  data?: boolean      // append metadata after message - default false
  pretty?: boolean    // JSON.stringify extras with indentation - default false
  timestamp?: boolean | 'time' | 'iso' | 'relative'
}

timestamp values:

Example - development config:

lumber.config({
  apiKey: process.env.LUMBER_API_KEY!,
  encryptionKey: process.env.LUMBER_ENCRYPTION_KEY!,
  console: {
    timestamp: 'time',
    color: true,
    data: true,
    pretty: true,
    levels: { debug: process.env.NODE_ENV !== 'production' },
  },
})

context · boolean | ContextOptions · optional

Controls automatic environment context attached to every log. Defaults to true.

true - capture pid, hostname, and NODE_ENV (captured once at config time).

false - disable all context capture.

Object form:

context: {
  env?: boolean       // capture pid, hostname, NODE_ENV - default true
  caller?: boolean    // capture file/line/column per log - default false
  callerDepth?: number // extra stack frames to skip for wrapper layers - default 0
}

callerDepth is useful when you wrap the Lumber client:

// Your wrapper adds one frame to the stack
function log(msg: string) {
  lumber.info(msg)
}

// Without callerDepth, context.code points to this wrapper, not your caller
lumber.config({
  context: { caller: true, callerDepth: 1 },
})