@bigbertha/ sdk (英语)

Bertha 报告错误 。 浏览器、 React、 节点、 边缘和 Next.js, 没有依赖性 和源地图相匹配的调试 id 而不是文件路径.

• 浏览器中大约7.8 kB gzipt ()npm run size 执行预算).
• 当BERTHA说起时,会退后,然后把排成一行的东西寄出去 过程消失.
• 默认情况下会擦除邮件,无记名符号和隐形查询值.
• 每一件事件都说它是怎样浮出水面的(一个未发现的错误,一个拒绝,一个边界,一个召唤), 将页面的要求与 w3C 导致的服务器错误 traceparent。 。 。 .
• 与 OpenTeleometry 有关的工作 : otlp() 在 Bertha 点出 OTel 导出者, 内部错误 将活动跨度记录在其上,浏览器将它的页面请求作为跨度发送 一旦页面出现错误。 见 追踪。 。 。 .
• 除了请求的跨度外, 发送日志行, 记录所发生的不是错误 。 见 日志。 。 。 .
• 构建插件给每个捆绑一个调试ID,上传其地图并删除 .map 文件,所以地图从不传送到浏览器.

每个项目在Bertha的设置页面显示其运行时间的确切片段,以及它的 键填入。 这个文件更详细地涵盖了同一个领域.

安装

npm install @bigbertha/sdk

每个版本还附在其GitHub发行中,作为 bigbertha-sdk-<version>.tgz。 。 。 . 自己造一个: npm ci && npm run build && npm pack 在此文件夹中.

密钥

每个项目有两个:

• 无效密钥 (单位:千美元)BERTHA_KEY:发送事件. 它运送浏览器,所以它是公开的;a 被泄露的密钥只能发送事件,最多每秒50起.
• 上传密钥 (单位:千美元)BERTHA_UPLOAD_KEY:上传源地图和记录部署. 留着吧 仅限CI机密.

bertha project keys <name> 在服务器上同时打印。 旋转摄入键入 工程设置立即停止旧的设置 .

下一个.js

# .env.local and your host
NEXT_PUBLIC_BERTHA_KEY="…"
NEXT_PUBLIC_BERTHA_URL="https://bertha.example.com"
BERTHA_UPLOAD_KEY="…"   # CI only

// instrumentation.ts: server and edge errors, including onRequestError
export { register, onRequestError } from "@bigbertha/sdk/next"

// instrumentation-client.ts: browser errors and navigation breadcrumbs
export { onRouterTransitionStart } from "@bigbertha/sdk/next/client"

// next.config.ts: stamps the release, uploads maps after `next build`
import { withBertha } from "@bigbertha/sdk/next/config"
export default withBertha({ /* your config */ })

withBertha 选项: release, (中文(简体) ), keepMaps, (中文(简体) ), disableUpload, (中文(简体) ), recordDeploy。它删除下面的地图 .next/static (浏览器可以获取) 并保留服务器的,没有服务 而Vercel的构建输出需要的. keepMaps 带 true, (中文(简体) ), false 函数 内部路径 .next。它也给环境留下了印记,所以 Vercel 预览报告 以中场出击 在Vercel上,它记录了上传后的部署, 与Vercel的承诺sha, 消息和作者,所以发布页面知道什么出(recordDeploy: false 关掉它.

为了自己的选择( :beforeSend, (中文(简体) ), tags, (中文(简体) ), sampleRate),电话 init 从 @bigbertha/sdk/browser 内 instrumentation-client.ts 而不是导入 next/client,以及 init 从 @bigbertha/sdk/node 内 register()。构建插件 无论是哪种方式都一样,它都保留了调试IDs的另一个工具(例如哨兵的) 插件)已经给出了捆绑,因此两者可以并肩运行. 把它包进去 withSentryConfig 并设置哨兵 sourcemaps.deleteSourcemapsAfterUpload: false数字 : 哨兵的插件首先运行,它所删除的地图永远无法到达Bertha. 贝莎去除 之后被送去的.

维特 (浏览器)

// src/main.ts
import { init } from "@bigbertha/sdk/browser"
init({ key: import.meta.env.VITE_BERTHA_KEY, url: import.meta.env.VITE_BERTHA_URL })

// vite.config.ts
import { bertha } from "@bigbertha/sdk/vite"
export default defineConfig({ plugins: [bertha()] })

浏览器事件携带什么

• 该页: 它的 URL 作为事件的要求, 像任何 URL 一样被擦除 .

• 它是如何浮出水面的: onerror 或者说 onunhandledrejection也没有被应用程序抓住.

• 页面状态 : 视图和像素比例,在线,可见标签,页面是如何打开的 (导航、再装入、后/前、前),开关时间长短,是否 浏览器是自动的 (navigator.webdriver),裁判员、语言、时区和 连接类型, 当有一个版本时则使用 Next.js 版本 .

• 访客的IPbertha从请求中读取并全数储存. sendIp: false 关闭; 给定的 IP setUser 改为使用.

• 面包屑: ,从 后向缓存、 标签隐藏和显示、 路由变化、 点击、 获取和 XHR 具有地位和期限 console.log, (中文(简体) ), info, (中文(简体) ), warn 财务报告和审定财务报表 error关闭任何 与 breadcrumbs: { console: false } 诸如来.

• 追踪编号,每页负载1个. 同源取来和XHR请求载有 traceparent 带有它的头条,所以服务器错误 旁边的错误 。 对于另一个来源的API,请输入 tracePropagationTargets (URL 前缀或图案)并允许 traceparent cORS 中的标题:

  init({ key, url, tracePropagationTargets: ["https://api.example.com"] })
  

• 页面请求的跨度: 页面本身、文档载荷和每个获取 和XHR及其方法,被擦除的URL和状态. 他们等待的记忆(最后200) 只要一页出错就去bertha 只要它一直停留 打开,所以一个不会出错的页面不会发出任何错误. spans: false 关掉.

浏览器扩展和脚本中的框架Safari隐藏(webkit-masked-url://已经 所以bertha可以说 当一个错误可能不是你的.

插件打开隐藏的源图, 如果构建没有 。 只有上传时 BERTHA_UPLOAD_KEY 所以本地建筑离线 保存地图. 选项 : release, (中文(简体) ), url, (中文(简体) ), uploadKey, (中文(简体) ), keepMaps。 。 。 .

反应

import { ErrorBoundary } from "@bigbertha/sdk/react"

<ErrorBoundary fallback={({ reset }) => <button onClick={reset}>Try again</button>}>
  <App />
</ErrorBoundary>

ErrorBoundary 报告它用 React 组件堆栈捕获到的东西,然后制作 fallback: 节点,或函数 { error, eventId, reset }。还需要 onError(error, componentStack, eventId) 财务报告和审定财务报表 tags输入条目时添加 React 的 每个事件的版本。 反应是可选的对等依赖; SDK 中没有其他的 需要这个.

节点

import { init } from "@bigbertha/sdk/node"
init() // reads BERTHA_KEY, BERTHA_URL, BERTHA_RELEASE, BERTHA_COMMIT and NODE_ENV

init 报告未发现例外和未处理的拒绝,冲出,然后作为节点退出 将(handlers: false 关掉它。 每隔20分钟也会发出心跳 bertha能从"不跑"中分辨出"没有出错"(bertha)heartbeat: false) (中文(简体) ). 心跳名称 执行过程,从 commit, (中文(简体) ), BERTHA_COMMIT 或主机本身的变量 (赫鲁库的) HEROKU_SLUG_COMMIT 在、 Render 、 铁路、 Vercel 、 GitHub 上没有元数据 动作),所以发布即不 bertha deploy 记录了它的代码.

节点运行的代码不需要源地图: SDK 读取相邻的行 从磁盘中将您自己的文件框并随事件一起发送( r)contextLines: false 关掉它。 这也将 V8 的默认堆栈限制从 10 帧提高到 50, 所以 a 深层框架呼叫不隐藏你的代码。 你设定的限度是孤独的.

wrapHandler(fn) 报告一个请求处理者丢掉并重新扔出去的东西 请求: 其 URL 、 其信头( 从不 authorization, (中文(简体) ), proxy-authorization, (中文(简体) ), cookie, (中文(简体) ), set-cookie 或者说 x-api-key),第一个客户端IP x-forwarded-for 跳还是跳 套接字, 以及从一个接入的追踪 traceparent下一个 onRequestError 发送 同样的.

带有自己的错误中间软件的应用程序将框架的请求传递为 req 获得 同一请求、IP和追踪:

// Koa
app.on("error", (err, ctx) =>
  captureException(err, { req: ctx, status: err.status ?? 500, mechanism: { handler: "koa", handled: false } }),
)
// Express, after the routes
app.use((err, req, res, next) => {
  captureException(err, { req, status: 500, mechanism: { handler: "express", handled: false } })
  next(err)
})

req 取节点 IncomingMessage快递 req科亚的 ctx 或获取 Request (边入也. mechanism 说错误逃脱了应用程序自己的代码,所以bertha 不读它作为一个应用 捕获。 服务器事件也命名为主机( Heroku ) DYNO,否则主机名)和 节点和下个.js版本.

对于被捆绑的节点代码,请给出输出调试ID并上传其构建后的地图:

npx bertha sourcemaps upload dist

追踪

bertha在OTLP/HTTP上取取了OpenTeleometry的痕迹,所以一个错误的页面显示的是 整个请求都是通过你的服务完成的:时间在哪里,什么先失败 呼叫一个从未回答过的服务。 它持续一个小时 并保持一个 跟踪一次错误事件,它就命名了,所以只有错误停留的痕迹.

SDK不记录服务器横跨自身. 使用 OpenTeleometry 自己的仪器和 将出口者指向伯塔 otlp(),它给出了 URL 和密钥头 从 BERTHA_KEY 财务报告和审定财务报表 BERTHA_URL (或 key 财务报告和审定财务报表 url:

// Next.js: instrumentation.ts (npm install @vercel/otel)
import { OTLPHttpProtoTraceExporter, registerOTel } from "@vercel/otel"
import { otlp, register as bertha } from "@bigbertha/sdk/next"
export { onRequestError } from "@bigbertha/sdk/next"

export function register() {
  registerOTel({ serviceName: "shop", traceExporter: new OTLPHttpProtoTraceExporter(otlp()) })
  return bertha()
}

// Node: before anything else loads
// (npm install @opentelemetry/sdk-node @opentelemetry/auto-instrumentations-node @opentelemetry/exporter-trace-otlp-proto)
import { NodeSDK } from "@opentelemetry/sdk-node"
import { getNodeAutoInstrumentations } from "@opentelemetry/auto-instrumentations-node"
import { OTLPTraceExporter } from "@opentelemetry/exporter-trace-otlp-proto"
import { init, otlp } from "@bigbertha/sdk/node"

new NodeSDK({ traceExporter: new OTLPTraceExporter(otlp()), instrumentations: [getNodeAutoInstrumentations()] }).start()
init()

任何其他OTLP出口商也在工作:发送到 <url>/ingest/v1/traces 与 Authorization: Bearer <key>作为原生或JSON.

随着OpenTeleometry的运行,每个事件都命名了活动时的跨度 所以Bertha会把错误放在那个范围内 一个跨度在另一个跟踪 比 请求的 traceparent 由 : 哨兵运行 OpenTeleometry 并带有自己的踪迹 iDs,它的跨度会切断发送请求的页面的错误. 没有它,事件仍然伴随着 从收到的追踪 traceparent 并降落在请求的最外侧.

日志

记录线是用来记录所发生的事情的,这不是错误:一个成功的倒计时,一个缓慢的 上游,一个完成的工作。 线路去项目的日志,而不是它的问题,并携带 正在运行的跟踪(在浏览器中,页的),所以一个请求的行位于它的横跨处.

import { log } from "@bigbertha/sdk/node"   // or /browser, /edge, /next, /next/client

log.warn("TikWM failed; used the fallback", { video: "7301", status: 502 })
log.info("Synced orders", { count: 41 })
log.error(err)   // a line, not an issue: use captureException for that

log.debug, (中文(简体) ), info, (中文(简体) ), warn 财务报告和审定财务报表 error 接收消息(或 Error)和可选 字段。 字段作为文本发送,对象作为JSON. 客户 init() 返回有 同样的方法 client.log。 。 。 .

在服务器上,将请求作为 req 因此,一条线 降落在它的跟踪, 道路 captureException 已经 运行在请求以外的跟踪上 traceparent (哨兵's)被传递过来, 没有OpenTeleometry,请求的追踪是 都在这里了. trace 设置一个直接.

log.info("Used the cached price", { product: 28 }, { req: ctx })   // Koa's ctx, Express's req, a Request

• 下行数 logLevel (单位:千美元)"info" 未发送. "off" 无.
• 关于被捕获错误的错误行带有事件编号 (单位:千美元)bertha.event_id),所以线链接到这个问题,以哪个为先.
• 与 captureConsole: true, (中文(简体) ), console.debug, (中文(简体) ), log, (中文(简体) ), info, (中文(简体) ), warn 财务报告和审定财务报表 error 为: 也作为行号发送。 浏览器控制台面包屑保持原样.
• 线路像事件一样被洗刷, 分批发送 最多100秒第一, 并随页面或进程消失而发送。 当超过1000时 在等待(贝塔要求等待,或下降), 年龄最大的被扔下,下一个被扔下 批次以一行开头,写上多少个.
• 一个太老取出日志的Bertha答404:SDK警告一次并停止发行.

边缘

import { init } from "@bigbertha/sdk/edge"
init({ key: env.BERTHA_KEY, url: env.BERTHA_URL })

手牵手

每个条目输出相同的功能:

captureException(err, { level: "warning", tags: { job: "nightly" }, fingerprint: ["nightly-import"] })
// An error's own fields (code, status…) are sent with it, each as JSON.
captureMessage("Payment provider slow", { level: "warning" })
addBreadcrumb({ category: "cart", message: "Added 2 items" })
setUser({ id: "u_42" })   // hashed on the server, never shown in full
setTag("tenant", "harbour")
await flush()

选项

部署

出局后从中情局记录每个部署:

npx bertha deploy --env production

它发送释放 和最后一个承诺的sha,消息和作者。 发行页面 然后显示部署 带来了什么 是什么之后安静。 第一次活动 未知的释放也创造了释放,bertha将其标记为仅见,没有部署. 当释放是一个充分的承诺sha, 贝特哈把它作为承诺.

测试事件

检查密钥到达Bertha时不打破任何东西:

npx @bigbertha/sdk test --url https://bertha.example.com --key <the project's key>

它发出一个错误,"伯特哈测试事件",标记 test: true在发展中,除非 --env 说不然. BERTHA_URL 财务报告和审定财务报表 BERTHA_KEY 工作代替旗帜.

发展

npm run check   # types
npm test        # unit tests
npm run size    # browser bundle budget
npm run e2e     # the real bertha binary and the example apps, end to end

npm run e2e 用途 ../server/target/debug/bertha,或 BERTHA_BIN。 。 。 . -- --next 添加 下个例(J)npm install 内 examples/next-app (第一编).

有什么新情况

每个版本的更改都在 变动情况在"JavaScript SDK"栏下 升级时要做的事 SDK分享Bertha的版本,所以 释放无法改变其中的任何内容.

许可证

麻省理工学院. 见 自由主义。 。 。 .