How to Configure Logging Levels and Output Formats in Nautilus Trader

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 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 (lines 555–603) defines all available configuration options. During kernel construction in 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.

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.

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.

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.

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.

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.

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.

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.

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.

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.
• 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}