Custom Formatting

Customize log message formats using placeholders to match your logging needs. If you omit customLogFormat, Logixlysia uses a built-in default that includes the fox {icon}, optional {service} prefix, colored method and duration, {speed} for slow requests, and other common fields.

Basic Usage

logixlysia({
  config: {
    customLogFormat: '{now} {level} {duration}ms {method} {pathname} {status}'
  }
})

Available Placeholders

Placeholder	Description
`{now}`	Current date and time
`{level}`	Log level (`DEBUG`, `INFO`, `WARNING`, `ERROR`); with colors, level-colored background chip
`{duration}`	Request duration (e.g. `12ms`, `1.5s`); with colors, green / yellow / red based on `slowThreshold` and `verySlowThreshold`
`{method}`	HTTP method (padded in the default format)
`{pathname}`	Request path (alias: `{path}`); includes query string if `logQueryParams` is enabled
`{query}`	Raw query string (e.g. `?id=123`)
`{status}`	Response status code
`{statusText}`	Status text from Node’s `http.STATUS_CODES` (e.g. `Not Found` for 404)
`{message}`	Custom message
`{icon}`	Logixlysia fox `🦊`; plain emoji when `useColors` is off or output is not a TTY; with colors on a TTY, a level-colored background around the fox (green INFO, yellow WARNING, red ERROR, blue DEBUG)
`{speed}`	When duration ≥ `verySlowThreshold`, appends `⚡ slow` (yellow with colors)
`{service}`	From `config.service`, rendered as `[name]` (dim with colors); empty if unset
`{context}`	JSON string of `data.context` when the context tree is off or context is empty; omitted on the main line when the context tree is shown (see below)
`{ip}`	Client IP address (from `x-forwarded-for` or `x-real-ip`; empty when testing locally without these headers)
`{epoch}`	Unix timestamp

Examples

Minimal Format

customLogFormat: '{method} {pathname} {status}'

Output:

GET /api/users 200

Branded line with `{icon}` and `{service}`

Use {icon} for the Logixlysia fox (level styling applies when colors and a TTY are available). Pair with service in config:

logixlysia({
  config: {
    service: 'my-api',
    customLogFormat: '{now} {service}{icon} {method} {pathname} {status} {duration} {message}{speed}'
  }
})

With useColors: false or non-TTY output, a line can look like:

2025-04-13T15:00:19.123Z [my-api]🦊 GET     /api/users 200 12ms User viewed profile

On a color terminal, the fox appears inside a colored chip by level, and slow requests append ⚡ slow via {speed} when duration ≥ verySlowThreshold (default 1000).

Status text

customLogFormat: '{method} {pathname} {status} {statusText}'

Example values: 404 Not Found, 500 Internal Server Error.

Timestamp Format

Configure timestamp format separately:

logixlysia({
  config: {
    customLogFormat: '{now} {level} {method} {pathname}',
    timestamp: {
      translateTime: 'yyyy-mm-dd HH:MM:ss'
    }
  }
})

Context tree

When showContextTree is true (default), object context passed to logger.info / warn / error / debug is printed under the main line as tree branches, instead of being inlined into {context} on that line.

Each row is two spaces, ├─ or └─, the key (cyan when colors are on), two spaces, then the value.
For ERROR logs, an error row is appended when an error object is present (parsed message).
Set contextDepth (default 1) to flatten nested objects into dotted keys (e.g. user.id) up to that depth.

logixlysia({
  config: {
    showContextTree: true,
    contextDepth: 2
  }
})

Example (no ANSI colors), after a main line like … GET /orders 500 3ms Checkout failed:

  ├─ orderId  ord_123
  └─ error  Card declined

Structured Error Logs

Logixlysia natively supports structured errors (similar to the evlog pattern) when thrown exceptions contain specific troubleshooting fields:

why: Explains the root cause of the error.
fix: Suggests actionable remediation.
link: Provides a URL to documentation or troubleshooting help.
internal: Log-safe diagnostic metadata (e.g. error codes, non-sensitive context).

If a caught error contains any of these fields, they are automatically extracted and rendered under the error. namespace (error.why, error.fix, error.link, and error.internal) as individual tree branches.

[!WARNING] Because error.internal is emitted verbatim to logs, it should contain only log-safe diagnostic metadata. Do not place sensitive secrets, credentials, or PII (Personally Identifiable Information) in this field.

// Custom error implementation
class CheckoutError extends Error {
  why = 'Card declined by issuer due to insufficient funds.'
  fix = 'Please try a different credit card or payment method.'
  link = 'https://docs.example.com/payments/declined'
  internal = { gatewayCode: 'NSF', raw: '...' }
}

throw new CheckoutError('Payment failed')

Console output tree:

  ├─ orderId  ord_123
  ├─ error  Payment failed
  ├─ error.why  Card declined by issuer due to insufficient funds.
  ├─ error.fix  Please try a different credit card or payment method.
  ├─ error.link  https://docs.example.com/payments/declined
  └─ error.internal  {"gatewayCode":"NSF","raw":"..."}

Set showContextTree: false to disable the tree and put stringified context back on the main line via {context} when you include that token.

Error Log Formatting

The customLogFormat applies to both regular access logs and error logs. When an error occurs (like validation errors or exceptions), the same formatting rules apply, ensuring consistent log output across all log levels.

Best Practices

Keep formats concise for readability
Include essential information only
Use consistent formatting across environments
Consider log parsing requirements when designing formats
Error logs will include the error message in the {message} placeholder

Documentation

Features

Adapters

Integrations

Basic Usage

Available Placeholders

Examples

Minimal Format

Branded line with `{icon}` and `{service}`

Status text

Timestamp Format

Context tree

Structured Error Logs

Error Log Formatting

Best Practices

​Basic Usage

​Available Placeholders

​Examples

​Minimal Format

​Branded line with {icon} and {service}

​Status text

​Timestamp Format

​Context tree

​Structured Error Logs

​Error Log Formatting

​Best Practices

Basic Usage

Available Placeholders

Examples

Minimal Format

Branded line with `{icon}` and `{service}`

Status text

Timestamp Format

Context tree

Structured Error Logs

Error Log Formatting

Best Practices