日志记录¶

Kedro使用Python的logging库。配置以字典形式提供，遵循Python日志记录配置模式，如下所述。

默认情况下，Python仅显示WARNING及以上级别的日志消息。Kedro的日志配置指定来自Kedro的INFO级别消息也应被输出。这使得在执行kedro run时更容易跟踪管道的进度。

默认日志配置¶

Kedro的默认日志配置定义了一个名为rich的处理器，该处理器使用Rich日志处理器来格式化消息。我们还使用Rich回溯处理器来渲染异常信息。

如何在您的Kedro项目中执行日志记录¶

要在自己的代码中添加日志记录（例如在节点中）：

import logging

logger = logging.getLogger(__name__)
logger.warning("Issue warning")
logger.info("Send information")
logger.debug("Useful information for debugging")

你可以在日志调用中使用Rich的console markup：

logger.error("[bold red blink]Important error message![/]", extra={"markup": True})

如何自定义Kedro日志记录¶

要自定义Kedro项目中的日志记录，您需要指定项目专属日志配置文件的路径。通过修改环境变量KEDRO_LOGGING_CONFIG来覆盖默认的日志配置。建议将该变量指向您存储在项目conf目录下的项目专属配置文件，并将其命名为logging.yml。

例如，您可以通过在终端中输入以下内容来设置 KEDRO_LOGGING_CONFIG：

export KEDRO_LOGGING_CONFIG=<project_root>/conf/logging.yml

设置环境变量后，任何后续的Kedro命令将使用指定路径下的日志配置文件。

注意

如果未设置KEDRO_LOGGING_CONFIG环境变量，Kedro将使用默认日志配置。

调整Kedro特定部分的日志详细程度¶

您还可以在运行时自定义日志记录，并在使用Jupyter笔记本时重新定义logging.yml中提供的日志配置。以下示例展示了如何将kedro.io.data_catalog组件记录器的日志级别从默认的INFO更改为WARNING，而其他组件的日志记录将保持不变。同样的方法可以应用于更高/更低级别的组件，而不会影响顶层组件。

在您的笔记本单元格中添加以下内容：

import logging

logging.getLogger("kedro.io.data_catalog").setLevel(logging.WARNING)

自定义带日志记录的`CONF_SOURCE`¶

当你在Kedro项目中自定义CONF_SOURCE设置时，它决定了Kedro查找配置文件的位置，包括日志配置文件。然而，更改CONF_SOURCE不会自动更新logging.yml的路径。要为日志配置使用自定义位置或文件名，你必须显式设置KEDRO_LOGGING_CONFIG环境变量。

默认情况下，Kedro会在conf目录中查找名为logging.yml的文件。如果您在更改CONF_SOURCE后移动或重命名了日志配置文件，请使用KEDRO_LOGGING_CONFIG环境变量指定新路径：

export KEDRO_LOGGING_CONFIG=<project_root>/custom_config_folder/custom_logging_name.yml

请注意，在不相应更新日志配置的情况下调整CONF_SOURCE或重命名logging.yml可能导致Kedro无法定位该文件，从而将使用默认日志设置。

如何显示DEBUG级别的消息¶

要查看DEBUG级别的日志信息，请修改项目专属日志配置文件(logging.yml)中的日志级别。我们提供了一个logging.yml模板：

Click to expand the logging.yml template


version: 1

disable_existing_loggers: False

formatters:
  simple:
    format: "%(asctime)s - %(name)s - %(levelname)s - %(message)s"

handlers:
  console:
    class: logging.StreamHandler
    level: INFO
    formatter: simple
    stream: ext://sys.stdout

  info_file_handler:
    class: logging.handlers.RotatingFileHandler
    level: INFO
    formatter: simple
    filename: info.log
    maxBytes: 10485760 # 10MB
    backupCount: 20
    encoding: utf8
    delay: True

  rich:
    class: kedro.logging.RichHandler
    rich_tracebacks: True
    # Advance options for customisation.
    # See https://docs.kedro.org/en/stable/logging/index.html#how-to-perform-logging-in-your-kedro-project
    # tracebacks_show_locals: False

loggers:
  kedro:
    level: INFO

  your_python_package:
    level: INFO

root:
  handlers: [rich]

你需要修改这一行：

loggers:
  kedro:
    level: INFO

  your_python_package:
-   level: INFO
+   level: DEBUG

注意

日志记录器的名称对应于日志配置文件中loggers部分的键（例如kedro）。更多信息请参阅Python的日志记录文档。

通过将所需日志记录器（例如）的级别值更改为DEBUG，您将开始在日志输出中看到DEBUG级别的消息。

注意

当项目的日志级别设置为DEBUG且项目中启用了hooks时，hooks会使用pluggy的追踪功能记录每个hook的执行情况。这对调试很有帮助，但可能会产生大量日志并降低流水线执行速度。您可以通过将日志级别设为INFO或更高来禁用此功能。

高级日志记录¶

除了Kedro框架中定义的rich处理器外，我们在模板中还提供了两个额外的处理器。

console: 在标准输出（通常是终端屏幕）上显示日志，不进行任何富文本格式化
info_file_handler: 将INFO级别及以上的日志写入info.log

以下部分展示了一些常见示例，说明如何更改项目的日志配置。

如何自定义`rich`处理器¶

Kedro的kedro.logging.RichHandler是rich.logging.RichHandler的子类，并支持相同的参数集。默认情况下，rich_tracebacks设置为True以使用rich渲染异常。但您可以通过设置rich_tracebacks: False来禁用它。

注意

如果你想禁用rich的追踪回溯功能，必须将KEDRO_LOGGING_CONFIG指向你的本地配置文件，即conf/logging.yml。

当rich_tracebacks设置为True时，该配置会传播到rich.traceback.install。如果参数与rich.traceback.install兼容，它将被传递给回溯的设置。

例如，您可以在logging.yml中启用局部变量的显示以辅助调试。

  rich:
    class: kedro.logging.RichHandler
    rich_tracebacks: True
+   tracebacks_show_locals: True

完整的可用选项列表可在RichHandler文档中找到。

如何启用基于文件的日志记录¶

在Python项目中使用基于文件的日志记录有助于故障排查和调试。它能提供更好的应用程序行为可见性，并且易于搜索。然而，这种方法在Databricks Repos等只读系统中效果不佳。

要启用基于文件的日志记录，请在你的conf/logging.yml文件中按如下方式将info_file_handler添加到root日志记录器中：

 root:
-  handlers: [rich]
+  handlers: [rich, info_file_handler]

默认情况下，它仅跟踪INFO级别的消息，但可以配置为捕获任何级别的日志。

如何使用普通控制台日志记录¶

要使用普通日志而非富文本日志，请按以下方式将rich处理器替换为console处理器：

 root:
-  handlers: [rich]
+  handlers: [console]

如何在简易终端中启用丰富日志记录¶

Rich 能够检测您的终端是否支持显示富格式消息。如果您的终端是"哑终端"，那么格式会自动被移除，日志仅显示纯文本。这种情况可能发生在您在CI（如GitHub Actions或CircleCI）上执行kedro run命令时。

如果您发现日志消息的默认换行宽度过窄，但又不希望在CI环境中切换到使用console日志记录器，那么控制日志消息换行的最简单方法是通过修改COLUMNS和LINES环境变量来实现。例如：

export COLUMNS=120 LINES=25

注意

即使您只想更改日志消息的宽度，也必须为COLUMNS和LINES提供值。Rich对这些变量的默认值为COLUMNS=80和LINE=25。

如何在Jupyter中启用丰富的日志记录¶

Rich同样支持在JupyterLab和Jupyter Notebook中格式化日志输出。输出控制台的大小不会自动适应窗口，但可以通过环境变量JUPYTER_COLUMNS和JUPYTER_LINES进行控制。默认值（分别为115和100）应该能满足大多数用户需求，但如果您需要不同的输出控制台尺寸，可以调整JUPYTER_COLUMNS和JUPYTER_LINES的值。

如何在不使用rich库的情况下使用日志记录¶

如果您不希望Kedro项目中包含rich库，可以选择卸载它。但需要注意的是，2.3版本以上的cookiecutter库依赖于rich。要使Kedro在不使用rich的情况下正常工作，您需要将cookiecutter降级到2.3以下版本。

要卸载rich库，请运行：

pip uninstall rich

要将cookiecutter降级到不需要rich的版本，您可以指定2.3以下的版本。例如：

pip install cookiecutter==2.2.0

这些更改将影响Kedro日志记录、提示信息以及kedro ipython命令输出的视觉外观和格式。当使用低于2.3版本的cookiecutter时，即使安装了rich，提示信息的显示也会保持简洁样式。