197 lines
No EOL
5.4 KiB
Markdown
197 lines
No EOL
5.4 KiB
Markdown
# WooCommerce 远程日志记录
|
||
|
||
一个为 Automattic 项目设计的远程日志记录包。此包提供错误跟踪和日志记录功能，支持速率限制、堆栈跟踪格式化和自定义错误过滤。
|
||
|
||
## 安装
|
||
|
||
```bash
|
||
npm install @woocommerce/remote-logging --save
|
||
```
|
||
|
||
## 描述
|
||
|
||
WooCommerce 远程日志包提供以下产品特点：
|
||
|
||
- 包含堆叠追踪分析的远程错误日志记录
|
||
- 可自定义的日志严重级别
|
||
- 防止 API 泛滥的速率限制
|
||
- 自动捕获未处理的错误和 Promise 拒绝
|
||
- 基于 WooCommerce 资源路径的错误筛选
|
||
- 通过 WordPress 筛选器实现可扩展性
|
||
|
||
## 用法
|
||
|
||
1. 在应用程序开始时初始化远程日志记录器。如果您的插件依赖于 WooCommerce 插件，日志记录器将在 WooCommerce 中初始化，因此您无需调用此函数。
|
||
|
||
```js
|
||
import { init } from '@woocommerce/remote-logging';
|
||
|
||
init({
|
||
errorRateLimitMs: 60000 // 将速率限制设置为 1 分钟
|
||
});
|
||
```
|
||
|
||
2. 记录消息或错误：
|
||
|
||
```js
|
||
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](https://github.com/woocommerce/woocommerce/blob/trunk/plugins/woocommerce/src/Internal/Logging/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` (数组)：来自错误的堆栈帧数组。
|
||
|
||
**返回值：** (布尔值) 是否应发送错误。
|
||
|
||
**用法示例：**
|
||
|
||
```js
|
||
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) 修改后的错误数据对象。
|
||
|
||
**用法示例：**
|
||
|
||
```js
|
||
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` (字符串): 默认的端点网址。
|
||
|
||
**返回值:** (字符串) 修改后的端点网址。
|
||
|
||
**用法示例:**
|
||
|
||
```js
|
||
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 错误端点网址。
|
||
|
||
**用法示例：**
|
||
|
||
```js
|
||
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[]) 修改后的白名单。
|
||
|
||
**用法示例:**
|
||
|
||
```js
|
||
import { addFilter } from '@wordpress/hooks';
|
||
|
||
addFilter(
|
||
'woocommerce_remote_logging_request_uri_whitelist',
|
||
'my-plugin',
|
||
( whitelist ) => {
|
||
return [ ...whitelist, 'exampleParam' ]
|
||
}
|
||
);
|
||
``` |
