@blueking/open-telemetry 0.0.22 → 0.0.24

package/skills/bk-rum-otele/references/performance.md

@@ -0,0 +1,197 @@
+<!-- 本文件由 packages/open-telemetry/scripts/gen-skill-references.mjs 从 wikis 自动生成，请勿手改。 -->
+
+# Web Vitals 与 Long Task
+
+性能能力把浏览器提供的核心体验指标和主线程阻塞转换为原始 Span。`webVitals` 默认开启；`longTask` 默认关闭。SDK 不创建 Histogram，分布和分位数由服务端从原始值派生。
+
+## Web Vitals 总览
+
+`browser.web_vital` 覆盖：
+
+| 指标 | `vital.metric` | 单位 | 当前采集方式 |
+| --- | --- | --- | --- |
+| Cumulative Layout Shift | `cls` | 无量纲 | 每个 SDK View 独立计算 session window |
+| First Contentful Paint | `fcp` | ms | `web-vitals/attribution` |
+| Interaction to Next Paint | `inp` | ms | 每个 SDK View 维护交互候选近似 p98 |
+| Largest Contentful Paint | `lcp` | ms | `web-vitals/attribution` |
+| Time to First Byte | `ttfb` | ms | `web-vitals/attribution` |
+
+插件通过动态 import 加载 `web-vitals/attribution`。加载失败只禁用该插件；`debug=true` 时输出 warning，不影响其他采集。
+
+## 公共 Vital 字段
+
+每条 Vital Span 包含：
+
+- `vital.metric`
+- `vital.value`
+- `vital.rating=good|needs-improvement|poor`
+- `vital.id`
+- `span_type=vital`
+- `outcome.type=success`，仅 rating=good
+- `outcome.type=warning`，其他 rating
+
+Vital Span 是瞬时 INTERNAL Span。非法 `NaN`、`Infinity` 不上报。
+
+## Navigation Type
+
+优先使用 web-vitals metric 的 `navigationType`；否则读取首个 `PerformanceNavigationTiming.type`，并把 `back_forward` 规范为 `back-forward`。可能值包括：
+
+- `navigate`
+- `reload`
+- `back-forward`
+- `back-forward-cache`
+- `prerender`
+- `restore`
+- `unknown`
+
+## FCP、LCP 与 TTFB 的 View 归属
+
+这三类指标使用第一个 Performance Entry 的真实发生时间回查历史 Runtime Context。因此即使路由已经切换，较晚回调的初始导航指标仍会归到发生时的旧 View，而不是当前 View。
+
+Attribution 字段：
+
+| 指标 | 字段 |
+| --- | --- |
+| LCP | `vital.lcp.url`、`target`、`element_render_delay`、`resource_load_duration`、`time_to_first_byte` |
+| FCP | `vital.fcp.time_to_first_byte`、`load_state` |
+| TTFB | `vital.ttfb.waiting_duration`、`dns_duration`、`connection_duration`、`request_duration` |
+
+LCP URL 经过 `redactUrl`；DOM target 等字段可能包含高基数或业务语义，应纳入隐私审查。
+
+## 每个 View 的 CLS
+
+SDK 不直接使用整页生命周期累计的 web-vitals CLS，而是按 SDK View 重新计算：
+
+- 忽略 `hadRecentInput=true` 的 Layout Shift；
+- 相邻 Shift 间隔小于 1 秒且窗口总长小于 5 秒时进入同一 session window；
+- 取所有 session window 中累计值最大的一个；
+- 数值保留四位小数；
+- 记录该窗口中最大的单次 Shift 及目标元素；
+- View 结束时发送一条 CLS Span，即使值为 0。
+
+Rating 阈值：
+
+- `<= 0.1`：good
+- `<= 0.25`：needs-improvement
+- `> 0.25`：poor
+
+Attribution：`vital.cls.largest_shift_target`、`vital.cls.largest_shift_value`。通过 web-vitals 原生指标产生时还可能带 `vital.cls.load_state`。
+
+## 每个 View 的 INP
+
+SDK 使用 Event Timing Observer，`durationThreshold=40`：
+
+1. 按 interactionId 合并同一次交互，只保留 duration 最大 Entry。
+2. duration 上限保护为 60,000ms。
+3. 保留当前 View 最慢的 10 个候选。
+4. 优先使用浏览器 `performance.interactionCount` 估算总交互数。
+5. 浏览器不提供时，根据 interactionId 范围近似交互数。
+6. 取排序候选中接近 p98 的位置，而不是简单最大值。
+7. View 没有有效 Interaction 时不发送 INP Span。
+
+Rating 阈值：
+
+- `<= 200ms`：good
+- `<= 500ms`：needs-improvement
+- `> 500ms`：poor
+
+Attribution：
+
+- `vital.inp.interaction_target`
+- `vital.inp.interaction_type`
+- `vital.inp.input_delay`
+- `vital.inp.processing_duration`
+- `vital.inp.presentation_delay`
+
+Target 优先读取 `data-bk-action-name`、`aria-label`、`name`，否则使用标签名。
+
+## SPA 语义
+
+FCP、LCP、TTFB 本质上仍主要来自文档导航；CLS 和 INP 按 SDK View 划分，适合 SPA 路由。View 名称变化只更新当前 Vital Runtime Attributes，不会清空当前 CLS/INP；创建新 View 才会 finalize 旧值并重置。
+
+## Long Task 启用
+
+```ts
+tracking: {
+  longTask: {
+    threshold: 50,
+  },
+}
+```
+
+阈值默认为 50ms；有效的非负有限值生效，非法值回退 50。浏览器 Performance API 通常本身只产生超过 50ms 的 Entry，把阈值设得更低不保证获得更多数据。
+
+## API 选择与降级
+
+插件按优先级只观察一种 Entry：
+
+1. 浏览器支持 `long-animation-frame`：使用 LoAF。
+2. 否则支持 `longtask`：使用 Legacy Long Tasks。
+3. 都不支持：跳过插件，不抛业务异常。
+
+不会同时观察两种 API，因此不产生重复 Span。初始化时 buffered entries 先合并到下一个宏任务处理，等待 Session/View 上下文就绪。
+
+## Long Task Span
+
+每条合格 Entry 生成 `browser.long_task` INTERNAL Span，Span 持续时间等于浏览器 Entry duration：
+
+- `long_task.id`
+- `long_task.entry_type=long-animation-frame|long-task`
+- `long_task.duration`
+- `long_task.name`
+- LoAF 的 `long_task.start_time`
+- LoAF 原生 `long_task.blocking_duration`
+- LoAF 的 `long_task.first_ui_event_timestamp`
+- LoAF 的 `long_task.render_start`
+- LoAF 的 `long_task.style_and_layout_start`
+
+Span 开始时间是 `performance.timeOrigin + entry.startTime`。该 Span 也会通知 Action Activity，使活动中的 Action 能关联此 Long Task。
+
+## LoAF 脚本 Event
+
+LoAF 每个脚本写为 `long_task.script` Span Event：
+
+- `long_task.script.duration`
+- `long_task.script.execution_start`
+- `long_task.script.forced_style_and_layout_duration`
+- `long_task.script.invoker`
+- `long_task.script.invoker_type`
+- `long_task.script.pause_duration`
+- `long_task.script.source_char_position`
+- `long_task.script.source_function_name`
+- `long_task.script.source_url`，经过 URL 脱敏
+- `long_task.script.start_time`
+- `long_task.script.window_attribution`
+
+Event 时间使用脚本自己的 `performance.timeOrigin + startTime`。
+
+## Legacy Attribution Event
+
+Legacy Long Tasks 的每条 attribution 写为 `long_task.attribution` Span Event：
+
+- `long_task.attribution.index`
+- `long_task.attribution.container_id`
+- `long_task.attribution.container_name`
+- `long_task.attribution.container_src`，经过 URL 脱敏
+- `long_task.attribution.container_type`
+- `long_task.attribution.name`
+
+Legacy API 不提供可靠 blocking duration，SDK不会从总 duration 猜测。
+
+## 成本与隐私
+
+Long Task 会为每个 Entry 建 Span，并可能附带多个脚本 Event；在主线程问题严重的应用中数据量可观。建议结合 Session 采样开启。
+
+脚本 URL、函数名、Invoker 和 DOM target 可能暴露内部路径或业务命名。URL 会走 `redactUrl`，所有 Long Task Event attributes 在写入前还会经过 `redactAttributes`。`tracking.beforeSend` 只暴露 Span 顶层 attributes，不能修改这些 Span Event。
+
+## 常见问题
+
+### 没有 Long Task 数据
+
+在控制台检查 `PerformanceObserver.supportedEntryTypes`。不支持两种 API时是正常降级；还要确认插件已开启、Session 被采样、存在有效 View、Entry duration 达到阈值。
+
+### CLS/INP 只在切换页面后出现
+
+CLS/INP 在 View finalize 时发送；当前 View 通常在下一次路由、pagehide、Session 过期或 shutdown 时结束。需要调试最终值时可以触发一次 View 切换或 `await bkOT.shutdown()`。
+
+完整字段见[遥测字段字典](./telemetry-reference.md#web-vitals-字段)和[Long Task 字段](./telemetry-reference.md#long-task-字段)。

package/skills/bk-rum-otele/references/privacy.md

@@ -1,109 +1,278 @@
 <!-- 本文件由 packages/open-telemetry/scripts/gen-skill-references.mjs 从 wikis 自动生成，请勿手改。 -->
 
-# 隐私与公共属性
+# 隐私、Consent 与字段治理
 
-RUM 数据常包含 URL、用户标识、接口路径、错误信息和业务属性。SDK 不会替接入方猜测哪些字段敏感，因此提供 `privacy` 和 `context` 两类入口，由业务显式控制。
+浏览器 RUM 天然接触 URL、错误信息、页面文本、用户标识和业务属性。SDK 提供采集授权与脱敏入口，但不会替业务判断哪些数据属于敏感信息，也不会替代服务端权限、留存和删除机制。
 
-以下片段聚焦对应配置，实际初始化仍需提供必填的 `application.name` 和有效的 `transport` endpoint 配置。
+## 默认采集边界
+
+当前 SDK：
+
+- 不采集 Fetch/XHR 请求体和响应体；
+- 不采集普通业务请求/响应 header；
+- 不采集 WebSocket message 内容；
+- 默认 Action 命名模式不读取 DOM 文本，只读取显式 `data-bk-action-name`，否则使用标签名；
+- 默认 URL 清洗会移除 username、password、query 和 fragment；
+- 会采集错误 message/stack、资源 URL、View URL、CSP 原始策略、显式业务属性；
+- `user.id` 由业务提供，SDK 原样透传；
+- 可选 `persistentId: true` 会把匿名设备 ID 写入 localStorage。
+
+“默认不采集 Body”不代表所有字段都安全。URL path、错误堆栈、DOM 显式名称和自定义属性仍可能包含个人信息或密钥。
+
+## Consent 生命周期
+
+需要先授权后采集时：
+
+```ts
+const rum = new BkOpenTelemetry({
+  application: { name: 'portal' },
+  transport: { endpoint: 'https://rum.example.com' },
+  privacy: { trackingConsent: 'not-granted' },
+});
+
+// 用户同意后
+await rum.setTrackingConsent('granted');
+
+// 用户撤回后
+await rum.setTrackingConsent('not-granted');
+```
+
+`not-granted` 状态下不会安装内置插件、自定义插件或 instrumentation。撤销时 SDK 会：
+
+1. 关闭插件并解除监听/patch；
+2. 关闭注册的 instrumentation；
+3. 清除运行时 Session 关联；
+4. flush 撤销前已经结束、仍在队列中的数据；
+5. 释放本实例持有的全局 OTel context/propagator 引用。
+
+注意：
+
+- 撤销不是“删除已上报数据”；删除和留存策略必须由服务端实现；
+- 撤销时会尽力发送队列中的既有数据。如果你的合规策略要求撤销时直接丢弃未发送数据，当前 SDK 不提供该选项；
+- SDK 不提供 Consent UI、Cookie 分类或法律依据记录；
+- 页面中有多个 SDK 实例时，全局 OTel 对象按引用计数释放，但全局监听仍可能重复，因此仍应使用单实例。
+
+构造阶段有一个重要边界：`new BkOpenTelemetry()` 会先解析配置并创建 OpenTelemetry Resource。只要 `tracking.device !== false`，这个过程会同步读取 UA/UA-CH、内存、逻辑处理器等 Device Resource 快照，即使初始 Consent 是 `not-granted` 或 `enabled: false`；这些值此时不会发送，Device 插件的 ID/视口/网络监听也不会启动。如果你的合规定义连“读取到内存”都必须晚于授权，应在获得授权后再构造 SDK，而不是只依赖 `trackingConsent`。
 
 ## URL 脱敏
 
-`privacy.redactUrl` 会处理写入 attribute 的 URL 类字段。
+默认逻辑：
+
+```text
+https://user:pass@example.com/orders/123?token=abc#detail
+→ https://example.com/orders/123
+```
+
+默认只移除认证信息、query 和 fragment，不改写 path。动态订单号、用户 ID、文件名等仍需要自定义：
 
 ```ts
-new BkOpenTelemetry({
-  privacy: {
-    redactUrl: url =>
-      url
-        .replace(/([?&]token=)[^&]+/g, '$1***')
-        .replace(/([?&]bk_ticket=)[^&]+/g, '$1***')
-        .replace(/\/users\/[^/?#]+/g, '/users/:id'),
+privacy: {
+  redactUrl(rawUrl) {
+    const url = new URL(rawUrl, location.href);
+    url.username = '';
+    url.password = '';
+    url.search = '';
+    url.hash = '';
+    url.pathname = url.pathname
+      .replace(/\/orders\/[^/]+/g, '/orders/:id')
+      .replace(/\/users\/[^/]+/g, '/users/:id');
+    return url.href;
   },
-});
+}
 ```
 
-## 属性脱敏
+`redactUrl` 覆盖而不是叠加默认实现；自定义时必须自己删除 query、fragment 和认证信息。
 
-`privacy.redactAttributes` 会处理 Resource、通过 SDK `startSpan()` 以及内置插件显式应用的属性，适合删除 authorization、手机号、邮箱等字段。Resource 在 SDK 构造时处理一次，后续不会动态更新。
+SDK 在写入 View、Request、Resource、错误资源、CSP source、Long Task source、referrer 等 URL 字段时调用该 Hook。自定义插件直接写入名为 URL 的任意属性不会被自动识别，插件必须显式调用 `context.config.hooks.redactUrl()`。
+
+## 路由分组不是 URL 脱敏
 
 ```ts
-new BkOpenTelemetry({
-  privacy: {
-    redactAttributes: attributes => {
-      const next = { ...attributes };
-      delete next['http.request.header.authorization'];
-      delete next['biz.mobile'];
-      delete next['biz.email'];
-      return next;
+tracking: {
+  view: {
+    getPathGroup(url) {
+      return new URL(url, location.href).pathname.replace(/\/orders\/[^/]+/, '/orders/:id');
     },
   },
-});
+}
 ```
 
-第三方 OpenTelemetry instrumentation 自己生成的 Span 属性不保证经过这一构造路径。需要统一清理第三方 Span 时，在 `tracking.beforeSend` 做最终兜底。
+`getPathGroup` 只生成低基数 `view.url_path_group`，不会改写 `view.url`。要保护原 URL，仍需 `privacy.redactUrl`。建议两者使用相同的动态段规则，但用途不同：
+
+- `redactUrl`：隐私和敏感数据边界；
+- `getPathGroup`：聚合维度和查询基数。
+
+未配置 `context.attributes.page` 时默认返回空对象，不存在独立的默认页面属性路径。页面地址统一由经过 `redactUrl` 的 `view.url` 表达，聚合维度使用 `view.url_path_group`；业务通过该 Hook 添加的属性仍需自行确保不包含敏感信息。
+
+## 属性脱敏
+
+```ts
+privacy: {
+  redactAttributes(attributes) {
+    const next = { ...attributes };
+    delete next['enduser.email'];
+    delete next['biz.access_token'];
+
+    if (typeof next['error.message'] === 'string') {
+      next['error.message'] = next['error.message'].replace(/[\w.+-]+@[\w.-]+/g, '<email>');
+    }
+    return next;
+  },
+}
+```
 
-`redactAttributes` 应返回完整可用的属性对象，不要只返回被修改的单个字段。
+当前调用边界：
 
-## 公共属性
+- SDK 构造 Resource attributes 时调用一次；
+- `BkOpenTelemetry.startSpan()` 合并运行时与显式属性后调用；
+- 内置/自定义插件也可以显式调用 `context.applyRedact()`；
+- Filter processor 不会在 `tracking.beforeSend` 之后再次调用脱敏 Hook。
 
-`context.attributes` 提供三类 hook：
+该 Hook 的类型只覆盖 Attributes，不会自动处理 Span Event。当前例外是 Long Task 插件在写入自己的 script/attribution Event 前显式调用；`recordException()` 产生的 exception message/stacktrace 不会经过这个 Hook。
 
-- `page`：页面、动作、错误等需要页面上下文的事件。
-- `error`：错误事件补充属性。
-- `custom`：手动自定义事件补充属性。
+因此 `tracking.beforeSend` 如果新增或改写字段，必须保证写入值已经安全：
 
 ```ts
-new BkOpenTelemetry({
-  context: {
-    attributes: {
-      page: () => ({
-        'biz.space_id': window.__BK_SPACE_ID__,
-        'biz.project_id': window.__BK_PROJECT_ID__,
-      }),
-      error: () => ({
-        'biz.release_channel': window.__BK_RELEASE_CHANNEL__,
-      }),
-      custom: () => ({
-        'biz.scene': 'checkout',
-      }),
-    },
+tracking: {
+  beforeSend(event) {
+    // 这里写入的字段不会再自动走 redactAttributes
+    event.attributes['biz.region'] = 'ap-guangzhou';
   },
-});
+}
 ```
 
-## 用户标识
+`redactAttributes` 应满足：
+
+- 返回普通的合法 OTel Attributes 对象；
+- 不抛异常；
+- 不执行网络请求或昂贵计算；
+- 不原地依赖第三方对象结构，推荐复制后修改；
+- 同一输入得到稳定结果，避免字段在不同 Span 间随机变化。
+
+## Request 局部过滤
 
-`user.id` 由接入方提供，SDK 原样透传，不 hash、不脱敏、不改写。如果业务要求 hash 或匿名化，应在传给 SDK 前完成。
+只针对 Fetch/XHR：
 
 ```ts
-new BkOpenTelemetry({
-  context: {
-    user: {
-      id: hashUserId(window.__BK_USER__?.id),
+tracking: {
+  request: {
+    excludedUrls: [/\/auth\/refresh(?:\?|$)/],
+    beforeSend(event) {
+      delete event.attributes['server.address'];
+      if (event.resource.url?.includes('/private/')) return false;
     },
   },
-});
+}
 ```
 
-## 请求数据边界
+执行边界：
 
-SDK 不读取或上报请求/响应 Body。
+- `excludedUrls` 在建 Span 和注入 trace header 之前判断，适合完全排除；
+- `request.beforeSend` 在请求结束、属性已组装后执行，返回 false 丢弃该请求 Span；
+- `tracking.beforeSend` 是所有 Span 的最终业务过滤；
+- URL 在请求 Hook 前已经经过 `redactUrl`，但 `context.request` / `xhr` 仍是原浏览器对象，Hook 不应把其中原始敏感值重新复制到 attributes。
 
-## 低基数路由
+## Action 文本隐私
 
-路由模板会写入 `view.url_path_group` 和部分目标路径字段。推荐把动态 ID 替换成模板，避免指标维度爆炸。
+默认：
 
 ```ts
-new BkOpenTelemetry({
-  tracking: {
-    view: {
-      getPathGroup: url => {
-        const { pathname } = new URL(url, window.location.href);
-        return pathname
-          .replace(/\/\d+/g, '/:id')
-          .replace(/\/[0-9a-f]{24}/g, '/:objectId');
-      },
-    },
+tracking: {
+  action: { nameCollection: 'explicit' },
+}
+```
+
+SDK向上查找 `data-bk-action-name`，没有时退回标签名。建议模板只写稳定业务动作：
+
+```html
+<button data-bk-action-name="submit-order">提交订单</button>
+```
+
+不要写：
+
+```html
+<button data-bk-action-name="submit-order-for-user-13800138000">提交订单</button>
+```
+
+`nameCollection: 'text'` 会允许读取可访问名称和 DOM 文本，最多 100 字符，但长度限制不是脱敏。输入框内容、用户名、消息文本都有泄露风险，只有经过隐私评审后才应开启。
+
+## User ID
+
+```ts
+rum.setUser({ id: hashUserId(rawUserId) });
+```
+
+SDK 不执行 hash。推荐：
+
+- 使用稳定、不可直接还原的内部标识；
+- 不发送手机号、邮箱、身份证、昵称；
+- hash 时使用服务端管理的盐或 HMAC 方案，避免简单 SHA 对小空间标识可枚举；
+- 登出时 `setUser({ id: undefined })`；
+- 服务端限制谁能查询 `user.id`。
+
+## Device ID 与存储
+
+默认 `tracking.device` 开启，但 `persistentId` 默认 false：设备 ID 只活在当前 Device 插件的采集周期；撤销再授权会重新初始化插件并生成新 ID。启用持久化：
+
+```ts
+tracking: {
+  device: {
+    persistentId: true,
+    storageKey: 'MY_APP_RUM_DEVICE_ID',
   },
-});
+}
 ```
+
+这会写入 localStorage，可能受 Cookie/本地存储合规策略约束。SDK 不提供自动过期或删除 API；业务需在撤销授权时按自身策略清理指定 key。Session 也会使用 localStorage 维持跨 Tab 状态，撤销 Consent 不会自动删除该 Record；重新授权可能在 Record 有效时复用 Session ID。
+
+## 错误与 CSP 数据
+
+错误可能包含：
+
+- `error.message`；
+- exception message、type 和 stacktrace；这些 Span Event 不对 `tracking.beforeSend` 暴露；
+- 源文件 URL、行列号；
+- Promise rejection 的字符串化内容；
+- 资源加载失败 URL。
+
+CSP Span 可能包含 `blocked_uri`、`source_file`、`original_policy` 等字段。`original_policy` 可能暴露内部域名或安全策略结构。开启 `cspViolation` 前应确认服务端访问控制，并用 `redactAttributes` 删除不应出浏览器的数据。
+
+## 自定义属性规范
+
+推荐命名：`biz.<domain>.<field>`，例如 `biz.order.channel`。值只允许 OTel Attribute 支持的标量或同类型数组。
+
+不要上报：
+
+- token、cookie、密码、密钥；
+- 完整请求/响应 Body；
+- 未经处理的邮箱、手机号、身份证；
+- 用户自由输入文本；
+- 每条事件都唯一但无法用于诊断的高基数值；
+- 超大字符串、序列化 DOM、整段应用状态。
+
+## 服务端责任
+
+SDK 不实现以下能力：
+
+- IP 到地理位置的派生与脱敏；
+- 错误指纹、聚合计数、分位数；
+- 字段级访问控制；
+- 租户鉴权和 token 轮换；
+- 数据保留、删除、导出；
+- Consent 法律依据存档；
+- 敏感字段二次扫描。
+
+生产链路应在 Collector/处理管道再做一次 allowlist 或脱敏，不能只依赖浏览器 Hook。
+
+## 上线评审清单
+
+1. `redactUrl` 覆盖 path 中的动态 ID，且仍删除 query/fragment/认证信息；
+2. `view.url_path_group` 是低基数模板；
+3. `user.id` 已按公司规范处理；
+4. Action 未开启不必要的文本采集；
+5. CSP、错误 stack、自定义字段经过字段评审；
+6. 浏览器 token 是最小权限且可轮换；
+7. `persistentId` 和 Session localStorage 满足存储授权要求；
+8. Collector 有二次校验、权限、留存和删除能力；
+9. 撤销 Consent 后的“flush 既有队列”行为符合产品政策；
+10. 用真实页面抓包检查最终 OTLP JSON，而不仅是配置代码审查。