Log Formats

Zario provides flexible log formatting options to suit various needs, from human-readable console output to machine-parseable structured logs for aggregation systems. You can configure the default format during Logger initialization or switch it dynamically at runtime.

Zario primarily supports two output formats: Text and JSON.

Text Format

The Text format is designed for human readability, typically used for console output or basic log files. It presents log data as a single string, with various components appearing in a predictable order.

Default Structure

When configured for text output, Zario logs generally follow this structure:

[TIMESTAMP] [PREFIX] [LEVEL] MESSAGE {METADATA}

Each component is optional and depends on your logger's configuration:

• [TIMESTAMP]: The date and time when the log occurred. Its presence is controlled by the timestamp option, and its appearance by timestampFormat.
• [PREFIX]: A custom string prepended to the log, useful for identifying the source module or component. Controlled by the prefix option.
• [LEVEL]: The log's severity level (e.g., INFO, WARN, ERROR). This is always present and can be colorized if colorize is true.
• MESSAGE: The primary log message.
• {METADATA}: Any additional key-value data associated with the log, represented as a JSON string. This includes explicit metadata passed to the log method, and any context defined on the logger or added by enrichers. If there's no metadata, this part is omitted.

Timestamp Formatting

The timestampFormat option (Configuration Options) allows you to customize how the timestamp appears in Text format logs.

• "ISO": 2023-10-27T10:00:00.000Z
• "UTC": Fri, 27 Oct 2023 10:00:00 GMT
• "LOCAL": 10/27/2023, 1:00:00 PM (or similar, depending on locale)
• Custom strings (e.g., "YYYY-MM-DD HH:mm:ss"): 2023-10-27 10:00:00

Example Output (Text Format)

Consider the following LogData object internally processed by Zario:

With timestamp: true, timestampFormat: "YYYY-MM-DD HH:mm:ss", colorize: false and json: false, the output would be:

[2023-10-27 10:00:00] [AuthService] [INFO] User logged in successfully {"userId":123,"ipAddress":"192.168.1.1"}

JSON Format

The JSON format produces structured log entries, making them ideal for integration with centralized logging systems (e.g., ELK stack, Splunk, DataDog). Each log message is an independent JSON object, allowing for easy parsing, querying, and analysis.

Structured Output

In JSON format, Zario integrates all log components into a single JSON object. Metadata fields are merged directly into the root of the JSON object, alongside core log fields.

The core fields are:

• level: The log's severity level (e.g., "info", "warn", "error").
• message: The main log message.
• timestamp: The timestamp of the log, always formatted as an ISO 8601 string (e.g., "2023-10-27T10:00:00.000Z"), if timestamp is true. The timestampFormat option does not apply here.
• prefix: The logger's prefix, if defined.
• metadata: Any additional contextual information provided with the log. Fields from LogData.metadata and LoggerConfig.context are spread directly into the root JSON object. If a metadata key conflicts with a core field (like level or message), the core field takes precedence.

Example Output (JSON Format)

Using the same exampleLogData object as above:

With timestamp: true and json: true, the output would be:

Notice how userId and ipAddress from metadata are now top-level fields in the JSON object.

Dynamically Switching Formats

You can change the output format of a logger instance at any time using the setFormat() method:

Using setFormat() affects how messages are formatted by that specific logger instance and its children (unless a child explicitly overrides the json option). This dynamic control allows you to adapt logging behavior based on runtime conditions or user preferences without re-initializing the logger.