# How to Configure Logging Levels and Output Formats in Nautilus Trader

> Learn to configure logging levels and output formats in Nautilus Trader. Use LoggingConfig to control console and file settings and initialize the Rust-backed logger efficiently.

- Repository: [Nautech Systems/nautilus_trader](https://github.com/nautechsystems/nautilus_trader)
- Tags: how-to-guide
- Published: 2026-02-16

---

**Use the `LoggingConfig` data class to set console and file levels, formats, and rotation, then pass it to the `NautilusKernel` which invokes `init_logging` in `nautilus_trader/common/component.pyx` to initialize the Rust-backed logger.**

Nautilus Trader uses a high-performance, Rust-backed logging subsystem that you can tailor through Python configuration classes. To configure logging levels and output formats, you manipulate the `LoggingConfig` data class defined in [`nautilus_trader/common/config.py`](https://github.com/nautechsystems/nautilus_trader/blob/main/nautilus_trader/common/config.py) and pass it to the kernel during system initialization.

## Understanding the Logging Architecture

The logging system is initialized once per process via the `init_logging` function defined in `nautilus_trader/common/component.pyx` (lines 1215–1248). This function creates a `LogGuard` that manages the underlying Rust logger and automatically flushes logs when destroyed.

The `LoggingConfig` class in [`nautilus_trader/common/config.py`](https://github.com/nautechsystems/nautilus_trader/blob/main/nautilus_trader/common/config.py) (lines 555–603) defines all available configuration options. During kernel construction in [`nautilus_trader/system/kernel.py`](https://github.com/nautechsystems/nautilus_trader/blob/main/nautilus_trader/system/kernel.py), the configuration is applied unless logging has already been initialized or `bypass_logging` is set to `True`.

## Configuring Logging Levels

### Console Output Levels

Set the minimum severity for stdout using the `log_level` parameter. Valid levels include `DEBUG`, `INFO`, `WARNING`, `ERROR`, and `CRITICAL`.

```python
from nautilus_trader.config import LoggingConfig

log_cfg = LoggingConfig(
    log_level="DEBUG",  # Show DEBUG and above in console

)

```

### File Output Levels

Control file output independently with `log_level_file`. Set it to `OFF` to disable file logging entirely.

```python
log_cfg = LoggingConfig(
    log_level="INFO",
    log_level_file="DEBUG",  # More verbose file logging

    log_directory="logs",
    log_file_name="session.log",
)

```

### Per-Component Log Level Filtering

Fine-tune verbosity for specific components using `log_component_levels`. This maps component names to level strings, allowing targeted debugging of noisy subsystems.

```python
log_cfg = LoggingConfig(
    log_level="WARNING",
    log_component_levels={
        "actor/strategy-001": "DEBUG",
        "actor/executor": "INFO",
    },
    log_components_only=False,  # False allows other messages above log_level

)

```

Set `log_components_only=True` to receive logs exclusively from the specified components.

## Configuring Output Formats and Destinations

### Plain Text vs JSON Format

Set `log_file_format` to `JSON` for structured logging suitable for log aggregation systems. Omit or use plain text for human-readable output. The file extension (`.log` vs `.json`) also determines the format if not explicitly set.

```python
log_cfg = LoggingConfig(
    log_level_file="INFO",
    log_file_format="JSON",
    log_file_name="events.json",
)

```

### Log File Rotation

Enable size-based rotation with `log_file_max_size` (in bytes) and `log_file_max_backup_count` to prevent unbounded log growth.

```python
log_cfg = LoggingConfig(
    log_level_file="INFO",
    log_directory="logs",
    log_file_name="trading.log",
    log_file_max_size=10 * 1024 * 1024,  # 10 MiB

    log_file_max_backup_count=7,
)

```

### Log Directory and File Naming

Specify `log_directory` for the output path and `log_file_name` for the base name. The system creates the directory if needed and appends timestamps or rotation indices as configured.

```python
log_cfg = LoggingConfig(
    log_directory="/var/log/nautilus",
    log_file_name="live_session",
    log_level_file="DEBUG",
)

```

## Advanced Logging Options

### Enabling Rust Tracing for External Crates

Set `use_tracing=True` to enable the Rust `tracing` subscriber, which captures logs from external Rust crates. Control verbosity via the `RUST_LOG` environment variable.

```python
log_cfg = LoggingConfig(
    log_level="INFO",
    use_tracing=True,
)

# Set environment variable: RUST_LOG=hyper_util=debug

```

### Bypassing Logging in Tests

Set `bypass_logging=True` to completely disable the logging subsystem. This prevents the `LogGuard` from being created and keeps test output clean.

```python
from nautilus_trader.config import LoggingConfig

log_cfg = LoggingConfig(bypass_logging=True)

```

### ANSI Colors in Console Output

Control console colors with `log_colors`. This is enabled by default but can be disabled for environments that do not support ANSI codes.

```python
log_cfg = LoggingConfig(
    log_level="INFO",
    log_colors=True,
)

```

## Summary

- Configure logging levels and output formats using the `LoggingConfig` data class defined in [`nautilus_trader/common/config.py`](https://github.com/nautechsystems/nautilus_trader/blob/main/nautilus_trader/common/config.py).
- Pass the configuration to `NautilusKernel` or `TradingNode`, which invokes `init_logging` in `nautilus_trader/common/component.pyx` to initialize the Rust-backed logger.
- Set `log_level` for console output and `log_level_file` for file output independently.
- Use `log_file_format="JSON"` for structured logging or plain text for human-readable output.
- Enable rotation with `log_file_max_size` and `log_file_max_backup_count`.
- Filter specific components with `log_component_levels` or disable logging entirely with `bypass_logging`.

## Frequently Asked Questions

### How do I set different logging levels for console and file output?

Use the `log_level` parameter for console output and `log_level_file` for file output. For example, set `log_level="WARNING"` to reduce console noise while setting `log_level_file="DEBUG"` to capture detailed logs to disk for later analysis.

### What is the difference between plain text and JSON log formats in Nautilus Trader?

Plain text format produces human-readable logs with timestamps and severity levels, suitable for console viewing and manual debugging. JSON format produces structured machine-readable logs when you set `log_file_format="JSON"`, which is ideal for ingestion into log aggregation systems like ELK or Splunk.

### How can I filter logs to show only specific components?

Use the `log_component_levels` dictionary to map component names to specific log levels. Set `log_components_only=True` to restrict output exclusively to those components, or leave it as `False` to see filtered components plus any messages above the global `log_level`.

### How do I completely disable logging for unit tests?

Set `bypass_logging=True` in your `LoggingConfig`. This prevents the initialization of the Rust-backed logger and the creation of the `LogGuard`, ensuring your test runs remain clean and free of log output.