Custom Formatting

Create custom log message formats

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

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