# @dotcom-reliability-kit/client-metrics-web 中文文档

规范地址：https://npmcn.com/package/%40dotcom-reliability-kit/client-metrics-web/

版本：2\.1\.2
npm 元数据更新时间：2026-08-19T16:08:05.383Z
中文译文更新时间：2026-11-13T01:46:39.294Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40dotcom-reliability-kit/client-metrics-web
原文对照：https://npmcn.com/package/%40dotcom-reliability-kit/client-metrics-web/?lang=original
项目主页：https://github.com/Financial-Times/dotcom-reliability-kit/tree/main/packages/client-metrics-web#readme
源码仓库：https://github.com/Financial-Times/dotcom-reliability-kit

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：62 kB，27 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：^22\.12 \|\| ^24 \|\| ^26
- 运行依赖：1 个
- 首次发布：2025-04-09T14:03:45.093Z
- 最新版本发布：2026-08-19T16:08:05.205Z
- 近 30 天下载量：2600（2026-10-13 至 2026-11-11，npm 官方下载统计）
- 已发布版本数：13（近 12 个月 8 个）

## 中文简介

从网络向客户端计量服务器发送操作计量的客户端

## 安装

```sh
npm install @dotcom-reliability-kit/client-metrics-web
```

也可以使用：`pnpm add @dotcom-reliability-kit/client-metrics-web`、`yarn add @dotcom-reliability-kit/client-metrics-web`、`bun add @dotcom-reliability-kit/client-metrics-web`

## README

# @dotcom - 可靠性- kit/ 客户端- 度量仪- 网络

从浏览器发送操作度量事件到 [客户产品客户端计量服务器](https://github.com/Financial-Times/cp-client-metrics-server/tree/main)。本模块是 [FT.com 可靠性工具包](https://github.com/Financial-Times/dotcom-reliability-kit#readme)。 。 。 .

> \[尖叫声\] 此可靠性 Kit 模块用于客户端 JavaScript 。 将它导入到一个 Node.js app 将会导致错误被扔出.

> \[大 记住,这个图书馆是用来发送 _业务_ 度量衡 - 帮助我们了解您的系统是否按预期运行的度量衡. 对于分析数据,你仍应该使用Spoor(或团队共同的另一种解决方案).

-   [使用量(系统)](https://npmcn.com/package/%40dotcom-reliability-kit/client-metrics-web/#readme-usage-systems)
    -   [`MetricsClient`](https://npmcn.com/package/%40dotcom-reliability-kit/client-metrics-web/#readme-metricsclient)
        -   [`client.recordEvent()`](https://npmcn.com/package/%40dotcom-reliability-kit/client-metrics-web/#readme-clientrecordevent)
        -   [`client.enable()`](https://npmcn.com/package/%40dotcom-reliability-kit/client-metrics-web/#readme-clientenable)
        -   [`client.disable()`](https://npmcn.com/package/%40dotcom-reliability-kit/client-metrics-web/#readme-clientdisable)
        -   [`client.isEnabled`](https://npmcn.com/package/%40dotcom-reliability-kit/client-metrics-web/#readme-clientisenabled)
        -   [`client.isAvailable`](https://npmcn.com/package/%40dotcom-reliability-kit/client-metrics-web/#readme-clientisavailable)
    -   [基于事件的 API](https://npmcn.com/package/%40dotcom-reliability-kit/client-metrics-web/#readme-event-based-api)
    -   [处理错误](https://npmcn.com/package/%40dotcom-reliability-kit/client-metrics-web/#readme-error-handling)
    -   [配置选项](https://npmcn.com/package/%40dotcom-reliability-kit/client-metrics-web/#readme-configuration-options)
        -   [`options.systemCode`](https://npmcn.com/package/%40dotcom-reliability-kit/client-metrics-web/#readme-optionssystemcode)
        -   [`options.systemVersion`](https://npmcn.com/package/%40dotcom-reliability-kit/client-metrics-web/#readme-optionssystemversion)
        -   [`options.environment`](https://npmcn.com/package/%40dotcom-reliability-kit/client-metrics-web/#readme-optionsenvironment)
        -   [`options.batchSize`](https://npmcn.com/package/%40dotcom-reliability-kit/client-metrics-web/#readme-optionsbatchsize)
        -   [`options.sendIntervalSeconds`](https://npmcn.com/package/%40dotcom-reliability-kit/client-metrics-web/#readme-optionssendintervalseconds)
        -   [`options.queue`](https://npmcn.com/package/%40dotcom-reliability-kit/client-metrics-web/#readme-optionsqueue)
            -   [队列接口](https://npmcn.com/package/%40dotcom-reliability-kit/client-metrics-web/#readme-queue-interface)
                -   [选项](https://npmcn.com/package/%40dotcom-reliability-kit/client-metrics-web/#readme-options)
                -   [所需方法](https://npmcn.com/package/%40dotcom-reliability-kit/client-metrics-web/#readme-required-methods)
-   [使用量(共享图书馆)](https://npmcn.com/package/%40dotcom-reliability-kit/client-metrics-web/#readme-usage-shared-libraries)
-   [用法(基础设施)](https://npmcn.com/package/%40dotcom-reliability-kit/client-metrics-web/#readme-usage-infrastructure)
-   [测试](https://npmcn.com/package/%40dotcom-reliability-kit/client-metrics-web/#readme-testing)
-   [移动](https://npmcn.com/package/%40dotcom-reliability-kit/client-metrics-web/#readme-migrating)
-   [捐款](https://npmcn.com/package/%40dotcom-reliability-kit/client-metrics-web/#readme-contributing)
-   [许可证](https://npmcn.com/package/%40dotcom-reliability-kit/client-metrics-web/#readme-license)

## 使用量(系统)

想要从客户端发送度量衡的系统应当导入并构建度量衡客户端,作为其客户端-JavaScript的一部分. 如果你正在写代码 共享到多个系统 **不导入和构建计量客户端**。见 [共享图书馆使用指南](https://npmcn.com/package/%40dotcom-reliability-kit/client-metrics-web/#readme-usage-shared-libraries)。 。 。 .

安装 `@dotcom-reliability-kit/client-metrics-web` 作为依附关系:

```bash
npm install --save @dotcom-reliability-kit/client-metrics-web
```

在客户端代码中包含 :

```js
import { MetricsClient } from '@dotcom-reliability-kit/client-metrics-web';
```

> \[TIP\] 如果您使用此软件包并带有 TypeScript , 我们建议您使用以下设置: `tsconfig.json` 避免类型错误的文件 :
> 
> ```json
> {
>     "esModuleInterop": true,
>     "module": "nodenext",
>     "moduleResolution": "nodenext"
> }
> ```

### `MetricsClient`

MetricsClient 向客户端 Metrics 服务器发送事件, 使用 POST 到以下端点 `/api/v1/ingest`。 。 。 .

赛事加一批. 当批量达到最大容量,默认为20时,客户端将事件发送到服务器. 如果达不到最大容量,客户端每10秒发送一次事件. 这个 `sendIntervalSeconds` 是可配置的选项(参见 [`options.sendIntervalSeconds`](https://npmcn.com/package/%40dotcom-reliability-kit/client-metrics-web/#readme-optionssendIntervalSeconds)) (中文(简体) ). 如果批次没有增加事件,则不发送.

正确的环境(Production vs test)是根据浏览器主机名自动选择的. 如果您的主机名已经 `test`, (中文(简体) ), `staging` 或者说 `local`,事件将发送到我们的测试服务器。 否则,它会发送 度量衡到生产服务器.

这门课只能建一次 否则你就会发出重复的度量衡. 在加载页面时,您应该尽早构建度量衡客户端 。 所需选项见 [配置选项](https://npmcn.com/package/%40dotcom-reliability-kit/client-metrics-web/#readme-configuration-options)。 。 。 .

```js
const client = new MetricsClient({
    // Options go here
});
```

这将约束一些全球事件处理者:

-   `ft.clientMetric` - 根据事件发现的细节记录一个自定义的衡量标准([见下文文件](https://npmcn.com/package/%40dotcom-reliability-kit/client-metrics-web/#readme-event-based-api)(中文(简体) )

#### `client.recordEvent()`

发送计量事件 :

```js
client.recordEvent('example-namespace', {
    // Any event details you want to send can go here as key/value pairs
});
```

事件命名空间必须由字母字符、下划线和连字符组成。 命名空间将被转换为小写 . 如果您想要拥有顶级命名空间和二级命名空间,可以使用时段分隔符. 实例:

```
'top-level-namespace.success'
'top-level-namespace.failure'
```

另一个办法是将二级命名空间作为属性:

```
namespace: top-level-namespace,
status: success | failure
```

#### `client.enable()`

启用客户端 。 这是在即时状态下默认调用, 但是如果客户端被禁用, 您可能需要调用 .

```js
client.enable();
```

#### `client.disable()`

禁用客户端, 防止任何度量衡被发送 。 全球事件处理器也不受约束.

```js
client.disable();
```

#### `client.isEnabled`

显示当前客户端是否启用的布尔 .

#### `client.isAvailable`

一个布尔表示客户端是否正确配置和设置 。 如果这是 `false` 那么事件不可能被送到AWS Cloud Watch RUM.

### 基于事件的 API

根据复杂程度,在您的系统中绕过一个单一的客户实例可能不容易或更可取。 为此,我们也把一个听众绑在一起 `window` 联 合 国 `ft.clientMetric` 活动.

这使得您可以从系统中的任何地方发送计量事件,即使您无法访问客户端. 您需要发布一个自定义事件, 或是在窗口 :

```js
window.dispatchEvent(
    new CustomEvent('ft.clientMetric', {
        detail: {
            namespace: 'example-namespace',
            // Any event details you want to send can go here as key/value pairs
        }
    }
));
```

或从页面上的另一元素,只要您对事件进行放出:

```js
const element = document.getElementById('my-component');
element.dispatchEvent(
    new CustomEvent('ft.clientMetric', {
        bubbles: true,
        detail: {
            namespace: 'example-namespace',
            // Any event details you want to send can go here as key/value pairs
        }
    }
));
```

当以这种方式发送指标时 `detail` 对象可以拥有任意数量的属性。 这些属性将被提取入最终的度量衡事件并被发送到客户端度量衡服务器. 例如:

```js
window.dispatchEvent(
    new CustomEvent('ft.clientMetric', {
        detail: { namespace: 'snack.consumed', fruit: 'banana' }
    }
));

// is equivalent to:

client.recordEvent('snack.consumed', { fruit: 'banana' });
```

此选项默认启用 。 如果您想要禁用, 您可以设置 `enableEventApi` 旗为 `false` 当即时客户端计量构建器:

```js
new MetricsClient({ enableEventApi: false });
```

看为什么你会禁用它 [使用量(共享图书馆)](https://npmcn.com/package/%40dotcom-reliability-kit/client-metrics-web/#readme-usage-shared-libraries)。 。 。 .

### 处理错误

如果计量客户端的配置出问题 _或者说_ 发送一个事件, 我们不会丢出一个错误 - 这可能导致一个无限的循环, 我们试图记录 抛出的错误, 并扔出另一个错误.

而不是出错,我们记录一个警告到控制台。 如果您在 AWS 中没有看到度量衡, 请检查浏览器控制台 以获取这些警告 。 在推动任何变革之前,在当地发展中检查它们也是个好主意.

### 配置选项

配置选项可以传递到 `MetricsClient` 函数作为对象,并带有下面的任何键.

```js
new MetricsClient({
    // Config options go here
});
```

#### `options.systemCode`

**需求** `String`编辑 [毕斯 操作系统代码](https://biz-ops.in.ft.com/list/Systems) 你发送的度量衡.

```js
new MetricsClient({ systemCode: 'my-system' });
```

系统代码必须是字母数字字符的组合,可能由连字符相隔.

> \[大 如果系统Code设置不当,客户端将无法构建,无法发送任何事件. 试图使用 `recordEvent` 将失败并记录一个警告 `Client not initialised properly, cannot record an event.`

#### `options.systemVersion`

**可选** `String`。当前运行系统的版本号,帮助我们在新版本中发现问题。 这可能是一个版本编号或 git 承诺散列。 默认为 `0.0.0`。 。 。 .

```js
new MetricsClient({ systemVersion: '1.2.3' });
```

#### `options.environment`

**可选** `Enum`。可能会 `production` 或者说 `test`。用于定义要发送参数的服务器。 如果不设定,客户端将使用主机名来最好地猜测发送度量衡的位置. 如果您的主机名已经 `test`, (中文(简体) ), `staging` 或者说 `local`,将使用测试服务器。 否则,我们将发送 度量衡生产。 如果这不方便您使用,请使用 `environment` 选项来推翻这种行为.

```js
new MetricsClient({ environment: 'production' });
```

#### `options.batchSize`

**可选** `number`。这是在客户端发送到服务器之前,在队列中可以累积多少个事件。 最小大小是20个事件,如果尝试设置 `batchSize` 至更低的数字,将忽略,选项将设定为20个事件.

#### `options.sendIntervalSeconds`

**可选** `number`。这是客户端在发送批次事件之前等待的秒数。 最少的等待时间是10秒 如果你试图设置 `sendIntervalSeconds` 到一个更低的数字,它将被忽略,客户端将使用10秒.

```js
new MetricsClient({ sendIntervalSeconds: 15 });
```

如果网络是片面的或没有,我们正在增加等待时间,以避免一次重复过多。 最大间隔设定为2分钟,所以您应当设定 `sendIntervalSeconds` 不到两分钟.

> \[注\] 如果该批事件达到最大规模,则在到达发送IntervalSeconds结束之前发送事件.

#### `options.queue`

**可选** `Queue`。在发送前将事件分批进行排队。 默认情况下,客户端将使用 `InMemoryQueue`。可以使用 `IndexedDBQueue` ,它将将您的事件存储在索引DB数据库中,而不是内存数组(默认使用) `InMemoryQueue`) (中文(简体) ). 您也可以提供自己的队列执行( 只要它能扩展基础) `Queue` ) (中文(简体) ).

```js
// Default usage:
import { MetricsClient } from '@dotcom-reliability-kit/client-metrics-web';
new MetricsClient();

// Use InMemoryQueue with some custom settings:
import { InMemoryQueue, MetricsClient } from '@dotcom-reliability-kit/client-metrics-web';

const myQueue = new InMemoryQueue({ capacity: 11 });
new MetricsClient({ queue: myQueue });

// Use IndexedDB Queue:
import { InMemoryQueue, MetricsClient } from '@dotcom-reliability-kit/client-metrics-web';

const myIndexedDBQueue = new IndexedDBQueue({ capacity: 1_000_000, key: 'client-metrics-your-system' })
new MetricsClient({ queue: myIndexedDBQueue });
```

##### 队列接口

队列类定义了所有队列执行必须遵循的合同.

```js
import { Queue } from '@dotcom-reliability-kit/client-metrics-web';

new Queue({ capacity: 11 })
```

###### 选项

**能力** (数目,可选): 队列所能持有的最大项数 。 默认为一万.

> \[注\] 1万个事件的选择根据以下计算: 1 我们希望这批事件最多10MB 一个重事件大约为750字节.

###### 所需方法

子类必须执行下列方法:

-   **添加(项目)**: 在队列中添加项目.
-   **降( 计数)**: 将队列中最老的项目丢出。 默认为 1.
-   **拉( 计数)**: 删除并返回第一个计数项.
-   **顺序( 项目)**:在队列开始时放回项目.
-   **大小 ()**: 队列中的当前项目数.
-   **(提高)**: 最大队列容量(在基类中执行).

> \[注\] 方法是同索引DBQuee相容的.

## 使用量(共享图书馆)

如果你想从另一个系统共享的库中记录操作量度,我们建议 **没有** 安装此模块作为依赖。 相反,你应该只依靠 [基于事件的 API](https://npmcn.com/package/%40dotcom-reliability-kit/client-metrics-web/#readme-event-based-api)。 。 。 .

这确保:

-   我们最终不会有重复的全球活动处理者
-   安装您的库的系统不需要注入测量客户端并管理实例
-   我们最终不会使用不同的不兼容版本的测量客户端(依赖地狱)的系统和库

> \[尖叫声\] 狦 _需求_ 以依赖方式安装模块(因为您不想依赖其他团队在其系统中安装模块,或者您的工作被非CP系统所使用),可以直接安装模块并进行即时处理. 但你需要确保:
> 
> -   您将禁用 [基于事件的 API](https://npmcn.com/package/%40dotcom-reliability-kit/client-metrics-web/#readme-event-based-api)设置 `enableEventApi` 在建筑师中作假。 否则,如果另一个软件包通过基于事件的 API 发送度量衡,你的系统和母系统都可能会处理同一事件,我们最终可能会有重复的度量衡.
> -   如果使用的话 `indexed-db-queue`,设置 `key` 识别您的系统( 例如 `client-metrics-comment`) (中文(简体) ). 否则, 您的实例可能与父系统共享相同的队列, 并可以覆盖其度量衡 .

## 用法(基础设施)

除了客户端,你还需要在 [客户端计量服务器](https://github.com/Financial-Times/cp-client-metrics-server/tree/main/config/namespace) 发送事件。 你们可以自己按照重案组的剧本来安排 这应该让你把日志送到斯普伦克 和量子送到云表观察 然后可以使用你的"云表"(Cloud Watch)的度量衡在格拉法纳创建出图表和警报.

## 测试

这个软件包使用Playwright在浏览器环境中测试客户端的测算排队和发送机制. 要在本地运行测试, 您需要在第一次使用前安装剧作家 :

```sh
npx playwright install
```

然后,你可以运行:

```sh
npm run test:playwright
```

或者说

```sh
npm run playwright
```

如果你不想每次都重建客户端的包.

如果测试有问题,你可以访问html页面. 从 `/packages/client-metrics-web`,运行 :

```sh
// This step generates a bundle from the client-metrics code to be able to use it in a local html
npm run build:bundle

// Starts the server
npm start
```

然后转到http://127.0.0.1:8080/test/end-to-end/fixtures/. 您可以访问 [指数](https://npmcn.com/packages/client-metrics-web/test/end-to-end/fixtures/index.html) 调试.

## 移动

咨询 [移徙指南](https://npmcn.com/package/%40dotcom-reliability-kit/client-metrics-web/docs/migration.md) 如果你想要迁移到这个软件包的后期主要版本.

## 捐款

见 [可靠性工具包中心贡献指南](https://github.com/Financial-Times/dotcom-reliability-kit/blob/main/docs/contributing.md)。 。 。 .

## 许可证

凭 [麻省理工学院](https://github.com/Financial-Times/dotcom-reliability-kit/blob/main/LICENSE) 执照.  
版权:"2025","金融时报"有限公司.

## 常见问题

### @dotcom-reliability-kit/client-metrics-web 是什么？

从网络向客户端计量服务器发送操作计量的客户端

### 如何安装 @dotcom-reliability-kit/client-metrics-web？

在项目目录运行 npm install @dotcom-reliability-kit/client-metrics-web，或使用 pnpm add / yarn add / bun add。

### @dotcom-reliability-kit/client-metrics-web 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @dotcom-reliability-kit/client-metrics-web 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @dotcom-reliability-kit/client-metrics-web 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js ^22\.12 \|\| ^24 \|\| ^26。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @dotcom-reliability-kit/client-metrics-web 可以商用吗？

@dotcom-reliability-kit/client-metrics-web 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @dotcom-reliability-kit/client-metrics-web 的下载量有多少？

根据 npm 官方下载统计，@dotcom-reliability-kit/client-metrics-web 在 2026/10/13 – 2026/11/11 这 30 天内被下载 2,600 次，日均约 87 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @dotcom-reliability-kit/client-metrics-web 还在维护吗？

最新版本 2\.1\.2 发布于 2026/08/20（2 个月前）；至今共发布 13 个版本，其中过去 12 个月发布了 8 个；首次发布于 2025/04/09。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。