# @btravstack/observability 中文文档 规范地址：https://npmcn.com/package/%40btravstack/observability/ 版本：0\.58\.0 npm 元数据更新时间：2026-11-07T21:12:15.690Z 中文译文更新时间：2026-11-08T18:03:00.839Z 软件包许可：MIT 本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。 原始 npm 页面：https://www.npmjs.com/package/%40btravstack/observability 原文对照：https://npmcn.com/package/%40btravstack/observability/?lang=original 项目主页：https://github.com/btravstack/btravstack#readme 源码仓库：https://github.com/btravstack/btravstack ## 关键信息（来自 npm 元数据） - 包体积（解压后）：83.6 kB，21 个文件 - 模块格式：ESM + CJS - TypeScript 类型：包内自带 - Node.js 要求：\>=22 - 运行依赖：0 个 - peer 依赖：pino ^10，unthrown ^5\.0\.0，@btravstack/di ^0\.58\.0，@btravstack/core ^0\.58\.0，@btravstack/config ^0\.58\.0，@opentelemetry/api ^1\.9\.0，@opentelemetry/sdk-node ^0\.222\.0 - 首次发布：2026-08-25T16:16:35.367Z - 最新版本发布：2026-11-07T21:12:15.359Z - 近 30 天下载量：8367（2026-10-09 至 2026-11-07，npm 官方下载统计） - 已发布版本数：62（近 12 个月 62 个） ## 中文简介 @btravstack/core的可观察性:与内核单位相关的严格Logger端口,无依赖的JSON槽,以及作为日志行的生命周期事件 ## 安装 ```sh npm install @btravstack/observability ``` 也可以使用：`pnpm add @btravstack/observability`、`yarn add @btravstack/observability`、`bun add @btravstack/observability` ## README # @btravstack/可观察性 > 可观察性 [`@btravstack/core`](https://npmcn.com/package/%40btravstack/core),从记录开始:a **严格** `Logger` 端口——无 `any`,没有打印f,没有可变上下文,没有静态 实例——默认执行,将每行标注在环境中 单位的痕量ID、无依赖的JSON槽、子路径后皮诺和 内核的10个生命周期事件作为同流的日志行. 📖 **[文档](https://btravstack.github.io/btravstack/reference/observability)** • 妇女 [如何进行](https://btravstack.github.io/btravstack/how-to/log-and-correlate) • 妇女 [API 参考](https://btravstack.github.io/btravstack/api/observability/) ```sh pnpm add @btravstack/observability @btravstack/core @btravstack/config @btravstack/di unthrown ``` 这四个是同龄人. `pino` 是一个 **选项** 端点,仅在导入时需要 `@btravstack/observability/pino`节点 `>=22`。 。 。 . ## 实例 ```ts import { runMain, Logger } from "@btravstack/core"; import { createLogger, jsonSink, kernelEvents, observability, } from "@btravstack/observability"; import { Module, Provider } from "@btravstack/di"; // The application depends on the port, like any other service. const placeOrder = Provider(PlaceOrder)({ inject: { orders: OrderRepository, logger: Logger }, sync: ({ orders, logger }) => ({ execute: (id, quantity) => orders .save({ id, quantity }) .tap(() => logger.info("order placed", { id, quantity })), }), }); // The starter provides it. `LOG_LEVEL` is read inside the graph and validated // once — `verbose` is a startup failure naming the variable, not a silent // fallback to `info`. const OrderApi = HttpModule("OrderApi")({ router: orderRouter, imports: [ OrdersSlice, CustomersSlice, cache({ adapter: redisCache() }), observability(), otel(), ], }); // The kernel's own events, in the same stream and the same shape. The logger // here is built by hand because `building` is emitted while the graph still // is: the sink cannot come from the context it is watching. await runMain(OrderApi, { onEvent: kernelEvents(createLogger(jsonSink())) }); ``` 单位内部的每行都带有 `traceId`, (中文(简体) ), `unitId` 财务报告和审定财务报表 `tenantId` - 伐木机读取 `currentUnit()` **每个呼叫**,所以一个 应用程序瞄准镜对每个没有单一请求正确 参数串通了调用堆栈. ```json { "orderId": "0199a1e0-0000-7000-8000-000000000001", "time": "2026-08-16T09:41:02.113Z", "level": "info", "message": "order placed", "unitId": "u-7", "traceId": "3f9c…" } ``` ## 是什么使接口严格 | 决定 | 为什么 | | --- | --- | | A 类 **端口**,从一个类或静态 | 测试提供了自己的测试;没有全球性的测试可以达到过去 | | `with(attributes)` 返回一个日志 | 没有变异:两个瞄准镜不能相互间断上下文 | | `Attributes` 是一个平平的平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平 | 日志后端索引的形状;没有 `any`,没有打印,没有字符串 | | 失败了 `cause` | 一个 `Error`是因为 `message` 财务报告和审定财务报表 `stack` 不可假定的 -- -- `JSON.stringify` 单凭一己之力 就能减少值得保留的部分 | | 它不能抛出 | 被打碎的水槽被吞没了:可观察性断层不能变成断层 | | 六级,固定 | `LOG_LEVEL` 在启动时验证,以及 `isEnabled` 是一个比较 | ## 破坏执行工作 `observability({ sink })` 替换目的地; 提供 `Logger` 自己来代替一切 对于一个需要皮诺吞吐量的部署: ```ts import pino from "pino"; import { pinoSink } from "@btravstack/observability/pino"; observability({ sink: pinoSink(pino()) }); ``` 儿童记录员使用 `trace` 地板和所供应的伐木机保持不变. 关卡过滤器会保留这个软件包的.. `LOG_LEVEL`,验证一次——所以有 是过程中的一个过滤器,而不是两个可以不同意的过滤器. JSON和皮诺汇都保留了安全的错误诊断并省略了任意性 错误的有效载荷 。 Pino 的错误序列器安装在儿童日志器上 `trace`,使提供的日志配置完好无损. 组合生产政策还预测环境单位、痕量和租户 在自定义汇和启动人拥有的跨度之前的关联性可以看到它。 UUIDs 和 非零 W3C 跟踪ID 存活; 免费文本不。 未配置的遗产渲染 并明确敏感地调试 保持他们现有的披露行为. 为尽量减少生产数据,通过共享 `diagnosticPolicy()` 结束 `observability({ diagnostics })`, (中文(简体) ), `otel({ diagnostics })` 和临时的 `installTemporalDiagnostics`。没有这一明确政策,错误信息, 堆栈和有界原因链仍然可见。 见 [披露政策参考](https://btravstack.github.io/btravstack/reference/observability#a-shared-diagnostic-disclosure-policy) 用于许可列表和单独的敏感调试访问和保留合同. ## 追踪和计量 包的另一半名字, 后面一个可选的相声子路径 `pino` 为: ```sh pnpm add @opentelemetry/api @opentelemetry/sdk-node ``` ```ts import { observability } from "@btravstack/observability"; import { UnitSpanModule, otel } from "@btravstack/observability/otel"; // Beside observability() in the root's imports; the SDK is a resource of the // graph — started with the scope, flushed by release on every exit path. // Configuration is the OTEL_* environment conventions, read by the SDK itself. const AppImports = [observability(), otel()]; // A span per unit, correlated with the same ids the logger stamps — bound on // the starter's own `unit` option and forked by the runtime around each // request, delivery or activity attempt, e.g. // http({ unit: { anonymous: UnitSpanModule } }) ``` 入境的W3C `traceparent` 输入单位的微量id `@btravstack/http-server` 财务报告和审定财务报表 `@btravstack/amqp-worker`. 自动装置必须预装 (单位:千美元)`node --import @opentelemetry/auto-instrumentations-node/register`) —— 内容 无法成为提供者, 且软件包不会装作不是 。 满 语义 [参考页](https://btravstack.github.io/btravstack/reference/observability)。 。 。 . ## 许可证 [麻省理工学院](https://npmcn.com/package/%40btravstack/observability/LICENSE) 贝诺伊特旅行社 ## 常见问题 ### @btravstack/observability 是什么？ @btravstack/core的可观察性:与内核单位相关的严格Logger端口,无依赖的JSON槽,以及作为日志行的生命周期事件 ### 如何安装 @btravstack/observability？ 在项目目录运行 npm install @btravstack/observability，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：unthrown（^5\.0\.0）、@btravstack/di（^0\.58\.0）、@btravstack/core（^0\.58\.0）、@btravstack/config（^0\.58\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。 ### @btravstack/observability 支持 TypeScript 吗？ 支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。 ### @btravstack/observability 支持 ESM 还是 CommonJS？ 同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。 ### @btravstack/observability 需要什么版本的 Node\.js？ package\.json 的 engines 字段要求 Node\.js \>=22。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。 ### @btravstack/observability 可以商用吗？ @btravstack/observability 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。 ### @btravstack/observability 的下载量有多少？ 根据 npm 官方下载统计，@btravstack/observability 在 2026/10/09 – 2026/11/07 这 30 天内被下载 8,367 次，日均约 279 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。 ### @btravstack/observability 还在维护吗？ 最新版本 0\.58\.0 发布于 2026/11/08（今天）；至今共发布 62 个版本，其中过去 12 个月发布了 62 个；首次发布于 2026/08/26。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。