WooCommerce 文档

title: "WooCommerce 日志记录" post_status: publish comment_status: open taxonomy: category: - woocommerce post_tag: - Data Management - Best Practices - Repos

WooCommerce 日志记录

WooCommerce 拥有一个强大的日志记录系统，可用于在开发期间进行调试，在生产环境中捕获错误，甚至在发生特定事件时发送通知。 默认情况下，WooCommerce 使用此日志记录器来记录可能有助于解决商店问题的错误、警告和其他通知。 许多 WooCommerce 扩展也使用此日志记录器来实现类似的目的。

查看日志

您可以通过访问 WooCommerce > 状态 > 日志 来查看日志记录器创建的条目。 日志查看界面取决于配置的日志存储方法（请参阅下面的“配置日志记录器”部分）。

文件系统

使用默认的文件系统存储方法，您首先会看到现有日志文件的列表：

默认的日志查看界面，显示日志文件列表

日志文件的名称基于其包含条目的来源（即扩展或 WooCommerce 代码库的一部分），以及创建条目的日期。 在此文件浏览视图中，您可以以不同的方式对文件进行排序，还可以对其进行过滤，仅显示来自特定来源的文件。 单击文件将进入单个文件视图，您可以在其中查看实际的日志条目：

日志文件内容

单击文件中的行号以突出显示该行。 这也可以用于从其他位置链接到文件中的特定行。

从文件浏览器视图，您可以对日志文件列表进行排序和过滤，然后在这些文件的内容中搜索字符串：

搜索结果列表

单击搜索结果中的行号将带您到单个文件视图中的该行。

数据库

使用数据库存储方法，您将看到日志条目的列表，从最近的条目开始：

当日志条目存储在数据库中时的日志查看界面

这些条目可以按时间戳、级别和来源进行排序，也可以进行过滤，仅显示特定来源或最小级别。 您还可以搜索日志条目消息字段中的字符串。

配置日志记录器

从 WooCommerce > 状态 > 日志 屏幕上的“日志”屏幕，单击“设置”链接以进行配置更改：

日志设置屏幕

日志记录器

取消此处的复选框以关闭所有日志记录。 在大多数情况下，不建议这样做，因为日志记录可以提供有关您网站上正在发生情况的宝贵信息！

日志存储

默认情况下，WooCommerce 提供了两种不同的日志存储方法：

如果您更改此设置，并且已经存在一些日志条目，则这些条目将不会迁移到其他存储方法，但也不会被删除。

保留期限

日志记录器会定期检查并删除超过此时间段的旧日志，以节省空间。 如果日志条目存储在文件系统中，则超出保留期限的整个日志文件将被删除；而对于数据库存储，则会删除单个日志条目。

级别阈值

每个日志条目都有一个严重性级别（请参阅下面的“添加日志”部分）。 此设置定义一个最小严重性级别，任何生成且严重性级别低于或等于此最小级别的日志条目将不会被记录。 请谨慎使用此设置！

如果此设置设置为“无”，则表示所有日志条目都将被记录，无论其严重性级别如何。

添加日志

日志是通过 WC_Logger 类的各种方法添加的。 可以使用 wc_get_logger() 函数访问类实例。 添加日志条目的基本方法是 [WC_Logger::log( $level, $message, $context )](https://woocommerce.github.io/code-reference/classes/WC-Logger.html#method_log)。 此外，还提供了每个日志严重性级别的快捷方法，例如 WC_Logger::warning( $message, $context )。 建议使用快捷方法而不是通用的 log 方法。

级别

日志有八个不同的严重性级别：

除了为网站所有者提供有关日志条目的重要性的上下文信息外，这些级别还允许对日志进行过滤。 如果您只想记录严重性级别为 error 及以上的日志条目，可以在“日志设置”屏幕上设置阈值（请参阅上面的“配置日志记录器”）。

请注意，此阈值适用于所有日志，无论使用哪种日志处理程序。 例如，WC_Log_Handler_Email 类具有自己的阈值设置，但它不如全局阈值重要。

信息

信息是日志条目的主要内容。 确保其内容易于任何可能查看日志的人理解！

上下文

Context 参数旨在用于存储与日志条目相关的附加结构化数据。例如，在关于订单的日志条目中，您可能希望包含相关订单对象的 内容。当日志记录器 生成 一个条目时，Context 参数中的数据会转换为 JSON 格式后再进行存储。因此，如果您想添加多个 Context 数据，每个数据都应该作为 Context 数组中的一个单独的键进行添加。

有两个特定的键可以添加到 Context 数组中，它们会触发特殊的行为：

source

建议每个日志条目都包含一个 source 值在 Context 参数中。source 的目的是提供关于日志是在应用程序或代码库的哪个位置 生成 的 上下文 信息，并且可以用于过滤日志条目。

如果未指定 source，日志记录器会根据 生成 日志条目的插件或文件 生成 一个 source 值。

backtrace

将 Context 参数中的 backtrace 键设置为 true 会导致日志记录器 生成 一个 backtrace（即堆栈跟踪），该 backtrace 以数组格式存储，并将其包含在 Context 中，替换 true 值。这对于与 错误 相关的日志特别有用，这样您就可以看到导致 生成 该日志条目的代码。

在日志文件查看器中显示的 backtrace

完整示例

wc_get_logger()->info(
    'It is time for lunch.',
    array(
        'source'        => 'your_stomach',
        'backtrace'     => true,
        'previous_meal' => $elapsed_time_since_breakfast,
        'lunch_options' => array( 'fridge leftovers', 'bahn mi', 'tacos', 'pupusas' ),
    )
);

日志记录的最佳实践

何时使用日志记录

何时不使用日志记录

最佳实践

自定义日志记录器

日志记录器类

可以通过 woocommerce_logging_class 过滤器钩子，用另一个类替换 WC_Logger 类。 替代类必须实现 WC_Logger_Interface，否则将不会使用。 通常，最好创建自定义日志处理程序（见下文），而不是直接覆盖日志记录器类。

日志处理程序

在 WooCommerce 中，日志处理程序是一个 PHP 类，它接收原始日志数据并将其转换为可以存储或分发的日志条目。 WooCommerce 提供了四种不同的日志处理程序类：

更改或添加处理程序

要从文件处理程序切换到数据库处理程序，您可以简单地更新“日志设置”屏幕上的选项。 但是，在某些情况下，您可能希望拥有多个日志处理程序，并且/或您可能希望修改处理程序的设置。 例如，您可能希望将大多数日志保存到文件中，但将分类为紧急或严重错误的日志条目也发送到 Email 地址。为此，您可以使用 woocommerce_register_log_handlers 过滤器钩子来创建您想要使用的日志处理程序类实例的数组。 一些处理程序类构造函数具有可选参数，您可以在实例化类时使用这些参数来更改其默认行为。

以下是添加 Email 处理程序的示例：

function my_wc_log_handlers( $handlers ) {
    $recipients = array( 'wayne@example.com', 'garth@example.com' ); // 将日志发送到多个接收者。
    $threshold  = 'critical'; // 仅为具有此级别及更高级别的日志发送电子邮件。
    $handlers[] = new WC_Log_Handler_Email( $recipients, $threshold );

    return $handlers;
}
add_filter( 'woocommerce_register_log_handlers', 'my_wc_log_handlers' );

创建自定义处理程序

您可能希望创建自己的日志处理程序类，以便将日志发送到其他位置，例如 Slack 频道或 InfluxDB 实例。 您的类必须扩展 WC_Log_Handler 抽象类，并实现 WC_Log_Handler_Interface 界面。 WC_Log_Handler_Email 处理程序类提供了一个很好的示例，说明如何设置它。

日志文件存储位置

当使用“文件系统”日志处理程序时，默认情况下，日志文件存储在 WordPress “uploads” 目录中的 wc-logs 子目录中，这意味着它们可能可以公开访问。 WooCommerce 会添加一个 .htaccess 文件以防止访问 wc-logs，但并非所有 Web 服务器都识别该文件。 如果有选项，您可能希望考虑将您的日志文件存储在 Web 根目录之外的目录中。 确保该目录具有与 “uploads” 目录相同的用户/组 权限，以便 WordPress 可以访问它。 然后，使用 woocommerce_log_directory 过滤器钩子来设置指向您自定义目录的路径。

禁用冗余日志

如果某个日志信息频繁出现，并且阻塞了您的日志文件，您应该尝试找出它为什么会频繁触发，并解决问题。 但是，如果无法解决，您可以向 woocommerce_logger_log_message 过滤器钩子添加一个回调函数，以忽略该特定日志信息，同时允许其他日志信息通过：

function my_ignored_logs( $message, $level, $context, $handler ) {
    if ( false !== strpos( $message, 'Look, a squirrel!' ) ) {
        return null;
    }

    return $message;
}
add_filter( 'woocommerce_logger_log_message', 'my_ignored_logs', 10, 4 );

日志界面

如果您创建了一个自定义日志句柄，并且希望在该日志句柄上构建一个独立的界面，您可以使用以下几个过滤器钩子：