@beignet/devtools

中文文档
0.0.65发布于 2026/11/08MITTypeScriptES Module近 30 天下载 1984

Beignet的开发时间演示工具 - 服务器运行时间的小型望远镜

中文使用文档
文档目录17 节
  1. 代理技能
  2. 安装
  3. 下一个.js 设置
  4. 地方持久性
  5. 跟踪上下文
  6. 观察者
  7. 使用大小写工具
  8. 提供方仪器
  9. 审计活动
  10. 手工活动
  11. 终点
  12. 配置
  13. 编辑
  14. API 密码
  15. 生产安全
  16. 发展
  17. 许可证

@beignet/devtools (英语)

运行时间 : Beignet需要Node.js 22.12或更新. Bun是可选的.

[叹息] Beignet是实验性的α软件. 这个 0.0.x 包行为早期 评估,且在框架结算时,API可能在发布之间发生变化.

Beignet Apps的开发时间事件时间表. 它记录了HTTP的要求, 错误、 使用大小写运行、 域事件、 任务、 发件箱发送、 调度和提供者 活动在有限度的内存缓冲器中,然后服务于您从 应用.

事件提供者默认启用外部生产并返回 a 除非明确启用,否则不开放端口。 HTTP 路线 仅允许自动开发.

createDevtoolsProvider(...) 返回稳定 DevtoolsProvider 类型. DevtoolsConfig 描述已验证的配置; Zod 方案仍然是 内部执行细节.

代理技能

这个包装的是谭斯塔克特意技能 @beignet/devtools#runtime-safety当配置抓取,曝光时装入 本地开发以外的HTTP仪表板,增加授权或自定义 编辑、审查持续的诊断或调试提供者事件.

安装

bun add @beignet/devtools @beignet/core

下一个.js 设置

登记提供者:

import { createDevtoolsProvider } from "@beignet/devtools";
import { createNextServer, createNextServerLoader } from "@beignet/next";

export const getServer = createNextServerLoader(() =>
  createNextServer({
    ports,
    providers: [createDevtoolsProvider(), ...providers],
    context: ({ ports, requestId, trace }) => ({
      requestId,
      ...trace,
      ports,
    }),
  }),
);

提供者是服务器需要的唯一编程工具. 请求和错误 事件由服务器的内置仪器记录,它解决了 最终端口的提供方仪器端口(ports.instrumentation, (中文(简体) ), 接下来 ports.devtools) (中文(简体) ). 配置信头、被忽略路径、编辑和 与 instrumentation 选项 createServer(...) 编号 : createNextServer(...)。 。 。 .

登记提供者是可选的。 若为 @beignet/devtools 已安装,但 createDevtoolsProvider() 没有注册, 服务器运行时没有devtools 财务报告和审定财务报表 beignet doctor 报告不失败的信息提示 doctor --strict。 。 。 .

添加全覆盖路径 :

// app/api/devtools/[[...path]]/route.ts
import { createDevtoolsRoute } from "@beignet/devtools";
import { getServer } from "@/server";

export const { GET, POST } = createDevtoolsRoute(
  async () => (await getServer()).ports.devtools,
  {
    basePath: "/api/devtools",
    authorize: async (req) =>
      Boolean(await (await getServer()).ports.auth.getSession(req)),
  },
);

签名,然后打开 /api/devtools。 。 。 .

路径仍然隐藏,除非您提供 authorize。浏览器请求 a 一个 Origin 信头也必须是同一来源的。 生成的应用程序使用认证 端口,这样签名会话就可以打开仪表板.

仪表板连接到事件流 Server - Sent Events and falls 回到投票时 EventSource 无法使用。 侧边栏组视图 概览、HTTP、应用、基础设施和业务 每个视图的活事件计数徽章,加启用自定义的动态视图 有观者. 在狭窄的屏幕上,侧边栏会倒塌到图标栏上,所以 活动视图保持可用空间。 标题显示可点击的统计数据(活动, 请求、出错、使用大小写、活线连接状态、暂停/恢复和清除. 暂停缓冲事件,并在恢复时披露这些事件.

该流发送一个快照 每一个连接, 发出心跳评论, 4分钟后结束 EventSource 与新边界重接 示意图. 当主机通过请求中止或响应报告断开时 取消, 流会释放内存订阅; 定时关闭 做同样的。 响应流还封顶了1 MiB 未读编码的数据 关闭了 EventSource 可以重新连接,而不是保留一个未绑定的队列. 初始快照保存适合的监视器元数据,然后取相接 最新事件窗口, 当下一个条目无法匹配时停止 。 这个 显示结果的仪表板 omittedEvents 财务报告和审定财务报表 omittedWatchers 计数 作为部分弹出警告,防止储存过多的事件从 导致永久重联循环或重复检查其余部分 缓冲.

仪表板遵循系统颜色方案并包括手册 光/暗/系统切换持续 localStorage。主题与 阴影外观 生成的 Beignet 启动程序 .

请求行扩展为共享事件的端到端生命周期视图 同样的 traceId 或者说 requestId细节使一个生命周期瀑布: 作为相对计时栏所绘制的相干相干相干相干相干相干相干相干相干相干相干相干相干相干相干相干相干相干相干相干相干相干相干相干相干相干相干相干相干相干相干相干相干相干相干相干相干相干相干相干相干相干相干相干相干相干相干相干相干相干相干相干相干相干相干相干相干相干相干相干相干相干相干相干相干相干相干相干相干相干相干相干相干相干相干相干相干相干相干相干相干相干相干相干相干相干相干相干相干相干相干相干相干相干相干相干相干相干相干相干相干相干相干相干相干相干相干相干相干相干相干相干相干相干相干相干相干相干相干相干相干相干相干相干 ,以及路线匹配、合同名称、, 请检查date=中的日期值 (帮助), a 编辑说明、按类别分类的相关活动和原始JSON.

新闻 / 以焦点搜索,匹配事件摘要、路径、消息, 姓名、监视者、身份证和细节 方法、状态和监视器过滤器缩小 时间太紧了 时间线行带人可读摘要和ID 切换到复制点击芯片 。 JSON 详细查看器使语法 突出显示、可折叠节点和复制按钮.

错误按所有者查看失败: 路由、 框架、 提供者、 工作、, 调度,发件箱,客户端,devtools,或未知. 每行显示 信件、 拥有者、 相关路线/ 状况、 请求 ID、 痕量 ID 和附近 关联事件,这样你就可以看到失败是否属于应用程序代码, 框架边界、提供者工作或背景执行.

焦点小组提供子系统计量、行摘要和钻入场 每个Beignet工作流程原始。 数据库显示查询数, 失败, 推断表格名称、编辑状态、提供者名称、端口、参数计数、, 当运行时间可以保留主动请求上下文时,则请求/追踪ID. 发件箱显示已交付/重试/已死字母计数,消息名称/类型,尝试, 重试时间, 以及相关的请求/ 跟踪上下文 。 工作和时间表 生命周期状态、提供者、重试/错误细节、克龙元数据以及请求 上下文。 缓存、存储、上传、邮件、付款、应享权利、通知、, 授权、审计、政策和费率限制显示特定领域指标,例如 点击/出错,丢失对象,文件计数,收件人,取出会话, 已核实的webhooks,产品访问决定,频道,会话状态,耐用 审计行为者/资源、政策决定以及允许与被冻结的检查相对应.

在调试路由时先使用请求的生命周期视图 。 它显示是否 反应是路由自有或框架自有,使用案件处理 记录了相关的提供者事件,哪些工作/出栏/计划/领域 事件被触发,存储的元数据是否被编辑.

您可以在自己的整合测试中断言此图: 驱动真正的 HTTP 写入 和错误请求,读取devtools事件结束点,并验证请求 行、使用大小写跨度、持久的审计端口副作用和路由自有错误 通过请求元数据保持关联。 提供者查询和持久发包 显示在同一时间表中.

地方持久性

默认缓冲器位于内存. 当您想要时启用本地持久性 在 dev 服务器中幸存的时间 :

import {
  createDevtoolsProvider,
  createFileDevtoolsStore,
} from "@beignet/devtools";

createDevtoolsProvider({
  store: createFileDevtoolsStore({
    filePath: ".beignet/devtools/core/events.jsonl",
  }),
});

您也可以通过环境变量启用内置文件存储 :

DEVTOOLS_PERSIST=true
DEVTOOLS_PERSIST_PATH=.beignet/devtools/core/events.jsonl

文件商店为最近配置的事件撰写了JSONL和收缩. POST /api/devtools/clear 清除内存缓冲和已配置的商店.

跟踪上下文

Devtools是OpenTeleometry-兼容的,不依赖于OpenTeleometry SDK. 微量原始人生活着 @beignet/core/tracing: 服务器已读取 W3C 战车 traceparent 信头,当缺失时创建本地间隔,曝光 当前 traceparent 响应头并添加已捕获的跟踪字段 事件.

所有捕获的事件可包括:

  • traceId: W3C 追踪分布式关联的ID
  • spanId: 事件所代表的操作的跨度 ID
  • parentSpanId: 当事件被嵌入时, 父跨 ID
  • traceparent: 当前跨度的 W3C 标题值

散开 trace 上下文参数输入您的应用程序上下文, 所以使用大小写 仪器可以将嵌入的跨度附加在请求的跟踪上.

观察者

Devtools是围绕观察者组织的. 监视者拥有一个抓捕类别 并记录输入共享时间表的事件.

内设观察者:

  • requests hTTP请求时间和合同路线活动.
  • errors 记录未处理的错误,使用大小写失败,以及devtools失败.
  • useCases 记录应用程序命令和查询执行.
  • eventBus 记录域事件发布.
  • jobs 记录背景工作生命周期事件.
  • outbox 记录耐用寄件箱、复写和死信.
  • schedules 记录时间表执行.
  • providers 记录提供者设置、启动和停止活动.
  • db 记录第一当事方提供者的数据库诊断.
  • cache 记录来自第一当事方提供者的缓存诊断.
  • flags 标识评价、明确曝光和跟踪 来自第一当事方提供者的事件.
  • storage 记录第一当事方提供者的诊断.
  • uploads 记录上传准备、签名和完成.
  • mail 记录第一当事方提供者的邮件诊断.
  • payments 记录取出、门户、退款、以及来自 支付提供者.
  • entitlements 记录来自计费或计划状态的产品准入决定.
  • notifications 记录通知意向和渠道交付情况.
  • auth 记录来自第一当事方提供者的认证诊断.
  • audit 记录应用代码释放的经消毒的持久审计活动.
  • policies 记录申请授权政策决定.
  • rateLimit 记录率限制第一当事方提供者的诊断.
  • custom 记录应用和针对整合的诊断事件.

通过提供者配置监视器 :

createDevtoolsProvider({
  watchers: {
    requests: true,
    useCases: true,
    eventBus: false,
    jobs: false,
    outbox: true,
    schedules: true,
    db: true,
    payments: true,
  },
});

已禁用监视器不存储匹配事件 。 已安装的监视器元数据 可通过 ctx.ports.devtools.getWatchers() 和仪表盘API.

自定义集成还可以为自己的事件注册监视器元数据 类型。 自定义监视器视图在其拥有时出现在仪表板侧边栏 custom 事件:

createDevtoolsProvider({
  watchers: {
    search: {
      label: "Search",
      description: "Search query and indexing diagnostics.",
      eventTypes: ["custom"],
    },
  },
});

然后记录事件与 watcher: "search" 因此自定义监视器控制 是否被存储.

使用大小写工具

createUseCase(...) 从 @beignet/core/application 乐器每运行 默认 —— 不需要特定的编程 :

import { createUseCase } from "@beignet/core/application";

export const useCase = createUseCase<AppContext>();

每次运行都会解决仪器端口 ctx.ports (单位:千美元)ports.instrumentation,则 ports.devtools并读 ctx.requestId 财务报告和审定财务报表 跟踪上下文字段。 使用大小写 start, (中文(简体) ), end,以及 error 阶段共享 同样的跨度。 过 instrumentation: false 选择退出.

提供方仪器

第一当事方和应用一级供应商应使用 createProviderInstrumentation() 从 @beignet/core/providers 改为 取决于直接的devtools。 帮助对象接受端口对象或 仪器端口,记录通过 record(),并将提供者元数据添加到 自定义事件. @beignet/devtools 执行该仪器端口 何时 createDevtoolsProvider() 已注册.

当提供者在主动请求中记录事件时 运行时保留了请求的上下文,事件尚未包含 关联字段, devtools 添加活动 requestId, (中文(简体) ), traceId,以及 traceparent。这使供应商的工作与路线、钩和 使用时长而不使提供者取决于应用程序特定上下文 类型.

import {
  createProvider,
  createProviderInstrumentation,
} from "@beignet/core/providers";

export const searchProvider = createProvider({
  name: "search",
  setup({ ports }) {
    const instrumentation = createProviderInstrumentation(ports, {
      providerName: "search",
      watcher: "custom",
    });

    return {
      ports: {
        search: {
          async query(text: string) {
            const results = await runSearch(text);

            instrumentation.custom({
              name: "search.query",
              label: "Search query",
              summary: `${results.length} results`,
              details: { resultCount: results.length },
            });

            return results;
          },
        },
      },
    };
  },
});

使用内置监视器, 如 db, (中文(简体) ), cache, (中文(简体) ), storage, (中文(简体) ), mail, (中文(简体) ), payments, (中文(简体) ), flags, (中文(简体) ), entitlements, (中文(简体) ), auth, (中文(简体) ), audit, (中文(简体) ), policies, (中文(简体) ), rateLimit,或 schedules 何时 提供者属于这些类别之一。 使用 custom 或习惯 用于应用程序特定集成的监视器名称.

审计活动

长期审计日志仍应该通过您的应用程序来写 AuditLogPort。 。 。 . 使用 createInstrumentedAuditLog() 从 @beignet/core/ports 当您也 希望在本地编审时间表中进行静态审计活动 :

import { createInstrumentedAuditLog } from "@beignet/core/ports";

const audit = createInstrumentedAuditLog({
  audit: durableAudit,
  instrumentation: ports,
});

包装器首先记录耐用的审计条目, 然后显示自定义事件 属于 audit 监视器进入已解决的仪器端口。 开发工具 仍然是当地的一种诊断观点;它不是持久的审计库.

当审计端口为交易范围时, 仅在交易范围之后才会发出演示镜 交易承诺。 保持交易范围的审计端口持久 最好是对后来卷土重来的工作显示当地审计事件.

手工活动

使用 record() 用于特定应用活动。 它充满了 id 财务报告和审定财务报表 timestamp。 。 。 .

ctx.ports.devtools.record({
  type: "custom",
  watcher: "search",
  name: "search.query",
  label: "Search query",
  summary: "24 results in 18ms",
  details: {
    queryLength: query.length,
    resultCount: 24,
    durationMs: 18,
  },
});

log() 已完整时仍然可用 DevtoolsEvent。 。 。 .

终点

  • GET /api/devtools 服务于仪表板
  • GET /api/devtools/core/events 返回 JSON 事件
  • GET /api/devtools/stream 返回带有下列内容的动态服务器-事件流 每个连接的新快照
  • POST /api/devtools/clear 清除内存缓冲并配置存储

事件列表查询参数 :

  • type数字 : request, (中文(简体) ), error, (中文(简体) ), usecase, (中文(简体) ), eventBus, (中文(简体) ), job, (中文(简体) ), schedule, (中文(简体) ), provider,或 custom
  • requestId: 相关性 ID
  • traceId: W3C 跟踪标识
  • limit: 返回的最大事件,默认 200

配置

DEVTOOLS_ENABLED=true
DEVTOOLS_ENABLED=false
DEVTOOLS_MAX_EVENTS=1000
DEVTOOLS_PERSIST=true
DEVTOOLS_PERSIST_PATH=.beignet/devtools/core/events.jsonl

默认缓冲保留了最新的500个事件. 持久性是选入和使用 .beignet/devtools/core/events.jsonl 在没有自定义的情况下启用默认 路径.

提供者控制事件是否被记录. HTTP 路由控制 这些事件是否暴露。 路由处理器只有在 NODE_ENV === "development",但启用的路由仍然需要应用程序 authorize 默认调回。 取消设置、测试、预览、中继和生产 环境也需要 enabled: true数字 :

import { createDevtoolsRoute } from "@beignet/devtools";
import { getServer } from "@/server";

export const { GET, POST } = createDevtoolsRoute(
  async () => (await getServer()).ports.devtools,
  {
    basePath: "/api/devtools",
    enabled: process.env.DEVTOOLS_ENABLED === "true",
    authorize: async (req: Request) => {
      const session = await (await getServer()).ports.auth.getSession(req);
      return session?.user.id === process.env.DEVTOOLS_ADMIN_USER_ID;
    },
  },
);

若为 authorize 返回时 false,devtools 响应与 404如果返回一个 Response,该响应被使用,使应用程序返回自己的 403 或重定向反应.

浏览器请求带有 Origin 信头必须是同源; 授权不允许跨源浏览器请求 .

用于本地开发服务器, HTTP 收听器将完全绑定于 回放, 您可以故意省略认证 :

createDevtoolsRoute(devtools, {
  basePath: "/api/devtools",
  allowUnauthenticatedDevelopmentAccess: true,
});

此选项只在 NODE_ENV === "development" 请求 URL 用途 localhost页:1 *.localhost 名称, 127.0.0.0/8,或 [::1]。别使用它 与听众绑定 0.0.0.0,局域网接口,集装箱无障碍 接口,或主机开发环境。 获取 Request 揭露其 目标 URL, 不是请求者的网络地址, 所以主机名检查是 非对等认证 .

对嵌入式仪表板使用cookie/会话授权. 同样的起源 fetch 财务报告和审定财务报表 EventSource 请求包括 cookie, 但浏览器无法附加 应用程序定义的授权页眉 EventSource。 。 。 .

编辑

Devtools 使用共享的编辑助手 @beignet/core/ports 在此之前 事件被存储。 敏感密钥, 如 authorization, (中文(简体) ), proxy-authorization, (中文(简体) ), cookie, (中文(简体) ), set-cookie, (中文(简体) ), x-api-key, (中文(简体) ), accessKey, (中文(简体) ), jwt, (中文(简体) ), session, (中文(简体) ), token, (中文(简体) ), password, (中文(简体) ), secret,以及 credentials 替换为 [redacted]嵌入于字符串中的高度信任证书形状——包括: 持有者和基本证书,JWTs, 具有证书的URL, 秘密 任务和私人密钥——也被擦除,包括错误信息和 堆叠.

服务器请求仪器记录请求调试头, 但确实 默认情况下不记录请求或响应机构。 仪表板标记请求 修改敏感字段时的生命周期细节,并警告是否 密形元数据密钥在存储的事件中仍然可见.

您可以通过服务器添加自定义重排器 instrumentation 选项 :

const server = await createNextServer({
  // ...
  instrumentation: {
    redact: (event) => ({
      ...event,
      details: scrub(event.details),
    }),
  },
});

内幕商店也接受自定义设置的重置器:

const devtools = createInMemoryDevtools({
  redact: (event) => event,
});

API 密码

interface DevtoolsPort {
  log(event: DevtoolsEvent): void;
  record(event: DevtoolsEventInput): DevtoolsEvent;
  subscribe(listener: DevtoolsListener): () => void;
  getEvents(filter?: DevtoolsFilter): DevtoolsEvent[];
  getWatchers(): DevtoolsWatcher[];
  isWatcherEnabled(name: DevtoolsWatcherName): boolean;
  clear(): void | Promise<void>;
}
function createFileDevtoolsStore(options?: {
  filePath?: string;
  maxEvents?: number;
  compactEvery?: number;
}): DevtoolsEventStore;
function createProviderInstrumentation(
  target: ProviderInstrumentationTarget,
  options: {
    providerName: string;
    watcher?: string;
    redact?: (event: ProviderInstrumentationEventInput) => ProviderInstrumentationEventInput;
  },
): ProviderInstrumentation;
type DevtoolsEvent =
  | RequestEvent
  | ErrorEvent
  | UseCaseEvent
  | EventBusEvent
  | JobEvent
  | ScheduleEvent
  | ProviderEvent
  | CustomDevtoolsEvent;

所有活动包括: id, (中文(简体) ), timestamp选项 requestId选项 watcher, (中文(简体) ), 选项 traceId选项 spanId选项 parentSpanId选项 traceparent编辑 details。 。 。 .

请求/ error 抓取在服务器上配置, 不在此包中 。 见 页:1 instrumentation 选项 createServer(...) 内 @beignet/core/server数字 :

type ServerInstrumentationOptions<Ctx> = {
  requestIdHeader?: string | false; // default "x-request-id"
  traceContextHeader?: string | false; // default "traceparent"
  ignorePaths?: readonly string[]; // default ["/api/devtools"]
  redact?: (
    event: ProviderInstrumentationEventInput,
  ) => ProviderInstrumentationEventInput;
  shouldCapture?: (args: {
    req: HttpRequestLike;
    ctx?: Ctx;
    contract: HttpContractConfig;
    response: HttpResponseLike;
    error?: unknown;
  }) => boolean;
};

createDevtoolsRoute() 财务报告和审定财务报表 handleDevtoolsRequest() 接受:

type DevtoolsRequestOptions = {
  basePath: string;
  enabled?: boolean;
  allowUnauthenticatedDevelopmentAccess?: boolean;
  authorize?: (
    req: Request,
  ) => boolean | Response | Promise<boolean | Response>;
};

生产安全

HTTP 处理器只有在 NODE_ENV === "development"但他们 隐藏不包含 authorize 或明确的本地开发 选入. 设置 enabled: true 在另一个环境中 永远不会激活 未经认证的选入。 提供者还在其中安装一个不开放的devtools端口 默认生产,所以应用代码不需要无效检查.

载有 Origin 页眉必须匹配请求的 URL 来源 . 将其作为浏览器的保障,而不是代替授权.

Devtools可以包含敏感的请求,错误,和域数据. 放在当地 除非您有意添加认证和编辑.

发展

仪表盘UI是一个反应应用程序在 ui/。 。 。 . bun run build:ui 编译为 将一个自成一体的 HTML 文件作为生成模块嵌入到软件包中 (单位:千美元)src/ui-html.generated.ts,被指为; bun run build 运行 build:ui 财务报告和审定财务报表 然后TypeScript构建。 从一个新的克隆,运行 bun run build 曾经 直接运行此软件包的测试 — root bun run test 处理 通过涡轮来订购.

许可证

麻省理工学院

版本与发布记录

@beignet/devtools 共发布 65 个版本,首次发布于 2026/05/27;过去 12 个月发布了 65 个版本。

版本发布日期距今
0.0.65latest2026/11/08今天
0.0.642026/11/034 天前
0.0.632026/11/026 天前
0.0.622026/11/017 天前
0.0.612026/11/017 天前
0.0.602026/11/017 天前

关于 @beignet/devtools 的常见问题

@beignet/devtools 是什么?

Beignet的开发时间演示工具 - 服务器运行时间的小型望远镜

如何安装 @beignet/devtools?

在项目目录运行 npm install @beignet/devtools,或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖:@beignet/core(>=0.0.3 <1.0.0)。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖,Yarn 需要手动安装。

@beignet/devtools 支持 TypeScript 吗?

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

@beignet/devtools 支持 ESM 还是 CommonJS?

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

@beignet/devtools 需要什么版本的 Node.js?

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

@beignet/devtools 可以商用吗?

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

@beignet/devtools 的下载量有多少?

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

@beignet/devtools 还在维护吗?

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