# @autotelic/fastify-opentelemetry 中文文档 规范地址：https://npmcn.com/package/%40autotelic/fastify-opentelemetry/ 版本：0\.23\.0 npm 元数据更新时间：2025-11-09T21:13:42.428Z 中文译文更新时间：2026-11-07T07:11:40.518Z 软件包许可：MIT 本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。 原始 npm 页面：https://www.npmjs.com/package/%40autotelic/fastify-opentelemetry 原文对照：https://npmcn.com/package/%40autotelic/fastify-opentelemetry/?lang=original 项目主页：https://github.com/autotelic/fastify-opentelemetry#readme 源码仓库：https://github.com/autotelic/fastify-opentelemetry ## 关键信息（来自 npm 元数据） - 包体积（解压后）：19.4 kB，5 个文件 - 模块格式：CommonJS - TypeScript 类型：包内自带 - Node.js 要求：\>=18 - 运行依赖：1 个 - peer 依赖：@opentelemetry/api ^1\.0\.0 - 首次发布：2020-07-02T22:54:45.912Z - 最新版本发布：2025-11-09T21:13:42.204Z - 近 30 天下载量：57444（2026-10-07 至 2026-11-05，npm 官方下载统计） - 已发布版本数：32（近 12 个月 1 个） ## 中文简介 OpenTeleometry 的快取插件 ## 安装 ```sh npm install @autotelic/fastify-opentelemetry ``` 也可以使用：`pnpm add @autotelic/fastify-opentelemetry`、`yarn add @autotelic/fastify-opentelemetry`、`bun add @autotelic/fastify-opentelemetry` ## README # 速成 OpenTelection A 类 [快捷化](https://fastify.io/) 使用该插件的插件 [打开数位 API](https://github.com/open-telemetry/opentelemetry-js/tree/main/api) 提供请求追踪. ## 使用量 ```sh npm i @autotelic/fastify-opentelemetry ``` ### 实例 #### 插件使用 ```js // index.js // Load your OpenTelemetry/API configuration first. Now the configured SDK will be available // to fastify-opentelemetry. (See the example configuration below.) require('./openTelemetryConfig') const openTelemetryPlugin = require('@autotelic/fastify-opentelemetry') const fastify = require('fastify')(); (async () => { await fastify.register(openTelemetryPlugin, { wrapRoutes: true }) fastify.get('/', async function (request, reply) { const { activeSpan, tracer, // context, // extract, // inject, } = request.openTelemetry() // Spans started in a wrapped route will automatically be children of the activeSpan. const childSpan = tracer.startSpan(`${activeSpan.name} - child process`) // doSomeWork() childSpan.end() return 'OK' }) fastify.listen(3000, (err, address) => { if (err) { fastify.log.error(err) process.exit(1) } }) })() ``` #### 打开远程 API 配置 ```js // openTelemetryConfig.js const { BatchSpanProcessor, ConsoleSpanExporter, TraceIdRatioBasedSampler } = require('@opentelemetry/sdk-trace-base') const { NodeTracerProvider } = require('@opentelemetry/sdk-trace-node') // Configure a tracer provider. const provider = new NodeTracerProvider({ sampler: new TraceIdRatioBasedSampler(0.5) }) // Add a span exporter. provider.addSpanProcessor( new BatchSpanProcessor(new ConsoleSpanExporter()) ) // Register a global tracer provider. provider.register() // Note: the above is just a basic example. fastify-opentelemetry is compatible with any // @opentelemetry/api configuration. ``` 见 [实例](https://npmcn.com/package/%40autotelic/fastify-opentelemetry/example/index.js) 对于一个实例应用。 要在本地运行示例应用程序, 首先复制此 repo , 然后 `npm i` 运行 : ```sh npm run dev ``` ## API 密码 ### 配置 此插件将所有跟踪器配置留给 [打开数位 API](https://github.com/open-telemetry/opentelemetry-js/tree/main/api)追踪和传播方法分别来自全球追踪提供者和全球传播者。 这使得插件本身的配置最小化. 插件接受以下配置属性 : - **`exposeApi` 数字 : `boolean`** - 用来防止插件装饰请求. 默认情况下,请求将被装饰(即默认为 `true`) (中文(简体) ). - **`formatSpanName` 数字 : `(FastifyRequest) => string`** - 跨度名称的自定义物质。 默认格式是 `` `${req.method} ${req.routeOptions.url}` ``。 。 。 . - **`formatSpanAttributes` 数字 : `object`** - 包含跨度属性的格式函数. _属性_数字 : - **`request`数字 : `(FastifyRequest) => object`** - 根据请求,返回的对象将被添加到当前跨度的属性中。 默认请求属性为: ```js { 'req.method': request.raw.method, 'req.url': request.raw.url } ``` - **`reply`数字 : `(FastifyReply) => object`** - 答复时,返回对象将被添加到当前跨度的属性中。 默认回复属性为: ```js { 'reply.statusCode': reply.statusCode } ``` - **`error`数字 : `(Error) => object`** - 在出错时,返回的对象将被添加到当前跨度的属性中。 默认错误属性为: ```js { 'error.name': error.name, 'error.message': error.message, 'error.stack': error.stack } ``` - **`wrapRoutes` 数字 : `boolean | string[]`** - 当 `true`,所有路由处理器将使用等于 `request.openTelemetry().context`。并接受包含所有应当被包裹的路由路径的阵列。 可选 - 默认已禁用 . - 路径必须有一个线索 `/` 不得随从 `/` 联合国. `'/my/exact/route/path'`) (中文(简体) ). - 环绕一个路由允许在路由处理器范围内创建的任何跨度自动成为当前请求的子 `activeSpan`。这包括自动创建的跨度 [开元仪表](https://github.com/open-telemetry/opentelemetry-js#node-instrumentations)。 。 。 . - 全球背景管理器(例如:. [`AsyncHooksContextManager`](https://github.com/open-telemetry/opentelemetry-js/tree/main/packages/opentelemetry-context-async-hooks))需要为路由处理器提供主动上下文. - **`ignoreRoutes` 数字 : `string[] | (path: string, method: string) => boolean`** - 配置 [钩子](https://npmcn.com/package/%40autotelic/fastify-opentelemetry/#readme-hooks) 由此插件添加以忽略某些路由路径(即该路由没有自动跟踪). 胜过 `wrapRoutes`。 。 。 . - 可以是一系列路由路径(遵循与 `wrapRoutes`) (中文(简体) ). - 可以是接收路由路径和方法并返回布尔值的函数( 返回) `true` 以忽略方式处理)。 例如, 禁用跟踪 `OPTIONS` 路径 : ```js fastify.register(openTelemetryPlugin, { ignoreRoutes: (path, method) => method === 'OPTIONS' }) ``` - 被忽略的路线仍然可以进入 `request.openTelemetry`不过 `activeSpan` 将会是 `undefined`。 。 。 . - **`propagateToReply` 数字 : `boolean`** - 当 `true`中,当前间距上下文将使用您的已注册的传播器注入回复信头。 默认为 `false`。 。 。 . - **`spanOptions` 数字 : `SpanOptions | (FastifyRequest) => SpanOptions`** - 说吧 [`SpanOptions`](https://open-telemetry.github.io/opentelemetry-js/interfaces/_opentelemetry_api.SpanOptions.html) 返回函数 [`SpanOptions`](https://open-telemetry.github.io/opentelemetry-js/interfaces/_opentelemetry_api.SpanOptions.html)这些将被传递到 `tracer.startSpan` 每个请求。 默认为 `{ kind: 1 }`。 。 。 . ### 请求装饰器 此插件以一个 `openTelemetry` 函数返回具有下列属性的对象: - **`context`数字 : [`Context`](https://open-telemetry.github.io/opentelemetry-js/interfaces/_opentelemetry_api.Context.html)** - 包含活动段段的上下文以及提取出的任何上下文. - **`activeSpan`数字 : [`Span`](https://open-telemetry.github.io/opentelemetry-js/interfaces/_opentelemetry_api.Span.html)** - 活动跨度(可通过以下途径获得): `context`我们只是提供一条捷径. - **`extract`数字 : [`Propagation.extract`](https://open-telemetry.github.io/opentelemetry-js/classes/_opentelemetry_api.PropagationAPI.html#extract)** - 包装传播API的取出方法,并作为当前请求的背景通过 `context` 参数。 这将返回一个新的上下文, 并将 **没有** 影响请求的跟踪上下文。 接受下列论点: - **`carrier`数字 : `object`** - 包含要取出的内容的对象. - **`getter`数字 : [`TextMapGetter`](https://open-telemetry.github.io/opentelemetry-js/interfaces/_opentelemetry_api.TextMapGetter.html)** - 包含 `get` 财务报告和审定财务报表 `keys` 方法。 。 。 用于从载体中提取值. OpenTeleometry 的默认值 [`defaultTextMapGetter`](https://open-telemetry.github.io/opentelemetry-js/modules/_opentelemetry_api.html#defaultTextMapGetter)。 。 。 . - **`inject`数字 : [`Propagation.inject`](https://open-telemetry.github.io/opentelemetry-js/classes/_opentelemetry_api.PropagationAPI.html#inject)** - 包装传播API的注射方法,并在当前请求的上下文中通过 `context` 参数。 接受下列论点: - **`carrier`数字 : `object`** - 上下文将注入对象. - **`setter`数字 : [`TextMapSetter`](https://open-telemetry.github.io/opentelemetry-js/interfaces/_opentelemetry_api.TextMapSetter.html)** - 包含 `set` 方法。 用来给载体注入值. OpenTeleometry 的默认值 [`defaultTextMapSetter`](https://open-telemetry.github.io/opentelemetry-js/modules/_opentelemetry_api.html#defaultTextMapSetter)。 。 。 . - **`tracer`数字 : [`Tracer`](https://open-telemetry.github.io/opentelemetry-js/interfaces/_opentelemetry_api.Tracer.html)** - 插件创建并使用的追踪器. ### 钩子 此插件注册以下快取钩: - `onRequest`: 开始跨度. - `onReply`:停止横跨. - `onError`: 添加错误信息以覆盖属性. - `onRoute`: 仅在 `wrapRoutes` 已启用. - `onSend`: 仅在 `propagateToReply` 已启用. ### OpenTeleometry 兼容性 作为 [打开数位 API](https://github.com/open-telemetry/opentelemetry-js/tree/main/api#version-compatibility) 使用a 变量在 `global` 对象存储全局 API,需要注意确保所有模块兼容. 每个版本的OpenTeleometry API将要求专门发布自来自来自来自来自来自去自来自去自来自去自来自去自去自来自去自去自去自来自来自去自来自去自来自去自来自来自来自去自去自来自来自来自去自来自来自来自来自来自来自去自来自来自来自来自来自来自来自去自来自来自来自来自来自来自来自来自来自自自来自来自自来自来自来自来自来自来自来自自来自来自自来自自自来自来自来自来自来自来自来自来自来自来自来自来自来自来自来自来自来自来自来自来自来自来自来自来自来自来自来自来自来自来自来自来自来自来自来自来自来自来自来自来自来自来自来自来自来自来自. | OpenTeleometry API 版本 : 开源软件 | 最小快取 OpenTelection 版本 | | --- | --- | | `@opentelemetry/api@1.0.0` | `@autotelic/fastify-opentelemetry@0.14.0` | | `@opentelemetry/api@0.20.0` | `@autotelic/fastify-opentelemetry@0.13.0` | | `@opentelemetry/api@1.0.0-rc.0` | `@autotelic/fastify-opentelemetry@0.12.0` | | `@opentelemetry/api@0.18.0` | `@autotelic/fastify-opentelemetry@0.10.0` | | `@opentelemetry/api@0.17.0` | `@autotelic/fastify-opentelemetry@0.9.0` | | `@opentelemetry/api@0.15.0` | `@autotelic/fastify-opentelemetry@0.8.0` | | `@opentelemetry/api@0.14.0` | `@autotelic/fastify-opentelemetry@0.7.0` | | `@opentelemetry/api@0.13.0` | `@autotelic/fastify-opentelemetry@0.5.0` | | `@opentelemetry/api@0.12.0` | `@autotelic/fastify-opentelemetry@0.4.0` | | `@opentelemetry/api@0.10.0` | `@autotelic/fastify-opentelemetry@0.2.4` | | `@opentelemetry/api@0.9.0` | `@autotelic/fastify-opentelemetry@0.1.1` | ## 常见问题 ### @autotelic/fastify-opentelemetry 是什么？ OpenTeleometry 的快取插件 ### 如何安装 @autotelic/fastify-opentelemetry？ 在项目目录运行 npm install @autotelic/fastify-opentelemetry，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：@opentelemetry/api（^1\.0\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。 ### @autotelic/fastify-opentelemetry 支持 TypeScript 吗？ 支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。 ### @autotelic/fastify-opentelemetry 支持 ESM 还是 CommonJS？ 以 CommonJS 形式发布，可以直接 require\(\)；在 ES Module 项目中也可以用 import 引入（Node\.js 会把 module\.exports 作为默认导出）。 ### @autotelic/fastify-opentelemetry 需要什么版本的 Node\.js？ package\.json 的 engines 字段要求 Node\.js \>=18。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。 ### @autotelic/fastify-opentelemetry 可以商用吗？ @autotelic/fastify-opentelemetry 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。 ### @autotelic/fastify-opentelemetry 的下载量有多少？ 根据 npm 官方下载统计，@autotelic/fastify-opentelemetry 在 2026/10/07 – 2026/11/05 这 30 天内被下载 57,444 次，日均约 1,915 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。 ### @autotelic/fastify-opentelemetry 还在维护吗？ 最新版本 0\.23\.0 发布于 2025/11/10（11 个月前）；至今共发布 32 个版本，其中过去 12 个月发布了 1 个；首次发布于 2020/07/03。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。