# @absolutejs/telemetry 中文文档规范地址：https://npmcn.com/package/%40absolutejs/telemetry/ 版本：0\.3\.1 npm 元数据更新时间：2026-08-07T05:41:40.159Z 中文译文更新时间：2026-11-06T05:57:15.854Z 软件包许可：Apache-2\.0 本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。原始 npm 页面：https://www.npmjs.com/package/%40absolutejs/telemetry 原文对照：https://npmcn.com/package/%40absolutejs/telemetry/?lang=original 项目主页：https://github.com/absolutejs/telemetry 源码仓库：https://github.com/absolutejs/telemetry ## 关键信息（来自 npm 元数据） - 包体积（解压后）：444 kB，23 个文件 - 模块格式：ES Module - TypeScript 类型：包内自带 - 运行依赖：1 个 - peer 依赖：drizzle-orm \>=1\.0\.0-rc\.4 \<2 - 首次发布：2026-05-30T18:31:12.654Z - 最新版本发布：2026-08-07T05:41:40.017Z - 近 30 天下载量：4617（2026-10-05 至 2026-11-03，npm 官方下载统计） - 已发布版本数：9（近 12 个月 9 个） ## 中文简介 Tiny为绝对JS生态系统共享了OpenTeleometry底物. 类型复制@opetelemetry/api's Tracer/Span外形,船尾执行+跟踪OrNoop帮助器+0-dep OTLP-HTTP-JSON横跨出口国(/otlp-http subpath),并标出ABS ATTRS ## 安装 ```sh npm install @absolutejs/telemetry ``` 也可以使用：`pnpm add @absolutejs/telemetry`、`yarn add @absolutejs/telemetry`、`bun add @absolutejs/telemetry` ## README # @ 绝对js/ 遥测 Tiny 共享绝对 JS 基底的 OpenTelemetry 基底软件包. 该公司还派遣了一名中立供应商代理观察员 `@absolutejs/telemetry/agent`。通过 `createAgentTelemetryObserver(tracer)` 直接为 `@absolutejs/agent-runtime`是因为 `onEvent` 回调关联运行,签名的发现身份,步骤,效果,预算,以及失败. 提示和效果有效载荷不包括在内,演员身份识别默认为私人身份. **文档 :** [绝对js.com/文档/遥测包](https://absolutejs.com/documentation/telemetry-package) **何等为相.** 类型复制的OTel地表 + noop 执行 + 页:1 `tracerOrNoop()` 帮助 + `ABS_ATTRS` 语义公约 LOC,零运行时间道克. **它能解决什么.** 深度研究审计的G2差距:底线软件包(运行时间/同步/队列/路由器/秘密/速率限制) -jsc)需要OTel的跨度来进行"从边缘到跑步的一丝痕迹" ======== ====================================================================================================================================================================================================================================================== 没有共同的底物, 每个软件包都写自己的同位素/无倒置锅炉板并选择自己的属性名称. **如何是接线.** 每个底盘包厂都得买选项 `tracerProvider?: TracerProvider`它在内部呼吁: ```ts const tracer = tracerOrNoop(options.tracerProvider, '@absolutejs/'); ``` 和用途 `tracer.startActiveSpan(name, options, fn)` 在热道上. 当用户通过时 `@opentelemetry/api` `TracerProvider`真实跨度流经。当它们不执行时,新追踪器会执行使用零分配的回调. ## 安装 ```sh bun add @absolutejs/telemetry # Optional — only if you want real OTel spans: bun add @opentelemetry/api @opentelemetry/sdk-node ``` 包裹有 **没有** 运行时间依赖。它不是对等的 `@opentelemetry/api` ——其类型结构相容,所以真实的 OTel `TracerProvider` 满足此软件包预期的形状 . ## 持久跟踪存储 `@absolutejs/telemetry` 拥有中性提供者 `TraceStore` 合同. `createTraceStoreSpanExporter()` 工程 OpenTeleometry SDK 跨入一个捆绑的安全可靠储存的形状并通过合同写成批次. 它会丢弃带有秘密属性的密钥, 剥去 URL 查询/ hash 值, 边框属性/事件/链接、删除请求/响应机构和数据库报表 ,默认情况下,支持应用程序特定属性允许列表,并保存纳米秒印作弦. `createFanoutSpanExporter()` 向多个出口商发送每批货物和报告部分失败,没有隐藏一个健康的目的地。这支持持久与可选 OTLP 收藏器并列的第一当事方存储,而不组合与任何一家供应商签订储存合同. 使用 `createMemoryTraceStore()` 测试。用于生产存储,导入 `createDrizzleTraceStore()` 财务报告和审定财务报表 `telemetryDrizzleSchema` 从 `@absolutejs/telemetry/drizzle`。导出表用于主机所有滴滴迁徙. 写作是专有的 `(trace_id, span_id)`; 仓库支持过滤的微量摘要、完整的微量检索、保存通过 `prune()`,集合存储统计,桶装出错/时间序列, 人均服务健康摘要和无父母/子女服务依赖图规定一个托管的可观察性供应商。记忆中的执行暴露了同样的 `TraceAnalyticsStore` 用于本地开发和测试的接口. ## 使用量 ### 作为底盘包的作者 ```ts import { tracerOrNoop, ABS_ATTRS, type TracerProvider } from '@absolutejs/telemetry'; export type MyPackageOptions = { // existing options... tracerProvider?: TracerProvider; }; export const createMyPackage = (options: MyPackageOptions) => { const tracer = tracerOrNoop(options.tracerProvider, '@absolutejs/my-package'); return { doWork: async (input: string) => { return tracer.startActiveSpan( 'my-package.doWork', { attributes: { [ABS_ATTRS.tenant]: input } }, async (span) => { try { const result = await actuallyDoWork(input); return result; } catch (error) { span.recordException(error); throw error; } finally { span.end(); } } ); }, }; }; ``` 或者用方便包装 `withSpan(tracer, name, options, fn)` 那个自动集 `status` + 键 `recordException` + 键 `end()` 通用软件案例. ### 做为消费的线条 ```ts import { NodeTracerProvider } from '@opentelemetry/sdk-node'; import { createMyPackage } from '@absolutejs/my-package'; const tracerProvider = new NodeTracerProvider({ /* exporter, sampler, etc */ }); tracerProvider.register(); const pkg = createMyPackage({ tracerProvider }); // Spans now flow through to your configured exporter. ``` ## API 密码 ### `tracerOrNoop(provider, name, version?)` 回返 `provider.getTracer(name, version)` 若为 `provider` 定义; 否则就是无线追踪器基底的峡谷切入点软件包. ### `withSpan(tracer, name, options, fn)` 编号 : `withSpanSync(...)` 在一个自动设置的跨度中, 将自动调取( 或同步) : - `status: OK` 关于成功 - `status: ERROR` + 键 `recordException(error)` 掷出 - `span.end()` 两种情况中的一种(`finally`(中文(简体) ) ```ts const result = await withSpan( tracer, 'sync.runMutation', { attributes: { [ABS_ATTRS.mutation]: 'createIssue' } }, async (span) => { span.setAttribute(ABS_ATTRS.mutationAttempt, 1); return await engine.runMutation('createIssue', args, ctx); } ); ``` ### `createNoopSpan()` 编号 : `createNoopTracer()` 编号 : `createNoopTracerProvider()` 单子用于测试 + 作为默认倒计时. ### `ABS_ATTRS` 标准属性名. 使用这些代替内线字符串文字因此交叉包件查询( e)`abs.tenant = "acme"`解决在一个过滤器 : ``` abs.tenant // tenant / shard key abs.shard.id // sync abs.engine.id abs.collection abs.mutation abs.mutation.attempt abs.subscription.id abs.batch.size abs.cluster.origin // queue abs.job.id abs.job.kind abs.job.attempt abs.job.max_attempts abs.worker.id // runtime abs.runtime.key abs.runtime.pid abs.runtime.port abs.runtime.exit_reason abs.runtime.readiness_ms // router abs.route.shard abs.route.decision // secrets abs.secret.name abs.secret.fingerprint // audit abs.audit.kind // handoff abs.handoff.correlation_id abs.handoff.operation abs.handoff.outcome abs.handoff.service abs.handoff.source abs.handoff.attempt abs.handoff.contradiction ``` 添加新属性是一个小突起; 将已有属性重命名为断开更改( 任何人查询其跨度商店时, 都会对旧名). ### 类型再出口 `Tracer`, (中文(简体) ), `Span`, (中文(简体) ), `TracerProvider`, (中文(简体) ), `SpanContext`, (中文(简体) ), `SpanStatus`, (中文(简体) ), `SpanStatusCode`, (中文(简体) ), `SpanKind`, (中文(简体) ), `SpanOptions`, (中文(简体) ), `Attributes`, (中文(简体) ), `AttributeValue`, (中文(简体) ), `AbsAttrName`镜像 `@opentelemetry/api` 确切地说; 一个真正的OTel `TracerProvider` 满足这些类型的结构. `handoffSpanAttributes()` 财务报告和审定财务报表 `handoffSummarySpanAttributes()` 项目 `@absolutejs/handoff` 将证据纳入这些公约而不复制信息, 参考、外部身份、原始有效载荷或客户数据. ## 许可证 [Apache 2.0 (英语)](https://npmcn.com/package/%40absolutejs/telemetry/LICENSE)B级基底相接于绝对JS许可政策. ## 常见问题 ### @absolutejs/telemetry 是什么？ Tiny为绝对JS生态系统共享了OpenTeleometry底物\. 类型复制@opetelemetry/api's Tracer/Span外形,船尾执行\+跟踪OrNoop帮助器\+0-dep OTLP-HTTP-JSON横跨出口国\(/otlp-http subpath\),并标出ABS ATTRS ### 如何安装 @absolutejs/telemetry？在项目目录运行 npm install @absolutejs/telemetry，或使用 pnpm add / yarn add / bun add。 ### @absolutejs/telemetry 支持 TypeScript 吗？支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。 ### @absolutejs/telemetry 支持 ESM 还是 CommonJS？以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。 ### @absolutejs/telemetry 可以商用吗？ @absolutejs/telemetry 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。 ### @absolutejs/telemetry 的下载量有多少？根据 npm 官方下载统计，@absolutejs/telemetry 在 2026/10/05 – 2026/11/03 这 30 天内被下载 4,617 次，日均约 154 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。 ### @absolutejs/telemetry 还在维护吗？最新版本 0\.3\.1 发布于 2026/08/07（3 个月前）；至今共发布 9 个版本，其中过去 12 个月发布了 9 个；首次发布于 2026/05/31。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。