# Configuration Reference

Zario is highly configurable. You can pass a `LoggerOptions` object to the `Logger` constructor to customize its behavior.

## Logger Options

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `level` | `LogLevel` | `'info'` | The minimum log level to output. |
| `colorize` | `boolean` | `true` | Whether to colorize the console output. |
| `json` | `boolean` | `false` | Whether to format logs as JSON. |
| `transports` | `Transport[]` | `[Console]` | An array of transports to use for logging. |
| `timestamp` | `boolean` | `false` | Whether to include a timestamp in the log output. |
| `timestampFormat`| `string` | `'YYYY-MM-DD HH:mm:ss'` | The format for timestamps. |
| `prefix` | `string` | `''` | A prefix to add to all log messages. |
| `context` | `object` | `{}` | Default metadata to attach to every log. |
| `asyncMode` | `boolean` | `false` | Enable non-blocking asynchronous logging. |
| `customLevels` | `object` | `undefined` | Map of custom log level names to priorities. |
| `customColors` | `object` | `undefined` | Map of custom log level names to colors. |
| `filters` | `Filter[]` | `[]` | Array of filters to apply before logging. |
| `aggregators` | `Aggregator[]`| `[]` | Array of log aggregators. |
| `enrichers` | `Enricher[]` | `[]` | Pipeline for structured logging metadata. |
| `retryOptions` | `LoggerRetryOptions` | `undefined` | Auto-wraps transports with retry behavior. |
| `queueProvider` | `QueueProvider` | `MemoryQueueProvider` | Custom queue provider implementation for async mode. |
| `queueOptions` | `MemoryQueueOptions` | `undefined` | Options for the default memory queue provider. |

### Retry Options (`retryOptions`)

`retryOptions` applies retry behavior to each configured transport.

When importing from the root `zario` package (e.g., `import { Logger } from 'zario'`), the retry transport wrapper is configured automatically. 

However, if you import `Logger` from the lean `zario/logger` entrypoint, you must register the retry factory once at startup:

#### Startup Configuration Setup
```typescript
import { Logger } from 'zario/logger';
import { RetryTransport } from 'zario/transports/RetryTransport';
import { ConsoleTransport } from 'zario/transports/ConsoleTransport';

// 1. Configure the retry factory once at startup
Logger.retryTransportFactory = (options) => new RetryTransport(options);

// 2. Instantiate with retryOptions
const logger = new Logger({
  transports: [new ConsoleTransport()],
  retryOptions: {
    maxAttempts: 5,
    baseDelay: 1000
  }
});
```

#### Transport Chain Configuration Setup
```typescript
import { Logger } from 'zario/logger';
import { RetryTransport } from 'zario/transports/RetryTransport';
import { HttpTransport } from 'zario/transports/HttpTransport';

// 1. Configure the retry factory
Logger.retryTransportFactory = (options) => new RetryTransport(options);

// 2. Automatically wrap HttpTransport with retry behavior
const logger = new Logger({
  transports: [
    new HttpTransport({
      url: 'https://logs.example.com/ingest'
    })
  ],
  retryOptions: {
    maxAttempts: 3,
    baseDelay: 500,
    backoffMultiplier: 2
  }
});
```

## Log Levels

Zario comes with several built-in log levels, ordered by priority:

1. `silent` (0) - Suppresses all logging.
2. `boring` (1) - Low priority, uncolored info.
3. `debug` (2) - Detailed debugging information.
4. `info` (3) - General informational messages.
5. `warn` (4) - Warning messages for non-critical issues.
6. `error` (5) - Error messages for failed operations.
7. `fatal` (6) - Critical failures that may lead to shutdown.

Logs with a priority **equal to or higher** than the configured `level` will be processed.

## Custom Levels & Colors

You can define your own log levels with specific priorities and colors.

```typescript
const logger = new Logger({
  customLevels: {
    'success': 4,  // Same priority as warn
    'trace': 1     // Lower priority than debug
  },
  customColors: {
    'success': 'green',
    'trace': 'gray'
  }
});

logger.logWithLevel('success', 'Operation completed!');
```

### Supported Colors
Zario supports standard ANSI colors: `black`, `red`, `green`, `yellow`, `blue`, `magenta`, `cyan`, `white`, `gray`, and their "bright" variants (e.g., `brightRed`).

## Timestamp Customization

The `timestampFormat` supports the following placeholders:

- `YYYY`: 4-digit year
- `MM`: 2-digit month (01-12)
- `DD`: 2-digit day (01-31)
- `HH`: 2-digit hour (00-23)
- `mm`: 2-digit minute (00-59)
- `ss`: 2-digit second (00-59)
- `SSS`: 3-digit millisecond (000-999)

Example: `YYYY/MM/DD HH:mm:ss.SSS` -> `2025/01/23 10:22:20.500`

## Memory & Performance

Zario provides several options to ensure memory safety and high performance in demanding environments.

### Unified Async Log Queue (`queueProvider` & `queueOptions`)
When `asyncMode` is enabled, Zario buffers log entries inside a central `LogQueue` before writing to transports. This avoids event loop congestion by batching writes.

You can configure the queue settings using `queueOptions` (which applies to the default `MemoryQueueProvider`):

```typescript
const logger = new Logger({
  asyncMode: true,
  queueOptions: {
    maxQueueSize: 5000,
    flushInterval: 100, // Flush buffered logs every 100ms (0 = next-tick flush)
    batchSize: 50,      // Immediate flush when 50 items are enqueued
    overflowStrategy: 'drop-oldest' // 'drop-oldest' | 'drop-newest' | 'sync'
  }
});
```

#### Pluggable Queue Providers
For enterprise requirements (e.g. persistent file-backed queues or Redis queues), you can implement the `QueueProvider` interface and pass it to the logger via `queueProvider`:

```typescript
import { QueueProvider, LogData, Formatter, Transport } from 'zario';

class RedisQueueProvider implements QueueProvider {
  enqueue(log: LogData, formatter: Formatter, transports: Transport[]): void {
    // Custom enqueue logic (e.g. push to Redis)
  }
  async flush(): Promise<void> {
    // Flush buffered logs
  }
  async destroy(): Promise<void> {
    // Cleanup resources
  }
}

const logger = new Logger({
  asyncMode: true,
  queueProvider: new RedisQueueProvider()
});
```

### Queue Limits in Aggregators (`maxQueueSize`)
Log aggregators (`BatchAggregator`, `TimeBasedAggregator`) support a `maxQueueSize` parameter. This limits the number of log entries held in memory before they are processed or dropped, preventing memory leaks in case of slow I/O or downstream service failures.

### Asynchronous HTTP (`forceAsync`)
The `HttpTransport` can be forced into asynchronous mode using the `forceAsync` option. This ensures that network requests never block the main event loop, providing predictable performance even when calling synchronous logging methods.

---

[← Getting Started](./getting-started.md) | [API Reference →](./api-reference.md)