Configuration

Complete reference for all Logixlysia configuration options.

Configuration Object

All configuration options are passed through the config property:

logixlysia({
  config: {
    // ... configuration options
  }
})

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:

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/.

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

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

On this page