# @12-apps/observability-backend 中文文档

规范地址：https://npmcn.com/package/%4012-apps/observability-backend/

版本：1\.9\.0
npm 元数据更新时间：2026-08-25T00:31:48.147Z
中文译文更新时间：2026-11-05T19:58:31.638Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%4012-apps/observability-backend
原文对照：https://npmcn.com/package/%4012-apps/observability-backend/?lang=original
项目主页：https://github.com/12-apps/shared-packages#readme
源码仓库：https://github.com/12-apps/shared-packages

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：42.1 kB，9 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=22\.0\.0
- 运行依赖：2 个
- 首次发布：2026-08-07T15:49:30.001Z
- 最新版本发布：2026-08-25T00:31:47.771Z
- 近 30 天下载量：32596（2026-10-04 至 2026-11-02，npm 官方下载统计）
- 已发布版本数：16（近 12 个月 16 个）

## 中文简介

服务器端的错误报告在Sentry上,附在日志器上而不是呼叫站点:一个转发出错/警告的温斯顿运输机,一个在任意深度按键进行编辑的PII擦洗机,以及一个故意退出的冲洗机. 关闭, 除非 SENTRY DSN 已设定, 所以 dev, C

## 安装

```sh
npm install @12-apps/observability-backend
```

也可以使用：`pnpm add @12-apps/observability-backend`、`yarn add @12-apps/observability-backend`、`bun add @12-apps/observability-backend`

## README

# `@12-apps/observability-backend`

服务器侧错误报告 Sentry, 因为只有一个环境, 没有人可以附加 一个调试器.

它有一个浏览器对应, `@12-apps/observability-frontend`它们是两个 软件包而不是一个,因为它们完全没有代码,只有环境 变量——此侧是 `@sentry/node` 加号 `winston-transport`另一个是 `@sentry/react` 加上反应,一个包就可以装上温斯顿运输 每个SPA的依赖树和每个服务器的回放。 他们是独立的 (或运行 没有另一个) 但故意分享 `SENTRY_ENVIRONMENT` 财务报告和审定财务报表 `SENTRY_RELEASE`,所以浏览器事件 及其背后的500 降落在同一 同一建筑下的环境.

## 为什么它存在

生产失败曾留下一个痕迹: 容器,随它而死亡,并且只能在SSH上达到。 所以,唯一的办法 学习 _为什么_ 有些东西破解了 是为了了解源头和猜想 4次连续错误的诊断就是代价。 这条线本来可以 在第一次尝试中结束它 一直存在; 没有人能读到它.

## 使用量

```ts
import { sentryTransport, flushReporter, scrub } from "@12-apps/observability-backend";

const reporter = sentryTransport();
const logger = winston.createLogger({
  transports: [consoleTransport, ...(reporter ? [reporter] : [])],
});
```

**它挂出LOGGER,而不是每个呼叫网站.** 共享日志已经 漏斗,每个功能的 `log.error` 经历了一个温斯顿的例子,所以 在此附加意味着新模块在登录时被覆盖,没有任何内容 记住 备选案文,a `captureException` 除了每个 `throw`,这是一条规则 第一次有人忘记它就衰败了.

注意这个陷阱意味着: **`console.error` 未联系到记者.** 温斯顿是漏斗;任何写过它的东西 到达一个容器的积分和 没有别的地方.

| 导出 | 它会做什么 |
| --- | --- |
| `sentryTransport()` | 页:1 `winston-transport` 安装,或 `null` 当报告关闭时 |
| `sentryEnabled()` | 是否为此进程配置了 DSN |
| `flushReporter(timeoutMs?)` | 等待已排队的事件; 在故意退出前拨打 |
| `scrub(value)` | 将上下文对象折叠成信件时, 任意深度按密钥编辑 PII |

`flushReporter()` 事情比看起来要重要 SDK批发 同步,所以 `log.error(…)` 接下来是 `process.exit(1)` 流泪过程 与事件仍在记忆中 大部分,因为一个死在靴子上的过程 留下了别的东西.

## 除非设定了 DSN , 否则它将被关闭

没有 `SENTRY_DSN`,没有运输,没有网络。 Dev CI和每一次测试都保持安静 和离线。 授权是一个部署决定,从来不是一个代码——这也是 是什么让测试套房的故意故障 无法填补问题跟踪器.

| 变量 | 说明 |
| --- | --- |
| `SENTRY_DSN` | 唯一需要的一个。 只写摄入. |
| `SENTRY_ENVIRONMENT` | 倒计时 `NODE_ENV`,则 `production` |
| `SENTRY_RELEASE` | 用于构建错误 |
| `SENTRY_TRACES_SAMPLE_RATE` | 默认为 `0` ——追踪每段计费,回答"多慢",而这个答案是"抛出的东西" |

## 临 二

`scrub()` 按任何深度而不是图案匹配值编辑: a 巴西的CPF是11位数字,许多身份证也值得保留。 药品和 量是故意活下来的——一种能吃到量的洗涤剂会留下每件事 不可诊断.

这不是防御性的装饰。 写给它的泄漏是供应商的错误 保留上游反应机构,在被拒绝付款时,该反应机构携带 付款人的名字,电子邮件和税务id. `sendDefaultPii` 无论DSN如何 都被扣留 所以请求尸体 饼干和IP从不随身携带.

运输也送来 **消息** 作为字符串而不是原始元 对象: Winston 格式化运行 `util.inspect(…, { depth: 5 })` 超过额外 这恰恰是供应商的有效载荷如何到达 第三方.

## 为什么船会编成

不同于此 repo 中的大多数软件包, 此软件包发布 `dist` (双重CJS+ESM与 `.d.ts`)而不是TypeScript源. 有两个原因,两个都是负载的:

1.  **节点拒绝剥去下面的类型 `node_modules`** (单位:千美元)`ERR_UNSUPPORTED_NODE_MODULES_TYPE_STRIPPING`) (中文(简体) ). 一个服务器导入此选项 软件包从注册处得到一个硬故障 `.ts`它确实 _没有_ 在工作空间中失败,其中 pnpm 链接到软件包和节点解析 a 外部真实路径 `node_modules` - 所以虫子会首先出现在 消费者,出版后.
2.  **常见的JS消费者存在.** `@12-apps/shared-helpers` cJS 有经典 `moduleResolution`,这忽略了 `exports` 完整地图并读取 `main`编号 :`types`。 。 。 .

## 测试

```bash
pnpm --filter @12-apps/observability-backend test
```

没有到达网络:套房声称有两个安全属性—— 报告可以关闭,它转发的内容可以被清除.

## 常见问题

### @12-apps/observability-backend 是什么？

服务器端的错误报告在Sentry上,附在日志器上而不是呼叫站点:一个转发出错/警告的温斯顿运输机,一个在任意深度按键进行编辑的PII擦洗机,以及一个故意退出的冲洗机\. 关闭, 除非 SENTRY DSN 已设定, 所以 dev, C

### 如何安装 @12-apps/observability-backend？

在项目目录运行 npm install @12-apps/observability-backend，或使用 pnpm add / yarn add / bun add。

### @12-apps/observability-backend 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @12-apps/observability-backend 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @12-apps/observability-backend 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=22\.0\.0。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @12-apps/observability-backend 可以商用吗？

@12-apps/observability-backend 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @12-apps/observability-backend 的下载量有多少？

根据 npm 官方下载统计，@12-apps/observability-backend 在 2026/10/04 – 2026/11/02 这 30 天内被下载 32,596 次，日均约 1,087 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @12-apps/observability-backend 还在维护吗？

最新版本 1\.9\.0 发布于 2026/08/25（2 个月前）；至今共发布 16 个版本，其中过去 12 个月发布了 16 个；首次发布于 2026/08/07。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。