LoggingCopy Anchor Link

The platform provides Rust logging for backtesting and live trading through the standard log crate facade.

The core logger operates in a separate thread and uses a multi-producer single-consumer (MPSC) channel to receive log messages. This moves log output I/O off the calling thread. Message arguments are still formatted on the calling thread before the event is queued.

Logging output is configurable and supports:

• stdout/stderr writer for console output
• file writer for persistent storage of logs

ArchitectureCopy Anchor Link

The logging subsystem captures events from multiple sources and routes them through an MPSC channel to a dedicated logging thread:

• Python and Nautilus components: Log directly through the Nautilus Logger.
• External log crate users: Filtered by stdout_level/fileout_level in LoggerConfig.
• External tracing crate users: When enabled, output goes directly to stdout (separate from Nautilus logging), filtered by the RUST_LOG environment variable.
• Logging thread: NautilusTrader sends all log events through an MPSC channel to a dedicated thread. Thus, log I/O operations do not block the main thread.

ConfigurationCopy Anchor Link

Logging can be configured by importing the LoggerConfig object. By default, log events with an INFO LogLevel and higher are written to stdout/stderr.

The following log levels are supported:

• OFF - Disable logging.
• TRACE - Most verbose level.
• DEBUG - Detailed diagnostic information.
• INFO - General operational messages.
• WARNING - Potential issues that do not prevent operation.
• ERROR - Errors that may affect functionality.

See the LoggerConfig API Reference for further details.

Logging can be configured in the following ways:

• Minimum LogLevel for stdout/stderr.
• Minimum LogLevel for log files.
• Maximum size before rotating a log file.
• Maximum number of backup log files to maintain when rotating.
• Automatic log file naming with date or timestamp components, or custom log file name.
• Directory for writing log files.
• Plain text or JSON log file formatting.
• Filtering of individual components by log level.
• ANSI colors in log lines.
• Bypass logging entirely.
• Print Rust config to stdout at initialization.
• Truncate an existing log file on startup (clear_log_file).

Standard output loggingCopy Anchor Link

The stdout/stderr writers write log messages to the console. Set the minimum level with stdout_level.

File loggingCopy Anchor Link

Log files are written to the current working directory by default. Settings control file naming and rotation.

Set the log directory and custom file basename with FileWriterConfig.directory and FileWriterConfig.file_name.

The logging thread flushes the file buffer to the operating system at approximately 100 ms intervals without syncing to disk. Thus, a tailed log file stays current. Blocking console output can delay a flush, and an abrupt process exit can still lose lines that are buffered or queued for the logging thread.

Log file formats:

• None (default) - Plain text format with .log extension.
• "json" - JSON format with .jsonl extension, useful for log aggregation tools.

For detailed information about log file naming conventions and rotation behavior, see the Log file rotation and Log file naming convention sections below.

Log file rotationCopy Anchor Link

Rotation behavior depends on both the presence of a size limit and whether a custom file name is provided:

• Size-based rotation:
  • Set FileWriterConfig.file_rotate to a (max_file_size, max_backup_count) tuple, such as (100_000_000, 5) for 100 MB and five backup files.
  • When writing a log entry would make the current file exceed this size, the file is closed and a new one is created.
  • Rotation file names have millisecond resolution. If a rotation resolves to the active path, logging continues to that file, which may briefly exceed the configured maximum size.
• Date-based rotation (default naming only):
  • Applies when file_rotate and file_name are both unset.
  • On the first write after each UTC date change (midnight), the logger closes the current log file and starts a new one. This creates one file per UTC day.
• No rotation:
  • When file_name is set without file_rotate, logs continue to append to the same file.
  • Note: Size-based rotation takes precedence: if both a custom name and size limit are provided, rotation still occurs.
• Backup file management:
  • The second value in file_rotate limits the total number of rotated files kept.
  • When this limit is exceeded, the oldest backup files are automatically removed.
  • The limit applies to files rotated by the current process. Rotated files from earlier runs are not removed. Use an external tool such as logrotate for retention across restarts.
• Rotation failures:
  • If a rotation fails (for example, the new file cannot be opened), logging continues to the current file and rotation is retried at the next size or date boundary.

Log file naming conventionCopy Anchor Link

The default naming convention ensures log files are uniquely identifiable and timestamped. The format depends on whether file rotation is enabled:

With file rotation enabled:

• Format: {trader_id}_{%Y-%m-%d_%H%M%S-%3f}_{instance_id}.{log|jsonl}
• Example: TESTER-001_2025-04-09_210721-521_d7dc12c8-7008-4042-8ac4-017c3db0fc38.log
• Components:
  • {trader_id}: The trader identifier (for example, TESTER-001).
  • {%Y-%m-%d_%H%M%S-%3f}: UTC datetime with millisecond resolution.
  • {instance_id}: A unique instance identifier.
  • {log|jsonl}: File suffix based on format setting.

Without size-based rotation (default naming):

• Format: {trader_id}_{%Y-%m-%d}_{instance_id}.{log|jsonl}
• Example: TESTER-001_2025-04-09_d7dc12c8-7008-4042-8ac4-017c3db0fc38.log
• Components:
  • {trader_id}: The trader identifier.
  • {%Y-%m-%d}: Date only (YYYY-MM-DD).
  • {instance_id}: A unique instance identifier.
  • {log|jsonl}: File suffix based on format setting.
• Note: With default naming and no size limit, logs rotate daily at UTC midnight.

Custom naming:

If file_name is set (for example, my_custom_log):

• With rotation disabled: The file will be named exactly as provided (for example, my_custom_log.log).
• With rotation enabled: The file will include the custom name and timestamp (for example, my_custom_log_2025-04-09_210721-521.log).
• An extension in file_name is replaced by the format suffix, so my_custom_log.log produces the same names as my_custom_log.

Component log filteringCopy Anchor Link

The component_levels parameter sets log levels for individual components. The input value should be a dictionary of component ID strings to log level strings: dict[str, str].

Below is an example of a trading node logging configuration that includes some of the options mentioned above:

from nautilus_trader.common import LogLevel
from nautilus_trader.config import FileWriterConfig
from nautilus_trader.config import LoggerConfig
from nautilus_trader.config import LiveNodeConfig
from nautilus_trader.model import TraderId

config_node = LiveNodeConfig(
    trader_id=TraderId.from_str("TESTER-001"),
    logging=LoggerConfig(
        stdout_level=LogLevel.INFO,
        fileout_level=LogLevel.DEBUG,
        component_levels={"Portfolio": "INFO"},
        file_config=FileWriterConfig(file_format="json"),
    ),
)

For backtesting, the BacktestEngineConfig class can be used instead of LiveNodeConfig, as the same options are available.

Environment variable configurationCopy Anchor Link

The NAUTILUS_LOG environment variable provides an alternative way to configure logging using a semicolon-separated spec string. This is useful for Rust-only binaries or when you want to override logging settings without modifying code.

export NAUTILUS_LOG="stdout=Info;fileout=Debug;RiskEngine=Error;is_colored"

Supported keys:

Flags are enabled by their presence in the spec string (no value needed). Log levels are case-insensitive: Off, Trace, Debug, Info, Warn, Error.

Components-only loggingCopy Anchor Link

When focusing on a subset of noisy systems, enable log_components_only to log messages only from components listed in component_levels. All other components are suppressed regardless of the global stdout or file level.

Example (Python configuration):

logging = LoggerConfig(
    stdout_level=LogLevel.INFO,
    component_levels={
        "RiskEngine": "DEBUG",
        "Portfolio": "INFO",
    },
    log_components_only=True,
)

If you use the Rust spec string through the environment, include log_components_only alongside component filters, for example:

export NAUTILUS_LOG="stdout=Info;log_components_only;RiskEngine=Debug;Portfolio=Info"

Module path filtering (Rust only)Copy Anchor Link

When using the NAUTILUS_LOG environment variable, you can filter by Rust module paths in addition to component names. Keys containing :: are treated as module path filters with prefix matching, while keys without :: are component filters with exact matching.

# Filter all OKX adapter modules to Warn, but allow Debug for the websocket modules
export NAUTILUS_LOG="stdout=Info;nautilus_okx::=Warn;nautilus_okx::websocket=Debug"

The longest matching prefix takes precedence. In the example above, nautilus_okx::websocket::handler would use the Debug level (longer prefix), while nautilus_okx::data would use Warn.

Log colorsCopy Anchor Link

ANSI color codes improve log readability in terminals. In environments that do not support ANSI color rendering (such as some cloud environments or text editors), these color codes may not be appropriate as they can appear as raw text.

Set LoggerConfig.is_colored=False for these environments.

Python callback exceptionsCopy Anchor Link

Python callback errors include a traceback and chained exceptions. If traceback formatting fails, reporting falls back to the exception type and message.

Python strategy and execution algorithm order and position callbacks log failures at ERROR, with the component identity and callback name. Strategy market-exit callbacks use the same reporting. Python data and timer callback errors also reach ERROR. Those records use the emitting Rust module as their component.

For these event callbacks, an exception interrupts that Python invocation. By default, the runtime continues dispatching events. It does not roll back work the callback completed before raising.

To request a normal shutdown after an error, enable shutdown_on_error in the backtest engine or live node configuration. The request takes effect when the runtime next checks for shutdown, rather than interrupting the current event dispatch.

Using a logger directlyCopy Anchor Link

You can initialize and use Logger objects directly anywhere, much like Python's built-in logging API.

Without an object that initializes a NautilusKernel and logging (such as BacktestEngine or LiveNode), activate logging as follows:

from nautilus_trader.common import init_logging
from nautilus_trader.common import Logger
from nautilus_trader.common import LogLevel
from nautilus_trader.core import UUID4
from nautilus_trader.model import TraderId

log_guard = init_logging(
    trader_id=TraderId.from_str("TESTER-001"),
    instance_id=UUID4(),
    level_stdout=LogLevel.INFO,
)
logger = Logger("MyLogger")

See the init_logging API Reference for further details.

Keep the returned LogGuard alive for as long as direct logging is needed. The logging subsystem supports up to 255 concurrent guards.

LogGuard: managing log lifecycleCopy Anchor Link

init_logging returns a LogGuard that tracks one user of the process-global logging subsystem. BacktestEngine and LiveNode own their guards internally, so application code does not need to acquire a guard from an engine or node.

Reference counting implementationCopy Anchor Link

The logging system uses reference counting to track active LogGuard instances:

• Counter increments: When a new LogGuard is created, an atomic counter is incremented.
• Counter decrements: When a LogGuard is dropped, the counter is decremented.
• Last guard: When the counter reaches zero, pending file logs are flushed and synced. The process-global logging thread stays available for later guards.
• Maximum guards: The system supports up to 255 concurrent LogGuard instances. Attempting to create more raises a ValueError from init_logging, or a RuntimeError from engine or node creation.

Abrupt termination can still lose buffered logs. Dispose engines and nodes normally, and keep the guard returned by direct init_logging calls until the application no longer needs logging.

Tracing subscriber for external Rust librariesCopy Anchor Link

External Rust crates that use the tracing crate can have their log output displayed by enabling the tracing subscriber. This is useful for debugging external dependencies or when integrating custom Rust components (such as feature extractors or adapters) compiled as separate PyO3 extensions.

Enabling the subscriberCopy Anchor Link

Initialize the tracing subscriber directly:

from nautilus_trader.common import init_tracing

init_tracing()

Filtering with RUST_LOGCopy Anchor Link

The RUST_LOG environment variable controls which tracing events are displayed:

# Show debug logs from your crate, warn and above from hyper
RUST_LOG=my_feature_extractor=debug,hyper=warn python my_script.py

If RUST_LOG is not set, the default filter level is warn.

How it worksCopy Anchor Link

The tracing subscriber uses a tracing-subscriber fmt layer with a custom formatter to output directly to stdout. This is separate from the Nautilus logging infrastructure - tracing output uses a Nautilus-aligned format with nanosecond timestamps.

Example tracing output:

2026-01-24T05:51:42.809619000Z [DEBUG] hyper_util::client::legacy::connect::http: connecting to 104.18.5.240:443
2026-01-24T05:51:42.810543000Z [DEBUG] hyper_util::client::legacy::pool: pooling idle connection for ("https", api.example.com)

Differences from Nautilus logging:

• Tracing output goes directly to stdout, not through the Nautilus logging thread.
• Tracing events are not written to Nautilus log files.
• Filtering is controlled exclusively by RUST_LOG, independent of LoggerConfig.

For external libraries that use the log crate (such as rustls), their events go through the Nautilus logger and are filtered by stdout_level/fileout_level in LoggerConfig.

Platform-specific considerationsCopy Anchor Link

Windows shutdown behaviorCopy Anchor Link

On Windows, non-deterministic garbage collection during interpreter shutdown can occasionally delay the final LogGuard drop until after interpreter teardown has begun. Dropping the last guard is what flushes and syncs pending file logs, so a delayed drop can result in truncated logs.

Related guidesCopy Anchor Link

• Architecture - System architecture including logging infrastructure.