Logging 日志记录

The platform provides logging for both backtesting and live trading using a high-performance logging system implemented in Rust with a standardized facade from the log crate.

该平台使用 Rust 实现的高性能日志记录系统为回测和实时交易提供日志记录，并使用来自 log crate 的标准化外观。

The core logger operates in a separate thread and uses a multi-producer single consumer (MPSC) channel to receive log messages. This design ensures that the main thread is not blocked by log string formatting or file I/O operations.

核心记录器在单独的线程中运行，并使用多生产者单消费者 (MPSC) 通道接收日志消息。这种设计确保主线程不会被日志字符串格式化或文件 I/O 操作阻塞。

There are two configurable writers for logging:

日志记录有两个可配置的写入器：

• stdout/stderr writer 标准输出/标准错误写入器
• log file writer 日志文件写入器

Infrastructure such as vector can be configured to collect these log events.

可以配置诸如 vector 之类的基础架构来收集这些日志事件。

Configuration 配置

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

可以通过导入 LoggingConfig 对象来配置日志记录。默认情况下，具有 'INFO' LogLevel 及更高级别的日志事件将写入标准输出/标准错误。

Log level (LogLevel) values include (and generally match Rusts tracing level filters):

日志级别 (LogLevel) 值包括（通常与 Rust 的跟踪级别过滤器匹配）：

• OFF 关闭
• DEBUG 调试
• INFO 信息
• WARNING or WARN 警告
• ERROR 错误

info 信息

See the LoggingConfig API Reference for further details.

有关更多详细信息，请参阅 LoggingConfig API 参考。

Logging can be configured in the following ways:

可以通过以下方式配置日志记录：

• Minimum LogLevel for stdout/stderr 标准输出/标准错误的最小 LogLevel
• Minimum LogLevel for log files 日志文件的最小 LogLevel
• Automatic log file naming and daily rotation, or custom log file name 自动日志文件命名和每日轮换，或自定义日志文件名
• Directory for writing log files 写入日志文件的目录
• Plain text or JSON log file formatting 纯文本或 JSON 日志文件格式
• Filtering of individual components by log level 按日志级别过滤各个组件
• ANSI colors in log lines 日志行中的 ANSI 颜色
• Bypass logging completely 完全绕过日志记录
• Print Rust config to stdout at initialization 在初始化时将 Rust 配置打印到标准输出

Standard output logging 标准输出日志记录

Log messages are written to the console via stdout/stderr writers. The minimum log level can be configured using the log_level parameter.

日志消息通过标准输出/标准错误写入器写入控制台。可以使用 log_level 参数配置最小日志级别。

File logging 文件日志记录

Log files are written to the current working directory with daily rotation (UTC) by default.

默认情况下，日志文件写入当前工作目录，并按日轮换 (UTC)。

The default naming convention is as follows:

默认命名约定如下：

• Trader ID 交易者 ID
• ISO 8601 datetime ISO 8601 日期时间
• Instance ID 实例 ID
• The log format suffix 日志格式后缀
• {trader_id}_{%Y-%m-%d}_{instance_id}.{log | json}

e.g. TESTER-001_2023-03-23_635a4539-4fe2-4cb1-9be3-3079ba8d879e.json

例如：TESTER-001_2023-03-23_635a4539-4fe2-4cb1-9be3-3079ba8d879e.json

You can specify a custom log directory path using the log_directory parameter and/or a custom log file basename using the log_file_name parameter. The log files will always be suffixed with '.log' for plain text, or '.json' for JSON (no need to include a suffix in file names).

您可以使用 log_directory 参数指定自定义日志目录路径，并/或使用 log_file_name 参数指定自定义日志文件基本名称。对于纯文本，日志文件将始终以 '.log' 作为后缀，对于 JSON，则以 '.json' 作为后缀（无需在文件名中包含后缀）。

If the log file already exists, it will be appended to.

如果日志文件已存在，则会附加到该文件。

Component filtering 组件过滤

The log_component_levels parameter can be used to set log levels for each component individually. The input value should be a dictionary of component ID strings to log level strings: dict[str, str].

log_component_levels 参数可用于分别设置每个组件的日志级别。输入值应为组件 ID 字符串到日志级别字符串的字典：dict[str, str]。

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

以下是一个交易节点日志记录配置的示例，其中包含上面提到的一些选项：

from nautilus_trader.config import LoggingConfig
from nautilus_trader.config import TradingNodeConfig

config_node = TradingNodeConfig(
    trader_id="TESTER-001",
    logging=LoggingConfig(
        log_level="INFO",
        log_level_file="DEBUG",
        log_file_format="json",
        log_component_levels={ "Portfolio": "INFO" },
    ),
    ... # Omitted
)

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

对于回测，可以使用 BacktestEngineConfig 类代替 TradingNodeConfig，因为可以使用相同的选项。

Log Colors 日志颜色

ANSI color codes are utilized to enhance the readability of logs when viewed in a terminal. These color codes can make it easier to distinguish different parts of log messages. 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.

当在终端中查看时，ANSI 颜色代码用于增强日志的可读性。这些颜色代码可以更容易地区分日志消息的不同部分。在不支持 ANSI 颜色渲染的环境（例如某些云环境或文本编辑器）中，这些颜色代码可能不合适，因为它们可能显示为原始文本。

To accommodate for such scenarios, the LoggingConfig.log_colors option can be set to false. Disabling log_colors will prevent the addition of ANSI color codes to the log messages, ensuring compatibility across different environments where color rendering is not supported.

为了适应这种情况，可以将 LoggingConfig.log_colors 选项设置为 false。禁用 log_colors 将阻止向日志消息添加 ANSI 颜色代码，从而确保在不支持颜色渲染的不同环境中兼容。

Using a Logger directly 直接使用 Logger

It's possible to use Logger objects directly, and these can be initialized anywhere (very similar to the Python built-in logging API).

可以直接使用 Logger 对象，并且可以在任何地方初始化这些对象（与 Python 内置的日志记录 API 非常相似）。

If you aren't using an object which already initializes a NautilusKernel (and logging) such as BacktestEngine or TradingNode, then you can initialize logging in the following way:

如果您没有使用已经初始化 NautilusKernel（和日志记录）的对象，例如 BacktestEngine 或 TradingNode，则可以通过以下方式初始化日志记录：

from nautilus_trader.common.component import init_logging
from nautilus_trader.common.component import Logger

log_guard = init_logging()
logger = Logger("MyLogger")

info 信息

See the init_logging API Reference for further details.

有关更多详细信息，请参阅 init_logging API 参考。

warning 警告

Only one logging system can be initialized per process with an init_logging call, and the LogGuard which is returned must be kept alive for the lifetime of the program.

每个进程只能通过 init_logging 调用初始化一个日志记录系统，并且返回的 LogGuard 必须在程序的整个生命周期内保持活动状态。