Configuration - Logixlysia

Complete reference for all Logixlysia configuration options.

Configuration Object

All configuration options are passed through the config property:

logixlysia({
  preset: 'prod', // optional: 'dev' | 'prod' | 'json'
  config: {
    // ... configuration options (override preset)
  }
})

See Presets for defaults per environment.

Startup Options

`showStartupMessage`

Whether to display the startup message when the server starts.

Type: boolean
Default: true

showStartupMessage: true

`startupMessageFormat`

Format of the startup message.

Type: 'simple' | 'banner'
Default: 'banner'

startupMessageFormat: 'simple' // or 'banner'

Display Options

`useColors`

Enable colored output in console logs.

Type: boolean
Default: true

useColors: true

Colors require an interactive terminal: when stdout is not a TTY (Docker, CI, or output piped to a file), logs are printed uncolored even with useColors: true.

`ip`

Include client IP address in logs.

Type: boolean
Default: false

ip: true

How IP is resolved: The client IP is read from HTTP headers in this order:

x-forwarded-for — uses the first (leftmost) IP in the comma-separated list (the original client when behind proxies)
x-real-ip — fallback when x-forwarded-for is not present

These headers are typically set by reverse proxies (nginx, Caddy, Cloudflare, etc.) and load balancers. When testing locally (localhost or LAN) without a proxy, these headers are usually absent, so the {ip} placeholder will be empty. To test IP logging locally, you can pass a header manually, e.g. curl -H 'x-real-ip: 1.2.3.4' http://localhost:3000/.

`autoRedact`

Automatically redacts sensitive data from log messages, context objects, errors, and request headers before they are outputted. Redaction runs in two ways:

By key/header name — a built-in, case-insensitive denylist (authorization, cookie, x-api-key, password, secret, token, session, and more) wholly redacts the value of any matching object key or request header, regardless of what the value looks like. -, _, and camelCase variants (x-api-key, x_api_key, xApiKey) all match.
By value pattern — emails, IP addresses, Luhn-valid payment card numbers, and JWTs are redacted wherever they appear in strings, even in fields not covered by the key denylist.

Value-pattern redaction is best-effort — it only catches values matching those specific shapes. Always prefer key-based redaction (redactKeys) for known sensitive fields instead of relying on their value happening to match a pattern.

Type: boolean
Default: false

autoRedact: true

`redactKeys`

Additional key/header names to redact when autoRedact is enabled, extending the built-in denylist. Matching is case-insensitive and normalizes -, _, and camelCase variants.

Type: string[]
Default: undefined

autoRedact: true,
redactKeys: ['x-internal-token', 'customerSsn']

`logErrorPayload`

Log the offending payload (found/errors) from validation errors. Off by default — a failed schema validation embeds the entire request body (passwords, tokens, card fields) in the error message, so leaving this off keeps those values out of your logs and transports.

Type: boolean
Default: false

logErrorPayload: true

`logQueryParams`

Include query parameters in the logged URL path.

Type: boolean
Default: false

logQueryParams: true

Timestamp Options

`timestamp`

Timestamp configuration.

Type: { translateTime?: string }
Default: undefined

timestamp: {
  translateTime: 'yyyy-mm-dd HH:MM:ss'
}

Formatting Options

`customLogFormat`

Custom log message format using placeholders.

Type: string
Default: undefined

customLogFormat: '{now} {level} {duration}ms {method} {pathname} {status}'

When customLogFormat is omitted, Logixlysia uses a built-in default that includes {now}, {service}, {icon}, {method}, {pathname}, {status}, {duration}, {message}, and {speed}. Available placeholders:

{now} - Current timestamp
{level} - Log level
{duration} - Request duration (formatted, e.g. 12ms, 1.5s)
{method} - HTTP method
{pathname} - Request path
{status} - Response status code
{statusText} - HTTP status text from Node’s http.STATUS_CODES (e.g. Not Found for 404)
{message} - Custom message
{icon} - Logixlysia fox (🦊); with colors enabled, a level-colored background chip around the emoji
{speed} - When duration is at or above verySlowThreshold, appends ⚡ slow (yellow when colors are on)
{service} - Service label from the service config option, shown as [name] (dim when colors are on); empty if unset
{ip} - Client IP (from x-forwarded-for or x-real-ip; see ip option)
{epoch} - Unix timestamp

`service`

Service name used by the {service} placeholder (evlog-style [my-app] prefix).

Type: string
Default: undefined (no prefix)

service: 'my-api'

`slowThreshold`

Duration threshold (ms) for green duration text when colors are enabled. Between this value and verySlowThreshold, duration is yellow.

Type: number
Default: 500

slowThreshold: 500

`verySlowThreshold`

Duration threshold (ms) at or above which duration is red (bold when colors are on) and the {speed} token adds ⚡ slow.

Type: number
Default: 1000

verySlowThreshold: 1000

`showContextTree`

When true, structured context passed to logger helpers is printed as tree lines under the main log line instead of being crammed into {message} on the same line.

Type: boolean
Default: true

showContextTree: true

`contextDepth`

How many levels of nested objects to expand in the context tree.

Type: number
Default: 1

contextDepth: 2

Output Options

`transports`

Array of custom transport implementations.

Type: Transport[]
Default: []

transports: [
  {
    log: async (level, message, meta) => {
      // Custom transport logic
    }
  }
]

`useTransportsOnly`

Use only transports, disable console and file logging.

Type: boolean
Default: false

useTransportsOnly: true

`disableInternalLogger`

Disable console logging.

Type: boolean
Default: false

disableInternalLogger: true

`disableFileLogging`

Disable file logging.

Type: boolean
Default: false

disableFileLogging: true

`onError`

Called when a sink (transport, file, or rotation) or an enricher fails. Errors thrown by the hook itself are swallowed. When absent, failures go to stderr (rate-limited for transports and enrichers).

Type: (context: { sink: 'transport' | 'file' | 'rotation' | 'enricher'; error: unknown }) => void
Default: undefined

onError: ({ sink, error }) => {
  metrics.increment(`logixlysia.sink_error.${sink}`)
}

`enrichers`

Context contributors run on every request. Whatever they return is merged into the request context, so the fields reach the console tree, file logs, and every transport at once. See Enrichers.

Type: EnricherLike[]
Default: undefined

import { geoEnricher, traceparentEnricher } from 'logixlysia/enrichers'

enrichers: [
  traceparentEnricher(),
  geoEnricher(),
  request => ({ tenant: request.headers.get('x-tenant') })
]

Sampling Options

`sampling`

Head + tail sampling. Head sampling keeps a percentage of records per level; tail sampling replays what head dropped once the finished request matches a rule. See Sampling for the full guide.

Type: { head?: Partial<Record<LogLevel, number>>; tail?: { status?: number; durationMs?: number; paths?: string[] }; maxBufferedPerRequest?: number }
Default: undefined (no sampling)

sampling: {
  head: { DEBUG: 1, INFO: 10 }, // levels left out keep 100%
  tail: {
    status: 400, // rescue any response at or above 400
    durationMs: 1000, // rescue anything that took a second or longer
    paths: ['/checkout/**'] // rescue these routes whatever happened
  },
  maxBufferedPerRequest: 100
}

Sampling is off unless at least one head rate is below 100 — tail alone rescues nothing, because only head-dropped records are buffered. Invalid values throw at plugin construction.

File Logging Options

`logFilePath`

Path to the log file.

Type: string
Default: undefined

logFilePath: './logs/app.log'

`logRotation`

Log rotation configuration.

Type: LogRotationConfig
Default: undefined

logRotation: {
  maxSize: '10m',
  maxFiles: '7d',
  compress: true
}

`logRotation.maxSize`

Maximum file size before rotation.

Type: string | number
Format: '1k', '1m', '1g' or bytes

maxSize: '10m'

`logRotation.interval`

Rotate when the live log file’s age reaches the given interval. Evaluated on write — an idle process does not rotate until it logs again. See Log Rotation for details.

Type: string
Format: '1h', '1d', '1w'

`logRotation.maxFiles`

Maximum number of files or retention period.

Type: number | string
Format: Number or '7d', '30d'

maxFiles: '7d' // or 10

`logRotation.compress`

Enable compression for rotated logs.

Type: boolean
Default: false

compress: true

`logRotation.compression`

Compression algorithm.

Type: 'gzip'
Default: 'gzip'

compression: 'gzip'

Pino Options

`pino`

Pino logger configuration. Accepts all Pino options.

Type: PinoLoggerOptions & { prettyPrint?: boolean | object }
Default: undefined

pino: {
  level: 'info',
  prettyPrint: true,
  redact: ['password', 'token'],
  base: {
    service: 'my-api',
    version: '1.0.0'
  }
}

Common Pino Options

`pino.level`

Minimum log level.

Type: 'fatal' | 'error' | 'warn' | 'info' | 'debug' | 'trace'
Default: 'info'

pino: {
  level: 'debug'
}

`pino.prettyPrint`

Enable pretty printing for development.

Type: boolean | object
Default: false

pino: {
  prettyPrint: true
}

Or with options:

pino: {
  prettyPrint: {
    colorize: true,
    translateTime: 'HH:MM:ss Z',
    ignore: 'pid,hostname'
  }
}

Common prettyPrint Options

Option	Type	Description
`colorize`	`boolean`	Enable colors in output
`translateTime`	`string \| boolean`	Format timestamps
`ignore`	`string`	Comma-separated keys to exclude
`singleLine`	`boolean`	Print each log on one line
`messageFormat`	`string`	Custom message format
`levelFirst`	`boolean`	Show level before timestamp
`messageKey`	`string`	Key containing log message
`errorKey`	`string`	Key containing error info

See pino-pretty documentation for complete reference.

`pino.redact`

Redact sensitive fields from logs.

Type: string[] | object
Default: undefined

pino: {
  redact: ['password', 'token', 'apiKey']
}

Or with paths:

pino: {
  redact: {
    paths: ['user.password', 'req.headers.authorization'],
    remove: true
  }
}

`pino.base`

Base fields added to all logs.

Type: object
Default: undefined

pino: {
  base: {
    service: 'my-api',
    version: '1.0.0',
    environment: process.env.NODE_ENV
  }
}

Complete Example

logixlysia({
  config: {
    // Startup
    showStartupMessage: true,
    startupMessageFormat: 'banner',
    
    // Display
    useColors: true,
    ip: true,
    autoRedact: false,
    logQueryParams: false,
    
    // Formatting
    timestamp: {
      translateTime: 'yyyy-mm-dd HH:MM:ss'
    },
    customLogFormat: '{now} {level} {duration}ms {method} {pathname} {status}',
    
    // File Logging
    logFilePath: './logs/app.log',
    logRotation: {
      maxSize: '100m',
      maxFiles: '30d',
      compress: true
    },
    
    // Output Control
    disableInternalLogger: false,
    disableFileLogging: false,
    useTransportsOnly: false,
    transports: [],
    
    // Pino
    pino: {
      level: 'info',
      prettyPrint: false,
      redact: ['password', 'token'],
      base: {
        service: 'my-api',
        version: '1.0.0'
      }
    }
  }
})

​Configuration Object

​Startup Options

​showStartupMessage

​startupMessageFormat

​Display Options

​useColors

​ip

​autoRedact

​redactKeys

​logErrorPayload

​logQueryParams

​Timestamp Options

​timestamp

​Formatting Options

​customLogFormat

​service

​slowThreshold

​verySlowThreshold

​showContextTree

​contextDepth

​Output Options

​transports

​useTransportsOnly

​disableInternalLogger

​disableFileLogging

​onError

​enrichers

​Sampling Options

​sampling

​File Logging Options

​logFilePath

​logRotation

​logRotation.maxSize

​logRotation.interval

​logRotation.maxFiles

​logRotation.compress

​logRotation.compression

​Pino Options

​pino

​Common Pino Options

​pino.level

​pino.prettyPrint

​Common prettyPrint Options

​pino.redact

​pino.base

​Complete Example