woocommerce/packages/js/remote-logging/zh-cn/README.md

WooCommerce 远程日志记录

一个为 Automattic 项目设计的远程日志记录包。此包提供错误跟踪和日志记录功能，支持速率限制、堆栈跟踪格式化和自定义错误过滤。

安装

npm install @woocommerce/remote-logging --save

描述

WooCommerce 远程日志包提供以下产品特点：

• 包含堆叠追踪分析的远程错误日志记录
• 可自定义的日志严重级别
• 防止 API 泛滥的速率限制
• 自动捕获未处理的错误和 Promise 拒绝
• 基于 WooCommerce 资源路径的错误筛选
• 通过 WordPress 筛选器实现可扩展性

用法

1. 在应用程序开始时初始化远程日志记录器。如果您的插件依赖于 WooCommerce 插件，日志记录器将在 WooCommerce 中初始化，因此您无需调用此函数。

   import { init } from '@woocommerce/remote-logging';
   
   init({
     errorRateLimitMs: 60000 // 将速率限制设置为 1 分钟
   });
   

2. 记录消息或错误：

   import { log, captureException } from '@woocommerce/remote-logging';
   
   // 记录一条信息性消息
   log('info', '用户完成结账', { extra: { orderId: '12345' } });
   
   // 记录一条警告
   log('warning', 'API 请求失败，正在重试...', { extra: { attempts: 3 } });
   
   // 记录一个错误
   try {
     // 一些可能抛出错误的操作
   } catch (error) {
     captureException(error, { extra: { orderId: '12345' } });
   }
   

远程日志记录条件

远程日志记录需满足以下条件：

1. 远程日志记录已启用：该软件包会检查 window.wcSettings.isRemoteLoggingEnabled 以确定是否应启用此功能。该值通过 PHP 设置并作为布尔值传递给 JS。它要求内部启用 Tracks 并满足其他一些条件。请参阅 RemoteLogger.php 了解更多详情。

2. 非开发环境：它还会检查 process.env.NODE_ENV，以确保日志记录仅在非开发环境中进行。

如果这些条件中的任何一个未满足（Tracks 未启用或环境为开发环境），则不会将任何日志传输到远程服务器。

API 参考

• init(config: RemoteLoggerConfig): void: 使用给定的配置初始化远程日志记录器。
• log(severity: LogSeverity, message: string, extraData?: object): Promise<boolean>: 记录一条具有指定严重级别和可选额外数据的消息。
• captureException(error: Error, extraData?: object): void: 捕获一个错误并将其发送到远程 API。

有关类型和界面的更详细信息，请参阅源代码和内联文档。

自定义

您可以使用 WordPress 过滤器来自定义远程日志记录器的行为。以下是可用的过滤器：

woocommerce_remote_logging_should_send_error

控制是否应将错误发送到远程 API。

参数：

• shouldSend (布尔值)：关于是否发送错误的默认决定。
• error (错误)：错误对象。
• stackFrames (数组)：来自错误的堆栈帧数组。

返回值： (布尔值) 是否应发送错误。

用法示例：

import { addFilter } from '@wordpress/hooks';

addFilter(
  'woocommerce_remote_logging_should_send_error',
  'my-plugin',
  (shouldSend, error, stackFrames) => {
    const containsPluginFrame = stackFrames.some(
      (frame) => frame.url && frame.url.includes( /YOUR_PLUGIN_ASSET_PATH/ )
    );
    // 仅发送源自我们插件的错误
    return shouldSend && containsPluginFrame;
  }
);

woocommerce_remote_logging_error_data

在将错误数据发送到远程 API 前修改它。

参数：

• errorData (ErrorData): 要发送的错误数据对象。

返回值： (ErrorData) 修改后的错误数据对象。

用法示例：

import { addFilter } from '@wordpress/hooks';

addFilter(
  'woocommerce_remote_logging_error_data',
  'my-plugin',
  (errorData) => {
    // 自定义逻辑以修改错误数据
    errorData.tags = [ ...errorData.tags, 'my-plugin' ];
    return errorData;
  }
);

woocommerce_remote_logging_log_endpoint

修改远程日志记录 API 端点的网址。

参数:

• endpoint (字符串): 默认的端点网址。

返回值: (字符串) 修改后的端点网址。

用法示例:

import { addFilter } from '@wordpress/hooks';

addFilter(
  'woocommerce_remote_logging_log_endpoint',
  'my-plugin',
  (endpoint) => 'https://my-custom-endpoint.com/log'
);

woocommerce_remote_logging_js_error_endpoint

修改用于 JavaScript 错误的远程日志记录 API 端点的网址。

参数：

• endpoint (字符串)：JavaScript 错误的默认端点网址。

返回值： (字符串) 修改后的 JavaScript 错误端点网址。

用法示例：

import { addFilter } from '@wordpress/hooks';

addFilter(
  'woocommerce_remote_logging_js_error_endpoint',
  'my-plugin',
  (endpoint) => 'https://my-custom-endpoint.com/js-error-log'
);

woocommerce_remote_logging_request_uri_whitelist

修改在记录的请求 URI 中不会被屏蔽的白名单查询参数列表

参数:

• whitelist (string[]): 默认的白名单。

返回值: (string[]) 修改后的白名单。

用法示例:

import { addFilter } from '@wordpress/hooks';

addFilter(
  'woocommerce_remote_logging_request_uri_whitelist',
  'my-plugin',
  ( whitelist ) => {
    return [ ...whitelist, 'exampleParam' ]
  }
);