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

从浏览器发送操作度量事件到 客户产品客户端计量服务器。本模块是 FT.com 可靠性工具包。 。 。 .

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

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

• 使用量(系统)
  • MetricsClient
    • client.recordEvent()
    • client.enable()
    • client.disable()
    • client.isEnabled
    • client.isAvailable
  • 基于事件的 API
  • 处理错误
  • 配置选项
    • options.systemCode
    • options.systemVersion
    • options.environment
    • options.batchSize
    • options.sendIntervalSeconds
    • options.queue
      • 队列接口
        • 选项
        • 所需方法
• 使用量(共享图书馆)
• 用法(基础设施)
• 测试
• 移动
• 捐款
• 许可证

使用量(系统)

想要从客户端发送度量衡的系统应当导入并构建度量衡客户端,作为其客户端-JavaScript的一部分. 如果你正在写代码 共享到多个系统 不导入和构建计量客户端。见 共享图书馆使用指南。 。 。 .

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

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

在客户端代码中包含 :

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

[TIP] 如果您使用此软件包并带有 TypeScript , 我们建议您使用以下设置: tsconfig.json 避免类型错误的文件 :

{
    "esModuleInterop": true,
    "module": "nodenext",
    "moduleResolution": "nodenext"
}

MetricsClient

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

赛事加一批. 当批量达到最大容量,默认为20时,客户端将事件发送到服务器. 如果达不到最大容量,客户端每10秒发送一次事件. 这个 sendIntervalSeconds 是可配置的选项(参见 options.sendIntervalSeconds) (中文(简体) ). 如果批次没有增加事件,则不发送.

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

这门课只能建一次 否则你就会发出重复的度量衡. 在加载页面时,您应该尽早构建度量衡客户端 。 所需选项见 配置选项。 。 。 .

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

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

• ft.clientMetric - 根据事件发现的细节记录一个自定义的衡量标准(见下文文件(中文(简体) )

client.recordEvent()

发送计量事件 :

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()

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

client.enable();

client.disable()

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

client.disable();

client.isEnabled

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

client.isAvailable

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

基于事件的 API

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

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

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

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

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 对象可以拥有任意数量的属性。 这些属性将被提取入最终的度量衡事件并被发送到客户端度量衡服务器. 例如:

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

// is equivalent to:

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

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

new MetricsClient({ enableEventApi: false });

看为什么你会禁用它 使用量(共享图书馆)。 。 。 .

处理错误

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

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

配置选项

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

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

options.systemCode

需求 String编辑 毕斯 操作系统代码 你发送的度量衡.

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

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

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

options.systemVersion

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

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

options.environment

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

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

options.batchSize

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

options.sendIntervalSeconds

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

new MetricsClient({ sendIntervalSeconds: 15 });

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

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

options.queue

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

// 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 });

队列接口

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

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

new Queue({ capacity: 11 })

选项

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

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

所需方法

子类必须执行下列方法:

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

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

使用量(共享图书馆)

如果你想从另一个系统共享的库中记录操作量度,我们建议 没有 安装此模块作为依赖。 相反,你应该只依靠 基于事件的 API。 。 。 .

这确保:

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

[尖叫声] 狦 需求 以依赖方式安装模块(因为您不想依赖其他团队在其系统中安装模块,或者您的工作被非CP系统所使用),可以直接安装模块并进行即时处理. 但你需要确保:

• 您将禁用 基于事件的 API设置 enableEventApi 在建筑师中作假。 否则,如果另一个软件包通过基于事件的 API 发送度量衡,你的系统和母系统都可能会处理同一事件,我们最终可能会有重复的度量衡.
• 如果使用的话 indexed-db-queue,设置 key 识别您的系统( 例如 client-metrics-comment) (中文(简体) ). 否则, 您的实例可能与父系统共享相同的队列, 并可以覆盖其度量衡 .

用法(基础设施)

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

测试

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

npx playwright install

然后,你可以运行:

npm run test:playwright

或者说

npm run playwright

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

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

// 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/. 您可以访问 指数 调试.

移动

咨询 移徙指南 如果你想要迁移到这个软件包的后期主要版本.

捐款

见 可靠性工具包中心贡献指南。 。 。 .

许可证

凭 麻省理工学院 执照.
版权:"2025","金融时报"有限公司.