@github/failbot

中文文档
1.1.1发布于 2026/08/06MITTypeScriptCommonJS近 30 天下载 4.5万

JavaScript 的 Faullbot 客户端

中文使用文档
文档目录4 节
  1. 安装
  2. 用法 :
  3. 提交报告
  4. 例外有效载荷

失败者联署材料

A 类 失败者 javaScript 的客户端 .

安装

此软件包作为 npm 发布 @github/failbot。 。 。 .

❯ npm install @github/failbot

用法 :

const {Failbot, HTTPBackend, LogBackend} = require('@github/failbot')

const failbot = new Failbot({
  app: 'my-cool-app',
  backends: [new HTTPBackend({haystackURL: process.env.HAYSTACK_URL}), new LogBackend({log: console.log.bind(console)})]
})

try {
  riskyThing()
} catch (error) {
  failbot.report(error, {
    extra: 'metadata',
    can: 'be',
    passed: 'as well'
  })
}

提交报告

Failbot.report(error, metadata?, options?) 返回每个已配置后端的一个承诺。 报告是默认的最佳努力,因此交付失败决心 undefined。配置和有效载荷准备错误,包括编辑错误,同步抛出.

设定 rejectOnError 用后端发送错误拒绝 :

await Promise.all(failbot.report(error, metadata, {rejectOnError: true}))

HTTPBackend 将获取出错,超时,以及非-2xx响应视为交付失败. 默认5秒后请求超时 。 设定 timeoutMs 以配置超时 :

const backend = new HTTPBackend({
  haystackURL: process.env.HAYSTACK_URL,
  timeoutMs: 1_000
})

例外有效载荷

HTTP和日志报告包括一个具体运行时间的平台("node" 在节点.js和 "javascript" 和结构化 exception_detail 默认。 来自V8/Node/Chrome和Firefox/Safari的堆放框架已恢复正常,以便Failbog的调用者第一顺序。 遗产 class, (中文(简体) ), message字符串 backtrace 字段也用于兼容性.

消费者可以推翻默认 platform 财务报告和审定财务报表 exception_detail 通过元数据传递到 report。该格式继续拥有遗留错误字段、时间戳和JavaScript环境.

生成结构化例外字段编辑了Failbog全局上下文过滤器覆盖的已知证书模式,包括 URL 基本- 自动证书, cookie 值, 敏感的密钥值对等, 以及 GitHub 令牌 。 这种过滤有意保留了其他例外内容,如电子邮件地址和标识符. 提供打电话者 exception_detail 数值默认是逐字保存的,而遗留字段保留其已存在的值.

应用程序所有者负责将特定服务的敏感数据保留在例外情况之外。 配置 a redact 当应用程序处理默认证书模式无法识别的值时,函数:

const failbot = new Failbot({
  app: 'my-cool-app',
  backends: [new HTTPBackend({haystackURL: process.env.HAYSTACK_URL})],
  redact(value) {
    return value.replace(/service-specific-sensitive-pattern/g, '[app redacted]')
  }
})

内建过滤运行于生成的结构化细节上. 然后,自定义功能运行在运出的有效载荷中每个JSON可序列化字符串上,包括生成和调用人提供的结构化细节、遗留字段和元数据。 它不适用于 sensitive_context。将其用于 GitHub 调用的额外格式 安全例外处理指导,例如授权和HMAC头,JWT,服务证书,以及特定应用程序的序列数据. 函数必须总是返回字符串,并且不能丢出。 添加应用程序编辑规则的测试,并在一个规则匹配时记录一个参数或安全日志条目,这样基础例外可以被固定.

自定义后端执行接收所配置的函数为第三个参数 report 在传输例外数据之前必须应用它。 捆绑的 HTTP 和日志后端自动做到这一点.

例外元数据应使用已登记 语义公约。Splunk 中必须具备但不能到达哨兵的数据可以放置在 Failbog 中 sensitive_context 对象 :

failbot.report(error, {
  context: {'gh.example.repository.id': repositoryId},
  sensitive_context: {'gh.example.repository.path': repositoryPath}
})

仅使用 sensitive_context 当需要保留该值时。 认证数据和其他受限制的内容在报告之前必须删除,而不是通过上述两种方式发送.

为了将报告的例外情况归于服务目录服务 catalog_service 标记包括在通过此库报告的所有例外中。 由于所有的摩达部署 OTEL_SERVICE_NAME 环境变量, catalog_service 被作为 OTEL_SERVICE_NAME。 。 。 .

您不需要覆盖此值, 但是, 如果您需要, 您可以通过 catalogService 页:1 Failbot 构造器 : const failbot = new Failbot({app: 'my-app', catalogService: 'my-catalog', backends: ...})。请注意,压倒一切的这一值可能使你的团队无法收到与大量例外情况有关的警报.

版本与发布记录

@github/failbot 共发布 7 个版本,首次发布于 2021/10/21;过去 12 个月发布了 1 个版本。

版本发布日期距今
1.1.1latest2026/08/063 个月前
0.9.12025/09/241.1 年前
0.8.32023/02/203 年前
0.8.22022/11/114 年前
0.8.12022/11/114 年前
0.8.02021/11/304 年前

关于 @github/failbot 的常见问题

@github/failbot 是什么?

JavaScript 的 Faullbot 客户端

如何安装 @github/failbot?

在项目目录运行 npm install @github/failbot,或使用 pnpm add / yarn add / bun add。

@github/failbot 支持 TypeScript 吗?

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

@github/failbot 支持 ESM 还是 CommonJS?

以 CommonJS 形式发布,可以直接 require();在 ES Module 项目中也可以用 import 引入(Node.js 会把 module.exports 作为默认导出)。

@github/failbot 需要什么版本的 Node.js?

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

@github/failbot 可以商用吗?

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

@github/failbot 的下载量有多少?

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

@github/failbot 还在维护吗?

最新版本 1.1.1 发布于 2026/08/06(3 个月前);至今共发布 7 个版本,其中过去 12 个月发布了 1 个;首次发布于 2021/10/21。发布频率只是参考信号:功能稳定的工具可能很少需要更新,建议结合源码仓库的 issue 和提交记录判断。