# @flarelabs-net/workers-observability-utils 中文文档 规范地址：https://npmcn.com/package/%40flarelabs-net/workers-observability-utils/ 版本：0\.4\.0 npm 元数据更新时间：2026-05-29T11:22:11.183Z 中文译文更新时间：2026-11-14T21:31:55.213Z 软件包许可：ISC 本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。 原始 npm 页面：https://www.npmjs.com/package/%40flarelabs-net/workers-observability-utils 原文对照：https://npmcn.com/package/%40flarelabs-net/workers-observability-utils/?lang=original ## 关键信息（来自 npm 元数据） - 包体积（解压后）：47.6 kB，13 个文件 - 模块格式：ES Module - TypeScript 类型：包内自带 - 运行依赖：2 个 - 首次发布：2025-05-29T18:03:23.382Z - 最新版本发布：2026-05-29T11:22:11.027Z - 近 30 天下载量：96346（2026-10-15 至 2026-11-13，npm 官方下载统计） - 已发布版本数：9（近 12 个月 2 个） ## 中文简介 Cloudflare工人的图和计量工具汇编 ## 安装 ```sh npm install @flarelabs-net/workers-observability-utils ``` 也可以使用：`pnpm add @flarelabs-net/workers-observability-utils`、`yarn add @flarelabs-net/workers-observability-utils`、`bun add @flarelabs-net/workers-observability-utils` ## README # 工人可观察性 用于从Cloudflare工人那里捕捉和输出度量衡和日志的轻量级包. ## 特征 - 通过可配置的尾矿工人向多汇(Datadog、工人分析引擎、OpenTeleometry)集中出口 - 全面的衡量支持: `COUNT`, (中文(简体) ), `GAUGE`,以及 `HISTOGRAM` 自动汇总和标记 - 土著 `console.log()` 支持 - 与现有日志合作, 无需更改代码 ## 基本用途 ### 在员工中设置计量 主要工人将收集衡量标准并通过诊断渠道公布。 这个 `metrics` 对象提供了不同类型度量衡的记录方法: ```typescript import { metrics } from '@flarelabs-net/workers-observability-utils'; export default { async fetch(request, env, ctx) { // Record count metric with tags metrics.count('worker.request', 1, { method: request.method, }); // Record gauge metric metrics.gauge('worker.connections.active', 42); // Record histogram metric for response time. // Note: Timers are not totally accurate in cloudflare worker environments // but this can give an indication of relative performance const startTime = Date.now(); const response = await processRequest(); const responseTime = Date.now() - startTime; metrics.histogram('worker.response_time', responseTime, { percentiles: [0.5, 0.95, 0.99], aggregates: ['avg', 'max'] }); return response; }, }; ``` ### 计量类型 这个库支持三种计量标准: 1. **库恩特** - 事件总数。 可以增减. (例如请求计数,错误计数) ```typescript metrics.count('worker.request', 1, { status: '200' }); ``` 2. **乔治** - 时间点测量(例如内存使用、连接计数) ```typescript metrics.gauge('worker.memory_usage', memoryUsage, { region: 'earth' }); ``` 3. **中国** - 随时间推移的数值分布,统计汇总 ```typescript metrics.histogram('worker.response_time', responseTimeMs, { percentiles: [0.5, 0.95, 0.99], // p50, p95, and p99 percentiles aggregates: ['avg', 'max', 'min', 'sum', 'count'] }, { endpoint: '/api' }); ``` 直方图量度自动生成多个衍生量度 : - 百分率(测量): `worker.cpu_time.p50`, (中文(简体) ), `worker.cpu_time.p95`等 (中文(简体) ). - 合计数 : `worker.cpu_time.avg`, (中文(简体) ), `worker.cpu_time.max`等 (中文(简体) ). ### 标记 所有度量衡都支持标记,它们是帮助分类和过滤度量的密钥值对: ```typescript metrics.count('worker.request', 1, { method: 'GET', path: '/api', status: '200' }); ``` ### 在工作人中设置日志 此库自动抓取全部 `console.log()` 您的员工打来的电话 - 不需要更改代码 ! 您的现有采伐将通过"尾矿工人"进行收集和出口. ```typescript export default { async fetch(request, env, ctx) { // These logs will be automatically captured and exported console.log('Processing request', { method: request.method, url: request.url }); console.error('Something went wrong', { error: 'details' }); console.warn('This is a warning'); return new Response('Hello World'); }, }; ``` ### 日志辛克 目前支持的日志目的地 : - **打开几何** - 将日志转发给任何可兼容的 OpenTeleometry 收藏器 ## 设置尾线工人 为了高效地向外部供应商输出计量标准,您应当设置专门的"尾矿工人". 这个架构允许您的主要工人专注于处理请求,而"尾矿工人"则处理计量收集和导出. 更多信息,请参见 [云花纹工人文件](https://developers.cloudflare.com/workers/observability/logs/tail-workers/)。 。 。 . ### 多个辛克 通过这个库,您可以同时向多个目的地发送度量衡. TailExporter支持一系列的公制汇,每个汇都得到相同的公制汇数据. 目前得到支持的汇包括: - **数据犬** - 向Datadog输出用于可视化和报警的衡量标准 - **工人分析引擎** - Cloudflare's Analytics engine中存储用于自定义查询和分析的度量衡 - Warning:每个请求给工人分析引擎的默认写作数量为25. - **奥特计量器** - 将你的量子发送给任何可兼容的 OpenTeleometry 收藏器 在使用多汇时,将同时向所有配置的汇发送指标。 如果一个沉没,其他的仍然会得到测量值. ### 尾矿工人配置 1. 创建处理尾端事件的新工作者 : ```typescript // tail-worker/src/index.ts import { TailExporter, DatadogMetricSink, WorkersAnalyticsEngineSink, OtelMetricSink, OtelLogSink } from '@flarelabs-net/workers-observability-utils'; export default new TailExporter({ metrics: { sinks: [ new DatadogMetricSink({ site: 'us3.datadoghq.com', // API key can be provided here or via environment variables // apiKey: 'your-datadog-api-key' }), new WorkersAnalyticsEngineSink({ datasetBinding: env.ANALYTICS_ENGINE_DATASET }), new OtelMetricSink({ url: 'https://my-otel-exporter.io', headers: { }, }), ], // Optional default metrics to collect automatically defaultMetrics: { cpuTime: true, // default: true - collects worker.cpu_time as a GAUGE wallTime: true, // default: true - collects worker.wall_time as a GAUGE workersInvocation: true, // default: true - collects worker.invocation as a COUNT }, // When using Workers Analytics Engine, a value of 20 or less is recommended due to soft limits maxBufferSize: 20, // Maximum duration in seconds to buffer before flushing (default: 5, max: 30) maxBufferDuration: 5 }, logs: { sinks: [ new OtelLogSink({ url: 'https://my-otel-exporter.io', headers: { }, defaultLogsEnabled: { invocationLog: true; }; }), ], maxBufferSize: 20, maxBufferDuration: 5 } }); ``` ### 默认日志 尾端导出器可以通过每根汇发送一小组内置登录 `defaultLogsEnabled` 选项(用于汇,例如 `OtelLogSink`) (中文(简体) ). 最常见的默认日志是: - `invocationLog` (默认 : `true`:发布每集引用日志记录,包含关于引用的元数据(书写名称,执行模式,结果,版本Id),计时信息和任何全局标记. 这补充了自动 `console` 用于追踪、审计和将衡量标准与个人援引联系起来. 要禁用汇的引用日志, 设置 : ```ts new OtelLogSink({ ... defaultLogsEnabled: { invocationLog: false; }; }), ``` 您可以在构建汇时启用或禁用每个汇的默认日志(参见 `OtelLogSink` (见上文实例). 2. 设置 Datadog API 键 : ```bash # Using wrangler secrets wrangler secret put DD_API_KEY # Or DATADOG_API_KEY is also supported ``` 2. 配置您的工人 : ```jsonc // wrangler.jsonc for the Emitting Worker { "name": "my-worker", // Required: Enable the tail_consumers configuration "tail_consumers": [ { "service": "name-of-tail-worker", } ] } ``` ### 环境变量和约束 尾矿工人支持下列环境变量和约束: #### 数据犬 - `DD_API_KEY`: 您的数据犬 API 密钥 - `DD_SITE`: datadog url 即 us3. datadoghq.com 数据犬url : #### 工人分析引擎 - 需要将分析引擎数据集装入您的 wrangler.jsonc 中: ```jsonc { "analytics_engine_datasets": [ { "binding": "ANALYTICS_ENGINE_DATASET", "dataset": "your-dataset-name" } ] } ``` **说明**:工人分析引擎每引用一个软限为25个字,所以建议在使用这个水槽时,将您的最大缓冲度保持在20或更低. ### 默认计量 尾线工人可以自动收集以下的度量衡,而无需在您的主要工人中安装任何仪器: 1. **CPU 时间** (单位:千美元)`worker.cpu_time`\- 测量工人用毫秒计的CPU时间的GAUGE计量标准 2. **墙壁时间** (单位:千美元)`worker.wall_time`以毫秒计算工人总执行时间的GAUGE指标 3. **利用工人** (单位:千美元)`worker.invocation`\- 参照每个工人增加1倍的COUNT指标 这些度量衡是用同样的全局标记来收集的,这些标记应用于您的自定义度量衡(scriptName, executionModel, result, versionId). 您可以启用或禁用 TailExporter 配置中的这些默认度量 : ```typescript export default new TailExporter({ metrics: { sinks: [...], defaultMetrics: { cpuTime: true, // default: true wallTime: true, // default: true workersInvocation: true, // default: true } } }); ``` ## 常见问题 ### @flarelabs-net/workers-observability-utils 是什么？ Cloudflare工人的图和计量工具汇编 ### 如何安装 @flarelabs-net/workers-observability-utils？ 在项目目录运行 npm install @flarelabs-net/workers-observability-utils，或使用 pnpm add / yarn add / bun add。 ### @flarelabs-net/workers-observability-utils 支持 TypeScript 吗？ 支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。 ### @flarelabs-net/workers-observability-utils 支持 ESM 还是 CommonJS？ 以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。 ### @flarelabs-net/workers-observability-utils 可以商用吗？ @flarelabs-net/workers-observability-utils 使用 ISC 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。 ### @flarelabs-net/workers-observability-utils 的下载量有多少？ 根据 npm 官方下载统计，@flarelabs-net/workers-observability-utils 在 2026/10/15 – 2026/11/13 这 30 天内被下载 96,346 次，日均约 3,212 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。 ### @flarelabs-net/workers-observability-utils 还在维护吗？ 最新版本 0\.4\.0 发布于 2026/05/29（5 个月前）；至今共发布 9 个版本，其中过去 12 个月发布了 2 个；首次发布于 2025/05/30。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。