@brunyee-studio/onus-sdk (英语)

Onus 官方浏览器 SDK 错误、 会话重放、 自定义事件和网络分析 它与Onus信封终点站交谈(/api/{ingest_project_id}/envelope/)并抓取API(/api/{projectId}/analytics/batch/) (中文(简体) ). 信封端点也接受一个已存在的Sentry SDK不变,分析师调用镜像 PostHog 的核心调用,因此一个已存在的PostHog 集成端口无需重写调用站点即可被取用.

安装

pnpm add @brunyee-studio/onus-sdk

分析包内的船只——独立 @brunyee-studio/onus-analytics 软件包已删除。 从 页:1 @brunyee-studio/onus-sdk/analytics 子路径( 见 网络分析 页:1.

import { init, captureException, setReplayCaptureAllowed } from '@brunyee-studio/onus-sdk';

init({
  dsn: 'https://<public-key>@<ingest-host>/<numeric-project-id>',
  release: '1.0.0',
  environment: 'production',
  // Configure replay; recording waits for explicit host authorization:
  replays: { sampleRate: 1 },
});

// Only after the host has determined capture is authorized:
await setReplayCaptureAllowed(true);

try {
  risky();
} catch (e) {
  captureException(e);
}

DSN在设计上是公开的;滥用是通过利率限制和可选的每个键源允许列表处理服务器侧. 缺少或变形的 DSN 从未丢出: 每一个切入点(init,分析 init, (中文(简体) ), startSessionReplay, (中文(简体) ), ./node, (中文(简体) ), ./next, (中文(简体) ), ./pino记录 a console.warn,禁用网络发送并保持应用程序运行,每个抓取,日志和分析呼叫都成为了禁用.

应用框标识( :allowUrls 编号 : denyUrls(中文(简体) )

默认, captureException 使用同样来源的应用中标记堆栈框架 高度:相对/空径和同源URL是应用程序代码,其他 绝对起源是第三方。 两个 init 选项缩小或扩展此选项:

init({
  dsn,
  allowUrls: ['app.example.com', /\/static\/chunks/], // strings match by substring, RegExp by test
  denyUrls: ['/vendor/'], // always excludes, even when allowUrls matches
});

• allowUrls (非空) 标记只匹配 app中的帧; denyUrls 永远 标记匹配框架退出应用,优先于 allowUrls。 。 。 .
• 空数组行为为“ 未设置 ” (返回到同一来源) heuristic);非阵列值被忽略.
• 适用于 captureException 仅限路径——有效载荷传递到 captureEvent 没有自动标记.

服务器散列上只有程序框分组出错, 所以跨源供应商 噪音不能分散组合。 捆绑 webpack:// 框架(包括 node_modules 路径)默认情况下仍然在应用中被标记——使用 denyUrls 改为 把他们排除在外。 无应用框的堆叠倒回倒置所有框.

会话重放

二道所录. 自动启动( 建议) - 通过一个 replays 块到 init(); 录音推迟到主机呼叫时进行 setReplayCaptureAllowed(true) 在其本身的法律/CMP决定之后。 SDK的内幕授权开始 每页会话都关闭,而且永远不会持续。 经批准, 默认情况下,每个会话记录和抽样都是选择下限的:

init({
  dsn,
  replays: {
    sampleRate: 1, // fraction of sessions recorded (default 1 = all users)
    // sessionId: () => analytics.get_session_id(), // link playback to analytics sessions
  },
});
await setReplayCaptureAllowed(true); // Only after host authorization
// On withdrawal: stop without flushing unsent events, abort in-flight sends,
// and remove the replay id from future errors.
await setReplayCaptureAllowed(false);
// Re-grant re-runs the configured auto-start (including sampling) and, if
// selected, starts a fresh recording with a new replay id.
await setReplayCaptureAllowed(true);

事后发现的错误 contexts.replay.replay_id 自动 - 没有额外的接线。 一旦Onus接受第一首录音 就会开始连接 片段( 页面快照播放从开始), 因此错误从不指向 无法播放的重放; 在此之前捕获出的错误没有带重放 ID 。 补助金在开放时具有独家能力;退出后,提供新的补助金 重新运行最新 init({ replays }) 配置, 而重新初始化 无 replays 删除已停放的自动启动. enabled: false (或省略 )选择完全退出.

现有人工呼叫者的行为变化 : 一个直接 startSessionReplay() 现在决定 null 直到主机明确调用 setReplayCaptureAllowed(true)。退出即刻停止记录,不 尾冲,取消飞行中的请求,并清除出错的qq重播链接. 重新赠与允许进行新的人工录音;它从未恢复撤回的录音.

隐私默认( 总是在)

捕捉默认是安全的隐私, 和面具发生 运输前 (SDK在rrweb序列化任何内容之前和任何内容之前解决口罩) 片段离开页面 :

• 非密码字,类似文本的输入值通过强制口罩映射被遮蔽 (单位:千美元)maskAllInputs; 密码值为 永远 蒙上面纱,不能 解开面具.
• 普通 DOM 文本节点默认被遮蔽( NamemaskTextSelector: '*') (中文(简体) ).
• input[type="hidden"], (中文(简体) ), input[type="radio"],以及 input[type="checkbox"] 要素是: 完全封锁 默认: rrweb 隐藏路径跳过 这些类型(隐藏值和无线电/检查框) value 属性 ),并且其检查状态不会被重播.
• 标记了子树 data-onus-private 被完全封锁.
• 摄像头 横跨原生地的 Iframe 摄像头 内线影像不动.
• 已录制的页面 URL 省略了查询字符串,片段,以及证书.

未洗过的: 遮盖输入值, 普通 DOM 文本 节点和被封锁的子树 管理部 属性 (例如要件) title 或 href 锁定的属性),图像 URL, <style> 编号 : 样式表文本 (由rrweb序列化为: _cssText外边 maskTextSelector 隐藏路径)和非回放有效载荷被记录 逐字记录。 主机必须用 data-onus-private (或 privacy.blockSelector)并审查敏感路线和每个数据路径 之前允许在生产中重放.

每集成一次淘汰

通过一个打字 privacy 对象( 手工 startSessionReplay 或 replays 故意放松非密码口罩 以达到这个目的. privacy 旗子总能取胜 recordOptions 传球,还有 敌对 recordOptions 永远无法击败蒙面,启用画布/框架 抓取,替换SDK的 emit,或通过rrweb预包装事件 packFn编号 :plugins (被剥去的:在SDK发射前跑出并 能够绕过 Meta href sanitization. 空的、 空白的或 CSS 无效的 选择器返回到安全默认处, 而不是损坏掩码( rrweb) 2.1.1 无声记录在无效选择器上被揭发). privacy.blockSelector 实值 添加剂: 它 EXTENDS 内置块列表 —— 它永远无法删除 默认块( e)data-onus-private,隐藏,收音机,和复选框输入). 没有 privacy: false 方便开关. URL 最小化意味着敏感数据必须永远不要 活在路径中——主机也应屏蔽敏感的子树:

import { init, setReplayCaptureAllowed } from '@brunyee-studio/onus-sdk';
import { startSessionReplay } from '@brunyee-studio/onus-sdk/replay';

// Strict default — everything masked (after authorization):
await setReplayCaptureAllowed(true);
await startSessionReplay({ dsn });

// Selective text opt-down — only mask text inside a known-sensitive area:
init({
  dsn,
  replays: {
    privacy: { maskTextSelector: '.sensitive-area' },
  },
});

// Extra blocked subtree — privacy.blockSelector ADDS to the built-in block
// list; [data-onus-private], input[type=hidden], input[type=radio] and
// input[type=checkbox] stay blocked:
init({
  dsn,
  replays: {
    privacy: {
      blockSelector: '.payment-form',
      ignoreSelector: '.skip-recording',
    },
  },
});

手动控制仍然通过单独的切入点工作 :

import { setReplayCaptureAllowed } from '@brunyee-studio/onus-sdk';
import { startSessionReplay, stopSessionReplay } from '@brunyee-studio/onus-sdk/replay';

await setReplayCaptureAllowed(true); // Manual starts also require authorization.
const replayId = await startSessionReplay({ dsn, environment: 'production' });
// Errors carry contexts.replay.replay_id once the first segment is accepted.

rrweb 是一个 可选同伴依赖 ——录音机捆绑只在录音实际开始时才懒散地装入,因此禁用回放的应用程序从不下载. 重放片段作为配对发布 replay_event + 键 replay_recording 封装物品(gzipt)与摄入路线和私人存储桶所期望的完全一致。 第一段(rrweb Meta + FullSnapshot)一拍即发;后段分批分送 segmentIntervalMs (违约5000)或 maxEventsPerSegment 事件(默认 100)。 片段发送重试网络错误,408,429和5xx至3次尝试并封顶回放;其他4xx回复则没有重试. 每个录相机在上传前被粘住( 在哪里) CompressionStream ),因此它是被压缩而存储的. 重播结束于 idleTimeoutMs 没有用户输入( 默认 5分钟) 或一次是 maxReplayDurationMs 长 (默认和最长为60分钟; 摄入会减少后段); 下一个用户输入会开始新的重放, 所以一个未注意的标签会停止记录 。 按球队保留赛设置的回放到期(默认为90天).

日志

结构化日志到 Onus 日志查看器为 log 信封项目。 打开 带有 logs 块; 没有一块, logger 电话什么也不做.

import { init, logger } from '@brunyee-studio/onus-sdk';

init({
  dsn: 'https://<key>@onus.example/<projectId>',
  release: '[email protected]',
  logs: {
    minLevel: 'info', // default 'trace'
    captureConsole: ['warn', 'error'], // also send these console calls
    sessionId: () => analytics.get_session_id(),
  },
});

logger.info('checkout started', { cartItems: 3, tier: 'pro' });
logger.error(logger.fmt`payment ${orderId} failed after ${attempts} tries`);

• 级别 : trace, (中文(简体) ), debug, (中文(简体) ), info, (中文(简体) ), warn, (中文(简体) ), error 财务报告和审定财务报表 fatal。 。 。 .
• 属性 : 字符串、数字和布林,在线上输入。 其他值为JSON-字符串.
• logger.fmt数字 : 保留信件模板及其参数为属性,因此类似行组在一起.
• 自动上下文 : 环境, 发布, SDK 名称和版本, 活动重放 id, session.id,以及没有查询字符串或碎片的页面 URL.
• 交付 :
  • 每封信封高达100个记录(和约512个KiB),默认每5个秒发送,或一批封装后立即发送.
  • 当页面被隐藏或卸下时,缓冲记录会随 sendBeacon。 。 。 .
• 限制和失败:
  • 最多保存了1 000份未发送的记录,最古老的记录首先被删除.
  • A 类 429 暂停发送 Retry-After其他故障以指数方式回落到60秒.
  • 被丢弃的记录在客户报告中被计算并报告给Onus.
  • 伐木工从不扔.
• 套装大小 : 核心条目中的伐木船。 导入它永远不会在重放或分析码中拉出.

追踪@brunyee-studio/onus-sdk/tracing(中文(简体) )

浏览器跟踪: a pageload 根, a 键 navigation 根/ SPA 路由变化, 还有一个 http.client 儿童间距/ 每名 fetch编号 :XMLHttpRequest每一个根被发送 作为一体 transaction 信封项并显示在 Traces 页面上.

import { init } from '@brunyee-studio/onus-sdk';
import { startBrowserTracing } from '@brunyee-studio/onus-sdk/tracing';

init({ dsn: 'https://<key>@onus.example/<projectId>', environment: 'production' });
const tracing = startBrowserTracing({
  tracesSampleRate: 0.1, // default 1
  service: 'web', // default 'browser'
  tracePropagationTargets: ['https://api.example.com', /^https:\/\/[a-z]+\.example\.com\//],
});
// tracing?.stop() removes every patch.

• 需求 init() 先说. startBrowserTracing 返回时 null 当 SDK 没有有效的 DSN 或追踪已经启动时.
• 根数 : 根结束于其最后一次请求完成后 1 s ()idleTimeoutMs),最多为30 s后(finalTimeoutMs),在下一个导航上,或 pagehide。请求尚未打开,然后发出状态 cancelled开始于 performance.timeOrigin。 。 。 .
• 导航 : history.pushState编号 :replaceState 财务报告和审定财务报表 popstate; 只有路径名更改才开始新的根。 在更改 URL 之前获取下一页的路由器应该调用 startNavigation(url) 当导航开始时,这些请求(并且服务器横跨它们)会在新页面的跟踪中降落;随后的历史变化不会为同一路径启动第二个根. startNavigation 追踪未运行时是禁用.
• 根与根之间的请求 : 在没有根端时(在上个根结束之后)提出的请求会随着上个根端的采样决定而获得新的痕量标识,所以一个已结束的痕量永远不会继续增长.

Next.js App 路由器在下页的有效载荷之前获取 pushState,所以打电话 startNavigation 从 instrumentation-client.ts数字 :

// instrumentation-client.ts
import { startNavigation } from '@brunyee-studio/onus-sdk/tracing';

export function onRouterTransitionStart(url: string) {
  startNavigation(url);
}

• 请求跨度 : 名称 METHOD /path,与 http.request.method, (中文(简体) ), url.full (无查询或片段)和 http.response.status_code。状态 \\ 500 或网络错误为 internal_error对SDK自己摄入路线的要求永远无法追查.
• traceparent 传播 : 默认情况下, 只有同源请求才能得到信头, 因此 CDNs 和第三方 永远不会看到你的跟踪 ID . tracePropagationTargets 替换默认 : RegExp 用绝对 URL 进行测试; 字符串为绝对 URL ()https://api.example.com)仅在该确切来源上与前缀相匹配;路径字符串(/api/)只匹配路径始于它的同源请求;任何其他字符串都是主机(api.example.com, (中文(简体) ), localhost:3000)与主机或其子域相匹配,从不象像 api.example.com.evil.net。字符串在 URL 的子字符串上永远不匹配,所以一个有路径的主机(api.example.com/v1)或协议相对字符串(//cdn.example.com)从不匹配任何东西:使用完整的URL(https://api.example.com/v1)或RegExp. tracePropagationTargets: [] 完全关闭传播。 现有 traceparent 永远不会被覆盖.
• 抽样: 确定每个根一次。 未被采样的根没有发出任何信号,但仍会传播 traceparent 有旗帜 00,因此服务器可以尊重决定.
• 关联性 : 在追踪运行时, logger 记录带有活动 trace_id 并记录错误 contexts.trace。核心条目只保留一个微小的跟踪记录,而不是跟踪器。 每个回放片段列出自前一段以来开始或传播的痕迹为: trace_ids,所以重播的日志侧边栏也显示了你的后端对这些痕迹的行.
• 套装大小 : 其自己的子路径,没有OpenTeleometry依赖。 从未导入其下载的应用程序 .

节点( E)@brunyee-studio/onus-sdk/node(中文(简体) )

pnpm add @brunyee-studio/onus-sdk @opentelemetry/api @opentelemetry/api-logs @opentelemetry/core \
  @opentelemetry/otlp-transformer @opentelemetry/resources @opentelemetry/sdk-logs

import { init, logger, captureException, flush } from '@brunyee-studio/onus-sdk/node';

init({
  dsn: process.env.ONUS_DSN,
  service: 'api',
  environment: 'production',
  release: '1.4.0',
});
logger.info('order placed', { orderId });
captureException(err); // error event with contexts.trace from the active span
await flush(); // before a serverless function returns

• 日志从OTLP/JSON到 /api/{projectId}/otlp/v1/logs,分批(≤512个记录, 1 s),并被拆分到1个米B请求上限下。 DSN的钥匙一定有 无允许来源列表,因为服务器发送者没有源头.

• logLevel (默认) info过滤器 logger.* 并控制台捕获. captureConsole: ['warn', 'error'] 镜像那些控制台的方法.

• 记录带有活性的OpenTeleometry跨度.

• 追踪 是它的子道, @brunyee-studio/onus-sdk/node/tracing,所以只发送日志和错误的应用程序就不需要其两个额外的软件包. 添加 @opentelemetry/sdk-trace-base @opentelemetry/context-async-hooks 转到安装行并传递 onusTracing 改为 init数字 :

  import { init } from '@brunyee-studio/onus-sdk/node';
  import { onusTracing } from '@brunyee-studio/onus-sdk/node/tracing';
  
  init({
    dsn: process.env.ONUS_DSN,
    service: 'api',
    tracing: onusTracing({ tracesSampleRate: 0.1 }),
  });
  

  init 然后登记一个全局跟踪器提供者、一个Async上下文管理器和W3C traceContext 在OTLP/JSON至 /api/{projectId}/otlp/v1/traces (批量处理、gzip和后退作为日志) 无 tracing 没有注册的追踪器,请携带它@opentelemetry/sdk-node) (中文(简体) ). 抽样基于父方: 正在接收 traceparent 决定(所以浏览器的被抽取出微量保留在外),只有根跨度使用 tracesSampleRate (单位:千美元). ignoreSpanPaths: /\/health/ 从未对名称或 http.target编号 :url.path编号 :http.route编号 :next.route 火柴。 比赛。 出口者自己的要求被查封,因此它们从未成为期限.

• 没有 HTTP 自动仪器的服务器加入呼叫者的追踪 continueTrace(headers, name, fn)数字 : fn 在活动中运行 SERVER 以请求为父的间距 traceparent,并记录了一次掷出.

  import { continueTrace } from '@brunyee-studio/onus-sdk/node';
  
  app.get('/orders', (req, res) =>
    continueTrace(req.headers, 'GET /orders', async () => res.json(await listOrders())),
  );
  

• init 不替换已注册的全局OTel日志提供者: OTel API 保存了第一个并忽略了以后的注册, 所以 logger 记录将交给提供商而不是Onus(误捕不受影响)。 如果您的应用程序已经注册( 例如 ) . @opentelemetry/sdk-node 和日志处理器一起通过 ./pino 运输,通过自己的供应商而不是全球供应商出口 registerOnus 从 ./next 成为记录OTel的.

• 打开 429编号 :503 暂停 Retry-After 并减少批量,直到那时。 被拒绝的密钥或项目( E)401编号 :403编号 :404,例如带有允许来源列表的密钥)暂停转发10分钟。 没有东西扔进你的应用程序.

皮诺( pino) (@brunyee-studio/onus-sdk/pino(中文(简体) )

添加 pino-abstract-transport 到节点安装行.

const log = pino({
  transport: {
    targets: [
      { target: 'pino/file', options: { destination: 1 } }, // keep stdout
      {
        target: '@brunyee-studio/onus-sdk/pino',
        options: { dsn: process.env.ONUS_DSN, service: 'api' },
      },
    ],
  },
});

运输以皮诺的工人线为主,并自行出口. 皮诺拒绝自定义 formatters.level 合并 transport.targets,且运输同时接受数字级别和级别标签。 线条保留 trace_id编号 :span_id (例如来自 @opentelemetry/instrumentation-pino)作为记录的微量上下文.

若为 ./node init (或 ./next registerOnus) 已运行在进程, 使用 createOnusPinoStream({ exclude? }) 作为 pino.multistream 取而代之的是目的地。 它通过提供商传播.

温斯顿( r)@brunyee-studio/onus-sdk/winston(中文(简体) )

添加 winston-transport 到节点安装行,并调用 init 从 ./node 先说.

import { OnusWinstonTransport } from '@brunyee-studio/onus-sdk/winston';

const log = winston.createLogger({
  transports: [new winston.transports.Console(), new OnusWinstonTransport()],
});

npm 和 syslog 都将映射到OTel断层,元数据成为属性,记录带有活性跨度.

下册.js@brunyee-studio/onus-sdk/next(中文(简体) )

添加 @vercel/otel 到节点安装行,以及 @opentelemetry/sdk-trace-base 如果设置 tracesSampleRate。 。 。 .

// instrumentation.ts
import { registerOnus } from '@brunyee-studio/onus-sdk/next';

export const register = () =>
  registerOnus({ dsn: process.env.ONUS_DSN, service: 'web', environment: process.env.VERCEL_ENV });
export { onRequestError } from '@brunyee-studio/onus-sdk/next';

在节点运行时此登记簿 @vercel/otel (请求跨度)与 Onus 日志处理器(以及 tracesSampleRate,与 Onus 取样器和处理器并列 @vercel/otel属于自己的 'auto' 处理器),所以 logger, (中文(简体) ), createOnusPinoStream 财务报告和审定财务报表 OnusWinstonTransport 通过它输出。 一次 registerOnus 已经运行, captureException 财务报告和审定财务报表 logger 从 ./node 来自应用程序中任何模块的工作(程序处理器、服务器动作、服务器组件);您不调用 init。 。 。 . onRequestError 抓取路径和活性跟踪的未处理错误。 在边缘运行时只登记了追踪,请求错误被写成 JSON 的一行 trace_id编号 :span_id。 。 。 .

运输语义

• POST 信封装有 X-Sentry-Auth (单位:千美元)sentry_key =你的公用钥匙).
• Gzips 身体通过 CompressionStream 当可用时;摄入路线会嗅出魔法字节并接受身份体.
• 荣誉 429 + 键 retry-after 带有上限后退(按键率限制).
• 覆盖在服务器的盖子上 (gzip后有1个MiB在线上,10个MiB被充气) 被丢弃客户端.
• navigator.sendBeacon 可在卸货时交货?sentry_key= 查询回落,因为信标不能设置信头).

抖树调试旗( D)

• 只导入您使用的内容; 回放记录器被隔离于 @brunyee-studio/onus-sdk/replay。 。 。 .
• 已知限制 : 不混合常见JS require('@brunyee-studio/onus-sdk') 无害环境管理的进口 /replay 一页的子路径 。 两座建筑可以 创建单独的模块实例, 带有单独的内存授权门 状态。 在SDK两个切入点使用一个模块系统直至 双相兼容性已经解决.
• 除错日志在编译时旗后被锁定 __ONUS_DEBUG__在生产捆绑机中剥去:

// webpack
new webpack.DefinePlugin({ __ONUS_DEBUG__: false });
// esbuild / tsup
define: {
  __ONUS_DEBUG__: 'false';
}

浏览器支持

要求数 crypto.randomUUID 或者说 crypto.getRandomValues (事件编号), fetch,可选择 CompressionStream (gzip) / (英语) navigator.sendBeacon (卸载快递). 更古老的浏览器轻而易举地降解:身份体而非gzip,取出而非信标.

版本策略 : 我们支持目前主要路线的修复.

出版

@brunyee-studio/onus-sdk 通过与下列相同的语义释放管道释放: packages/cli。仅限 dist/ 财务报告和审定财务报表 README.md 现予公布(files 内 package.json) (中文(简体) ).

网络分析@brunyee-studio/onus-sdk/analytics(中文(简体) )

产品分析表面init 编号 : capture 编号 : identify 编号 : alias 编号 : register 编号 : reset 编号 : get_distinct_id 编号 : get_session_id)上取取取取取API. 核心调用匹配 已有的 PostHog 集成,所以调用站点端口无需重写 . 从自己的子路径导入它, 所以应用程序只需要错误跟踪, 永远不会下载 分析码 副路径仅为无害环境管理(import 条件,像 ./replay页:1 软件包是 sideEffects: false,所以捆绑者放弃任何不导入的功能集.

import { init } from '@brunyee-studio/onus-sdk/analytics';

const onus = init({
  // Flat ingest DSN from your team's keys panel (public by design).
  dsn: 'https://<token>@<ingest-host>/<ingest-project-id>',
});

onus.capture('cta_click', { button: 'hero' });

或有明确部分:

init({ apiKey: '<token>', apiHost: 'https://app.onus.dev', projectId: 42 });

API 密码

行为说明

• 会议 是客户端uuidv7的ID,通过本地Storage在标签上共享, 闲作30分钟后旋转,或共计24小时.
• 持久性 偏好本地Storage, 当被封锁时会降解为内存 (Safari私人模式). Cookie 持久性被故意不支持于 v1 (同意地表+4KB预算).
• 页数: 缓冲事件 sendBeacon 打开 pagehide,带有 保存状态 fetch 倒计时.
• 检索: 瞬态失败( 5xx/ network) 用指数重试 在4次尝试后退后和下降; 4xx回复被确认,从未 再审——服务器的费率限制决定是权威的.
• 限制费率:客户端标志桶(默认为10起事件/s,爆破为10x); 过度事件是在当地放弃的,而不是429起损害终点.
• 数字数字 : capture 当 navigator.doNotTrack 设置和 respectDnt 真实( 默认) .
• before_send 在退出浏览器前接收每个事件; 返回 null 放弃它.
• 自动抓取数字 : $pageview + SPA 历史变化, $pageleave, (中文(简体) ), 财务报告和审定财务报表 $autocapture 点击/提交带有元素链并 data-onus-capture-attribute-* 财产通过.