Configuration Options

Zario offers extensive configuration options to tailor its logging behavior to your application's needs. This page details all available options for the Logger class and its built-in transports.

Logger Configuration (LoggerOptions)

The Logger class constructor accepts an options object of type LoggerOptions ([API Reference - LoggerOptions]).

Here's a breakdown of each option:

Core Options

• level?: LogLevel

  • Description: The minimum log level required for a message to be processed. Messages with a lower priority than this level will be ignored.
  • Default:
    • 'debug' in development environments (NODE_ENV is development, test, staging, or unset).
    • 'warn' in production environments (NODE_ENV is production or prod).
  • Possible Values: 'debug', 'info', 'warn', 'error', 'silent', 'boring', or any custom log level you define.
  • Example:

• colorize?: boolean

  • Description: Enables or disables colored output for text-based logs. Colors are applied based on the log level.
  • Default:
    • true in development environments.
    • false in production environments.
  • Possible Values: true | false
  • Example:

• json?: boolean

  • Description: Determines the output format of log messages.
  • Default:
    • false (text format) in development environments.
    • true (JSON format) in production environments.
  • Possible Values: true (structured JSON) | false (plain text)
  • Example:

• transports?: TransportConfig[]

  • Description: An array of transport instances that Zario will use to output log messages. Each log message is sent to all configured transports.
  • Default:
    • [new ConsoleTransport()] in development environments.
    • [new ConsoleTransport(), new FileTransport({ path: "./logs/app.log" })] in production environments.
  • Possible Values: An array of Transport instances (e.g., ConsoleTransport, FileTransport, HttpTransport, or custom transports).
  • Example:

• timestamp?: boolean

  • Description: Controls whether a timestamp is prepended to log messages.
  • Default: true
  • Possible Values: true | false
  • Example:

• timestampFormat?: string

  • Description: Defines the format of the timestamp string. This option is only applicable when timestamp is true.
  • Default: "YYYY-MM-DD HH:mm:ss"
  • Possible Values:
    • "ISO": ISO 8601 format (e.g., 2023-10-27T10:30:00.000Z)
    • "UTC": UTC string format (e.g., Fri, 27 Oct 2023 10:30:00 GMT)
    • "LOCAL": Localized date/time string (e.g., 10/27/2023, 1:30:00 PM)
    • Custom format string using tokens: YYYY (year), MM (month), DD (day), HH (hour), mm (minute), ss (second), SSS (milliseconds).
  • Example:

• prefix?: string

  • Description: A string prefix to be added to the beginning of every log message from this logger instance. Useful for identifying logs from specific modules or components.
  • Default: "" (empty string)
  • Example:

• context?: Record<string, any>

  • Description: An object containing key-value pairs that will be merged into the metadata of every log message generated by this logger. This is useful for adding consistent contextual information (e.g., requestId, userId).
  • Default: {} (empty object)
  • Example:

• asyncMode?: boolean

  • Description: Enables or disables asynchronous logging. In async mode, log writes are non-blocking, improving application performance at the cost of potential (though rare) log loss in case of a crash.
  • Default:
    • false in development environments.
    • true in production environments.
  • Possible Values: true | false
  • Example:

Advanced Options

• parent?: Logger

  • Description: Specifies a parent Logger instance. If provided, the new logger will inherit settings (level, transports, prefix, context, etc.) from the parent. This is primarily used internally by createChild().
  • Default: undefined
  • Example: (Typically used via logger.createChild())

• customLevels?: { [level: string]: number }

  • Description: An object mapping custom log level names to their numeric priorities. Higher numbers indicate higher priority. This allows you to define application-specific log levels beyond the standard debug, info, warn, error, silent, boring.
  • Default: {} (empty object)
  • Example:

• customColors?: { [level: string]: string }

  • Description: An object mapping log level names (built-in or custom) to ANSI color strings. These colors will be used when colorize is true.
  • Default: {} (uses Zario's default colors for standard levels)
  • Possible Values: Standard ANSI color names like 'black', 'red', 'green', 'yellow', 'blue', 'magenta', 'cyan', 'white', or their bright counterparts (e.g., 'brightRed').
  • Example:

• filters?: Filter[]

  • Description: An array of Filter instances. These filters are applied to each log message before it is sent to transports or aggregators. If any filter in the array returns false (meaning it should not emit), the log message is discarded.
  • Default: [] (no filters)
  • Possible Values: Instances of PredicateFilter, LevelFilter, PrefixFilter, MetadataFilter, FieldFilter, CompositeFilter, OrFilter, NotFilter ([API Reference - Filters]).
  • Example:

• aggregators?: LogAggregator[]

  • Description: An array of LogAggregator instances. Aggregators collect log messages (e.g., for batching) before a final processing step.
  • Default: [] (no aggregators)
  • Possible Values: Instances of BatchAggregator, TimeBasedAggregator, CompositeAggregator ([API Reference - Aggregation]).
  • Example:

• enrichers?: LogEnrichmentPipeline

  • Description: An instance of LogEnrichmentPipeline that contains a series of LogEnricher functions. Enrichers modify or add data to the log record's metadata before it's formatted and sent to transports/aggregators.
  • Default: A new, empty LogEnrichmentPipeline instance.
  • Possible Values: An instance of LogEnrichmentPipeline populated with MetadataEnricher static methods or custom LogEnricher functions ([API Reference - Structured Logging Extensions]).
  • Example:

Transport-Specific Configurations

Each built-in transport also has its own configuration options.

ConsoleTransportOptions

Options for the ConsoleTransport class.

• colorize?: boolean
  • Description: Overrides the logger's global colorize setting specifically for this console transport. If true, this transport will output colored logs even if the logger's colorize is false (and vice-versa).
  • Default: true
  • Possible Values: true | false
  • Example:

FileTransportOptions

Options for the FileTransport class.

• path: string

  • Description: (Required) The file path where logs will be written. The directory will be created if it doesn't exist.
  • Example:

• maxSize?: number

  • Description: The maximum size (in bytes) a log file can reach before it is rotated.
  • Default: 10 * 1024 * 1024 (10 MB)
  • Example:

• maxFiles?: number

  • Description: The maximum number of rotated log files to keep. Older files beyond this limit will be deleted.
  • Default: 5
  • Example:

• compression?: CompressionType

  • Description: Specifies the compression type for rotated log files.
  • Default: 'none'
  • Possible Values: 'gzip', 'deflate', 'none'
  • Example:

• batchInterval?: number

  • Description: The interval (in milliseconds) at which log messages are batched and written to the file. If 0 (default), logs are written immediately. Setting a value greater than 0 can improve performance by reducing file I/O operations.
  • Default: 0 (no batching)
  • Example:

• compressOldFiles?: boolean

  • Description: Whether to compress old log files (i.e., files that are rotated) when compression is enabled.
  • Default: true
  • Possible Values: true | false
  • Example:

HttpTransportOptions

Options for the HttpTransport class.

• url: string

  • Description: (Required) The URL of the HTTP endpoint where log messages will be sent.
  • Example:

• method?: string

  • Description: The HTTP method to use for sending log requests.
  • Default: 'POST'
  • Example:

• headers?: Record<string, string>

  • Description: An object containing custom HTTP headers to include with each request.
  • Default: { 'Content-Type': 'application/json' }
  • Example:

• timeout?: number

  • Description: The maximum time (in milliseconds) to wait for an HTTP response before aborting the request.
  • Default: 5000 (5 seconds)
  • Example:

• retries?: number

  • Description: The number of times to retry a failed HTTP request before giving up. Retries use an exponential backoff strategy.
  • Default: 3
  • Example:

Custom Log Levels and Colors

Zario allows you to define your own log levels and associate them with custom colors, providing greater semantic control over your logging.

Defining Custom Levels

Use the customLevels option in LoggerOptions. Each entry maps a custom level name (string) to a numeric priority. Standard levels have default priorities:

• silent: 0
• boring: 1
• debug: 2
• info: 3
• warn: 4
• error: 5

Defining Custom Colors

Use the customColors option in LoggerOptions. Each entry maps a log level name (built-in or custom) to an ANSI color string.

Environment-Based Auto-Configuration

Zario intelligently auto-configures default LoggerOptions based on the NODE_ENV environment variable, aiming to provide sensible defaults for different deployment environments.

Development Environment (NODE_ENV = development, test, staging, or unset)

If NODE_ENV is set to development, test, staging, or is not set at all, Zario applies the following defaults:

• level: 'debug' (Logs all messages down to debug severity)
• colorize: true (Console output will be colored)
• json: false (Logs will be in plain text format)
• transports: [new ConsoleTransport()] (Logs only to the console)
• timestamp: true (Timestamps are included in logs)
• asyncMode: false (Logs are written synchronously)

This setup is ideal for local development, providing verbose, human-readable output directly in your terminal.

Production Environment (NODE_ENV = production or prod)

If NODE_ENV is set to production or prod (case-insensitive), Zario optimizes for production deployments:

• level: 'warn' (Logs only warnings and errors to reduce noise)
• colorize: false (No colors, as production logs often go to files or structured logging systems)
• json: true (Logs are in structured JSON format, suitable for log aggregation tools)
• transports: [new ConsoleTransport(), new FileTransport({ path: "./logs/app.log" })] (Logs to both console and a file for persistence)
• timestamp: true (Timestamps are included)
• asyncMode: true (Logs are written asynchronously to minimize impact on application performance)

This configuration ensures efficient, machine-readable logging that is less disruptive to your live application.

Overriding Auto-Configuration

You can always explicitly set any LoggerOptions property in the Logger constructor to override these environment-based defaults. Your explicit settings will take precedence.

When creating [child loggers], they inherit settings from their parent, and any options provided to createChild() will override those inherited settings. This allows for fine-grained control over logging behavior across different parts of your application while maintaining a consistent base configuration.