Configuration

Complete configuration reference for 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:

1. x-forwarded-for — uses the first (leftmost) IP in the comma-separated list (the original client when behind proxies)
2. 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:

1. 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.
2. 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

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'
      }
    }
  }
})