跳到主要内容

WooCommerce 日志记录

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

查看日志​

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

文件系统​

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

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

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

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

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

数据库​

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

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

配置日志记录器​

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

日志记录器​

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

日志存储​

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

  • 文件系统 - 日志条目记录到文件中。 文件通过日志条目的 source 值（请参阅下面的“添加日志”部分）以及当前日期进行区分。 这些文件存储在站点的 uploads 目录下的 wc-logs 子目录中。 可以使用 woocommerce_log_directory 过滤器钩子定义自定义目录。 日志文件的大小可以达到 5MB，超过此大小后，日志文件将进行轮换。
  • 数据库 - 日志条目记录到数据库中的 {$wpdb->prefix}woocommerce_log 表中。

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

保留期限​

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

级别阈值​

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

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

添加日志​

日志是通过 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 方法。

级别​

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

  • emergency
  • alert
  • critical
  • error
  • warning
  • notice
  • info
  • debug

除了为网站所有者提供有关日志条目的重要性的上下文信息外，这些级别还允许对日志进行过滤。 如果您只想记录严重性级别为 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 值。这对于与 错误 相关的日志特别有用，这样您就可以看到导致 生成 该日志条目的代码。

完整示例​

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' ),
    )
);

日志记录的最佳实践​

何时使用日志记录​

  • 用于解决意外问题：
    • 从 API 接收到意外的值或 错误。
    • 系统中的数据不正确或已损坏。
    • 应用程序处于意外或损坏的状态。
  • 用于记录过程的审计日志：
    • 未在其他地方存储的事务 详情，例如订单备注（但可能应该存储？）。
    • 数据导入或导出的 结果。
    • 重要的 设置 被更改。
    • 自动化过程更改或删除数据。

何时不使用日志记录​

  • 用于告知开发人员他们正在错误地使用某个方法或 API。这可能会导致大量的无用日志条目，尤其是在它会在每个 网页 请求时触发的情况下。 最好通过 错误 或异常（例如 wc_doing_it_wrong()）提供即时 反馈。

最佳实践​

  • 与其直接使用 WC_Logger 的 log() 方法，最好使用专门针对日志级别的包装方法，例如 info() 或 error()。
  • 编写一个完整、连贯的句子作为日志信息。 这将使其对不熟悉代码库的人更有用。
  • 日志信息不应是可翻译的。 保持信息以英文书写，可以更轻松地根据信息内容搜索解决方案，并且也便于任何进行故障排除的人理解正在发生的情况，因为他们可能使用的语言与网站所有者使用的语言不同。
  • 理想情况下，每个日志条目的信息应该是一行（即，信息字符串中不应包含换行符）。 额外的行或额外数据应放在 context 数组中。
  • 避免在信息字符串中输出结构化数据。 将其放在 context 数组中的键中。 日志记录器将负责将其转换为 JSON 格式，并在日志查看器中使其易于阅读。
  • 如果需要包含堆栈跟踪，请让日志记录器为您生成它。
  • 为正在使用的组件或系统选择一个来源，并在每次调用日志记录时使用它。 这将使查找与该组件相关的日志条目更容易，并将其与其他不相关的日志条目过滤掉。
  • 考虑在循环过程之后添加一个日志条目，其中包含循环的聚合结果，而不是在循环中的每个条目时添加单独的条目。

自定义日志记录器​

日志记录器类​

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

日志处理程序​

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

  • Automattic\\WooCommerce\\Internal\\Admin\\Logging\\LogHandlerFileV2: 这是一个默认的处理程序，代表“文件系统”日志存储方法。 它将日志条目记录到文件中。
  • WC_Log_Handler_File: 这是一个旧的默认处理程序，也用于将日志条目记录到文件中。 可能会在未来被弃用，并且不建议使用此类或对其进行扩展。
  • WC_Log_Handler_DB: 此处理程序代表“数据库”日志存储方法。 它将日志条目记录到数据库中。
  • WC_Log_Handler_Email: 此处理程序不存储日志条目，而是将其作为电子邮件发送。 电子邮件发送到站点的管理员邮箱。 此处理程序有一些 限制。

更改或添加处理程序​

要从文件处理程序切换到数据库处理程序，您可以简单地更新“日志设置”屏幕上的选项。 但是，在某些情况下，您可能希望拥有多个日志处理程序，并且/或您可能希望修改处理程序的设置。 例如，您可能希望将大多数日志保存到文件中，但将分类为紧急或严重错误的日志条目也发送到 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 );

日志界面​

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

  • woocommerce_logger_handler_options: 此过滤器钩子允许您将自定义日志句柄添加到“日志存储”选项的列表中，位于“设置”界面。 必须首先选择您的句柄，使其成为“默认”日志句柄，然后才能为其渲染替代界面。
  • wc_logs_render_page: 这是用于渲染您自己的日志界面的动作钩子。 它仅在默认日志句柄设置为内置句柄之外的选项时才会触发。
  • wc_logs_load_tab: 此动作在日志选项卡首次加载时触发，在任何内容输出之前。 它对于处理表单提交非常有用。