@ devfellowship/可观察性
React apps的浏览器可观察性 SDK. 提供OpenTeleometry tracking,度量衡,哨兵出错跟踪,Web Vitals,取出仪器,出错边界,以及React Query出错报告——都通过一个单一的提供者包.
安装
npm install @devfellowship/observability
同伴依赖关系
react第18条@tanstack/react-queryqq 5( 可选的—— 允许自动查询错误报告)
快开始
包装您的应用程序 <ObservabilityProvider>数字 :
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:
<ObservabilityProvider
serviceName="my-app"
serviceVersion="1.2.0"
collectorUrl="https://otel.devfellowship.com"
apiKey="your-api-key"
sentryDsn="https://[email protected]/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() 电话 |
公用事业
跟踪自定义事件
import { trackEvent } from "@devfellowship/observability";
trackEvent("button_click", { "button.id": "checkout", page: "/cart" });
设置用户上下文
import { setUserId, setUserRole } from "@devfellowship/observability";
// After authentication
setUserId(user.id);
setUserRole(user.role);
哨兵助手
import { captureError, setSentryUser } from "@devfellowship/observability";
captureError(new Error("something broke"), { component: "Checkout" });
setSentryUser(user.id, user.role);
错误边界
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)是安全的读取和书写. 当一个值需要洗刷,且其属性无法取出新值时,事件或屑被丢弃,aconsole.warn指定密钥名称( 绝不是值) , 并且没有半刷新发送 。 被SDK报告为新出错并丢失了交易所抛出的一个钩子. - IP地址 (中文(简体) ).
sendDefaultPii实值false用它,SDK套装infer_ip: "never"。这里有 没有scrubIPAddressesSDK 选项在@sentry/react10.x. "防止IP地址的存储"是一个哨兵 项目 设置并必须在项目中进行(dfl-react) (中文(简体) ). SDK从不发送IP,并进行测试检查. - 释出. 设定
VITE_GIT_SHA(或releaseprop)在构建时间,所以每次部署时都会有放出变化.
测试 : npm test (单位,有固定装置). 真实浏览器“ 不重放信封” 的证明 : PLAYWRIGHT_PATH=<path to playwright/index.mjs> npm run proof:browser。 。 。 .
发展
npm install
npm run build # builds with tsup (ESM + .d.ts)
出版
npm version patch # or minor/major
npm publish
许可证
麻省理工学院