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

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 PII (emails, IPs, credit cards, JWTs) from log messages, context objects, and errors before they are outputted.

• Type: boolean
• Default: false

autoRedact: 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

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',
  interval: '1d',
  maxFiles: '7d',
  compress: true
}

logRotation.maxSize

Maximum file size before rotation.

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

maxSize: '10m'

logRotation.interval

Time interval for rotation.

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

interval: '1d'

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',
      interval: '1d',
      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'
      }
    }
  }
})