# @devfellowship/observability 中文文档

规范地址：https://npmcn.com/package/%40devfellowship/observability/

版本：2\.2\.1
npm 元数据更新时间：2026-11-04T22:27:39.837Z
中文译文更新时间：2026-11-12T03:03:24.976Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40devfellowship/observability
原文对照：https://npmcn.com/package/%40devfellowship/observability/?lang=original
项目主页：https://github.com/devfellowship/dfl-observability#readme
源码仓库：https://github.com/devfellowship/dfl-observability

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

- 包体积（解压后）：96.9 kB，5 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：9 个
- peer 依赖：react \>=18，@tanstack/react-query \>=5
- 首次发布：2026-04-02T20:15:08.379Z
- 最新版本发布：2026-11-04T22:27:39.604Z
- 近 30 天下载量：7924（2026-10-12 至 2026-11-10，npm 官方下载统计）
- 已发布版本数：6（近 12 个月 6 个）

## 中文简介

浏览器可观察性 SDK – OpenTeleometry + Sentry for React apps – 开源软件

## 安装

```sh
npm install @devfellowship/observability
```

也可以使用：`pnpm add @devfellowship/observability`、`yarn add @devfellowship/observability`、`bun add @devfellowship/observability`

## README

# @ devfellowship/可观察性

React apps的浏览器可观察性 SDK. 提供OpenTeleometry tracking,度量衡,哨兵出错跟踪,Web Vitals,取出仪器,出错边界,以及React Query出错报告——都通过一个单一的提供者包.

## 安装

```bash
npm install @devfellowship/observability
```

### 同伴依赖关系

-   `react` 第18条
-   `@tanstack/react-query` qq 5( 可选的—— 允许自动查询错误报告)

## 快开始

包装您的应用程序 `<ObservabilityProvider>`数字 :

```tsx
import { ObservabilityProvider } from "@devfellowship/observability";

function App() {
  return (
    <ObservabilityProvider>
      <YourApp />
    </ObservabilityProvider>
  );
}
```

通过零道具,提供者从Vite环境变量读取配置:

| 新闻 var | 目的 |
| --- | --- |
| `VITE_APP_NAME` | 跟踪/测量的服务名称 |
| `VITE_APP_VERSION` | 服务版本 |
| `VITE_OTEL_API_KEY` | API 密钥发送为 `x-api-key` 标题 |
| `VITE_SENTRY_DSN` | 哨兵 DSN(可操作错误跟踪. 会话重播已关闭 。) |
| `VITE_GIT_SHA` | 大楼的Git SHA. 成为哨兵 `release`后退至 `VITE_COMMIT_SHA`,则 `<app>@<version>`。 。 。 . |
| `VITE_OTEL_ENABLED` | 设定为 `"true"` (自动投入生产) |

## 明确配置

所有设置都可以作为道具被传递,压倒性的env vars:

```tsx
<ObservabilityProvider
  serviceName="my-app"
  serviceVersion="1.2.0"
  collectorUrl="https://otel.devfellowship.com"
  apiKey="your-api-key"
  sentryDsn="https://xxx@sentry.io/yyy"
  environment="production"
  enabled={true}
  enableWebVitals={true}
  enableQueryTracking={true}
  enableFetchTracing={true}
>
  <App />
</ObservabilityProvider>
```

### 道具

| Prop | 类型 | 默认 | 说明 |
| --- | --- | --- | --- |
| `serviceName` | `string` | `VITE_APP_NAME` 或者说 `"unknown"` | OTel 资源的服务名称 |
| `serviceVersion` | `string` | `VITE_APP_VERSION` 或者说 `"0.0.0"` | 服务版本 |
| `collectorUrl` | `string` | `"https://otel.devfellowship.com"` | OTel 收集器基础 URL |
| `apiKey` | `string` | `VITE_OTEL_API_KEY` | API 密钥头值 |
| `sentryDsn` | `string` | `VITE_SENTRY_DSN` | 哨兵 DSN( 无法禁用哨兵) |
| `environment` | `string` | `"production"` 编号 : `"development"` | 环境标签 |
| `enabled` | `boolean` | `true` 生产 | 杀技师 |
| `enableWebVitals` | `boolean` | `true` | 捕获LCP、CLS、INP、TTFB |
| `enableQueryTracking` | `boolean` | `true` | 将查询错误作为跨度报告 |
| `enableFetchTracing` | `boolean` | `true` | 全部自动跟踪 `fetch()` 电话 |

## 公用事业

### 跟踪自定义事件

```ts
import { trackEvent } from "@devfellowship/observability";

trackEvent("button_click", { "button.id": "checkout", page: "/cart" });
```

### 设置用户上下文

```ts
import { setUserId, setUserRole } from "@devfellowship/observability";

// After authentication
setUserId(user.id);
setUserRole(user.role);
```

### 哨兵助手

```ts
import { captureError, setSentryUser } from "@devfellowship/observability";

captureError(new Error("something broke"), { component: "Checkout" });
setSentryUser(user.id, user.role);
```

### 错误边界

```tsx
import { ErrorBoundary } from "@devfellowship/observability";

<ErrorBoundary fallback={<p>Something went wrong</p>}>
  <RiskyComponent />
</ErrorBoundary>
```

## 包括什么

-   **OTel 痕迹** —— 说 `BatchSpanProcessor` • OTLP/HTTP出口商
-   **OTel 度量衡** —— 说 `PeriodicExportingMetricReader` • OTLP/HTTP出口商
-   **获取仪器** ——自动创建跨人 `fetch()` 调用( 已过滤的集合 URL)
-   **网络维度** - LCP、CLS、INP、TTFB作为OTel直方图计量法报告
-   **哨兵** ——错误跟踪和浏览器跟踪,并进行擦拭(参见隐私). 不重播会话 .
-   **错误边界** - 反应组件出错,向OTel和哨兵报告
-   **响应查询集成** ——订阅查询缓存,产生故障出错跨度
-   **资源属性** ——浏览器,OS,设备类型,会话ID,取景口,连接类型,路由

## 隐私(哨兵)

由于2.2.0 哨兵客户端是用来泄露任何个人数据的(计划) `20261101-fleet-observability-error-loop`, T1 键:

-   **不重播会话 .** 没有重放集成,两个重放样本率都是0. 没有新的隐私决定, 请不要添加回来 .
-   **匿名用户.** 哨兵用户是每个浏览器的随机ID(`localStorage` 键 `dfl_obs_anon_id`) (中文(简体) ). `setSentryUser(id, role)` 保存签名但忽略 `id`: 没有发送账户编号、电子邮件或名称.
-   **作相扫地.** `beforeSend`, (中文(简体) ), `beforeSendTransaction` 财务报告和审定财务报表 `beforeBreadcrumb` 从信件、请求数据、信头、面包屑和横跨数据中删除电子邮件、 URL 查询字符串和片段、 JWT、 无记名符号、 key=value secretity 和 IPv4 地址。 饼干, `Authorization` 并删除类似的标题。 见 `src/lib/scrub.ts`。 。 。 .
-   **关不上,别扔.** 三个钩子 `scrubEventOrDrop` 财务报告和审定财务报表 `scrubBreadcrumbOrDrop`. 仅限获取的财产(见2026-11-04)是安全的读取和书写. 当一个值需要洗刷,且其属性无法取出新值时,事件或屑被丢弃,a `console.warn` 指定密钥名称( 绝不是值) , 并且没有半刷新发送 。 被SDK报告为新出错并丢失了交易所抛出的一个钩子.
-   **IP地址 (中文(简体) ).** `sendDefaultPii` 实值 `false`用它,SDK套装 `infer_ip: "never"`。这里有 **没有** `scrubIPAddresses` SDK 选项在 `@sentry/react` 10.x. "防止IP地址的存储"是一个哨兵 **项目** 设置并必须在项目中进行(`dfl-react`) (中文(简体) ). SDK从不发送IP,并进行测试检查.
-   **释出.** 设定 `VITE_GIT_SHA` (或 `release` prop)在构建时间,所以每次部署时都会有放出变化.

测试 : `npm test` (单位,有固定装置). 真实浏览器“ 不重放信封” 的证明 : `PLAYWRIGHT_PATH=<path to playwright/index.mjs> npm run proof:browser`。 。 。 .

## 发展

```bash
npm install
npm run build    # builds with tsup (ESM + .d.ts)
```

## 出版

```bash
npm version patch  # or minor/major
npm publish
```

## 许可证

麻省理工学院

## 常见问题

### @devfellowship/observability 是什么？

浏览器可观察性 SDK – OpenTeleometry \+ Sentry for React apps – 开源软件

### 如何安装 @devfellowship/observability？

在项目目录运行 npm install @devfellowship/observability，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：react（\>=18）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @devfellowship/observability 支持 TypeScript 吗？

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

### @devfellowship/observability 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @devfellowship/observability 可以商用吗？

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

### @devfellowship/observability 的下载量有多少？

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

### @devfellowship/observability 还在维护吗？

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