@blueking/open-telemetry 0.0.22-beta.1 → 0.0.23

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

@@ -0,0 +1,266 @@
+<!-- 本文件由 packages/open-telemetry/scripts/gen-skill-references.mjs 从 wikis 自动生成，请勿手改。 -->
+
+# 生产接入指南
+
+生产接入的目标不只是“有数据”，而是数据边界正确、基数可控、容量可估算、跨域链路稳定，并且出现故障时不影响业务页面。
+
+## 推荐基线
+
+```ts
+import { BkOpenTelemetry } from '@blueking/open-telemetry';
+
+export const rum = new BkOpenTelemetry({
+  application: {
+    name: 'order-center',
+    environment: 'production',
+    version: window.__APP_VERSION__,
+  },
+  transport: {
+    endpoint: 'https://rum-collector.example.com',
+    token: window.__RUM_WRITE_TOKEN__,
+    processor: 'batch',
+    timeoutMillis: 10_000,
+  },
+  session: {
+    sampleRate: 0.2,
+  },
+  tracking: {
+    view: {
+      getPathGroup(rawUrl) {
+        return new URL(rawUrl, location.href).pathname
+          .replace(/\/orders\/[^/]+/g, '/orders/:id')
+          .replace(/\/users\/[^/]+/g, '/users/:id');
+      },
+      excludedActivityUrls: [/\/events\/stream(?:\?|$)/, /\/analytics(?:\?|$)/],
+    },
+    request: {
+      excludedUrls: [/\/health(?:\?|$)/],
+      allowedTracingUrls: [
+        rawUrl => new URL(rawUrl, location.href).origin === 'https://api.example.com',
+      ],
+    },
+    blankScreen: {
+      rootSelector: '#app',
+    },
+  },
+  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;
+    },
+    redactAttributes(attributes) {
+      const next = { ...attributes };
+      delete next['biz.secret'];
+      return next;
+    },
+  },
+});
+```
+
+这只是结构基线，不能直接替代本应用的 URL、身份、隐私和容量评审。
+
+## 1. 确定应用身份
+
+建议：
+
+- `application.name`：一个部署单元或前端产品的稳定名；
+- `environment`：`production`、`staging` 等有限枚举；
+- `version`：能映射到静态资源和 source map 的构建版本。
+
+不要把租户、用户、主机、运行时间拼到这些 Resource 字段中。需要租户维度时使用经过评审的低基数自定义属性，并由服务端做权限隔离。
+
+## 2. 估算采样与数据量
+
+Session 采样率控制整体数据量。粗略估算：
+
+```text
+日 Span 量 ≈ 日 Session 数 × sampleRate × 采样 Session 的平均 Span 数
+```
+
+平均 Span 数受页面数、请求/资源数、错误、Vital、Action，以及 Long Task/CSP/WebSocket 开关影响。建议先在灰度环境或少量流量以 `sampleRate: 1` 测量，再回推生产比例。
+
+采样策略注意：
+
+- 同一 Session 采样决定稳定，适合还原完整用户旅程；
+- 不支持按单一错误事件强制保留；
+- sampleRate 变化只影响新建/轮换 Session 的决定；
+- 服务端不能用已采样原始条数直接当全量用户数，必须结合采样率建模。
+
+## 3. 控制路由和事件基数
+
+必须排查：
+
+- `view.url_path_group` 是否含订单 ID、用户 ID、UUID；
+- custom/action name 是否拼业务 ID；
+- 自定义属性是否包含时间戳、随机值、整条 URL；
+- error message 是否因为动态值导致无限分组。
+
+SDK 不在浏览器做错误指纹。服务端应基于 stack/message 归一规则生成 error group，同时保留原始事件供诊断。
+
+## 4. 配置隐私边界
+
+至少审查：
+
+- URL path/query/fragment；
+- 默认 `rum.page.path`（它不经过 `redactUrl` / `getPathGroup`）；
+- `user.id`；
+- Error message 和 stack；
+- Action 显式名称或 DOM 文本；
+- CSP `original_policy`；
+- Long Task source URL/function；
+- View/Custom/Request Hook 添加的业务字段；
+- 持久 Device ID 和 localStorage。
+
+默认 URL 会删除 query/hash，但 path 不会模板化。完整边界见[隐私、Consent 与字段治理](./privacy.md)。
+
+`tracking.beforeSend` 只暴露顶层 attributes，不能修改 exception Span Event 中的 message/stacktrace；异常内容必须在业务产生前避免携带密钥和个人信息，并在 Collector 端做二次清洗。
+
+初始 `trackingConsent: 'not-granted'` 不等于“构造时完全不读取浏览器信息”。只要 `tracking.device !== false`，构造实例仍会读取 Device Resource 快照，但不会发送；要求授权前零读取时，应延迟到授权后再 `new BkOpenTelemetry()`。
+
+## 5. 配置 Collector 与 CORS
+
+验证真实浏览器请求，而不是只用 curl：
+
+```text
+POST <endpoint>/v1/rum
+Content-Type: application/json
+Authorization: Bearer ...
+```
+
+Collector 要求：
+
+- OPTIONS 和 POST CORS 正确；
+- body limit 能容纳 batch；
+- 只接受受限 RUM 写入 token；
+- 2xx 表示整批成功；
+- 限流用 429/503 和合理 `Retry-After`；
+- 能处理 OTLP JSON 的 `resourceSpans/scopeSpans/spans`；
+- 对 tenant、service.name、environment 做校验；
+- 具备服务端二次脱敏。
+
+## 6. 谨慎开启 traceparent
+
+默认不向任何业务请求注入，包括同源。只允许自有、已完成 CORS 和追踪评审的 API：
+
+```ts
+allowedTracingUrls: [
+  rawUrl => {
+    const url = new URL(rawUrl, location.href);
+    return url.origin === 'https://api.example.com' && url.pathname.startsWith('/v2/');
+  },
+]
+```
+
+不要使用宽泛 `/./` 或所有 URL，避免向第三方发送 Trace ID，也避免触发额外预检。API 端必须允许 `traceparent` header，并正确接续 W3C Trace Context。
+
+## 7. 排除长活动与噪声
+
+两类配置语义不同：
+
+- `request.excludedUrls`：不采集、不注入、不计入活动；
+- `view.excludedActivityUrls`：仍采集请求，但不让它延长 View loading time。
+
+长轮询、流式 Fetch、埋点上报通常使用第二类；健康检查、明确无诊断价值的高频请求可使用第一类。
+
+## 8. 校准白屏和 Action
+
+白屏：
+
+- SPA 设置真实 root；
+- 骨架/loading selector 是否合理；
+- Canvas/iframe 页面是否适合九点 DOM 采样；
+- 在弱网和首屏延迟场景验证误报。
+
+Action：
+
+- 保留默认 `explicit`；
+- 关键按钮添加稳定 `data-bk-action-name`；
+- 不在显式名称中放用户或订单信息；
+- 将 rage/dead/error click 当启发式信号，不当业务失败真值。
+
+## 9. 控制可选高成本能力
+
+默认关闭项应按问题启用：
+
+| 能力 | 适合场景 | 主要风险 |
+| --- | --- | --- |
+| Long Task | 主线程卡顿和脚本归因 | 事件量、脚本 URL/函数信息 |
+| CSP | 安全策略诊断 | `original_policy`、高频 violation |
+| WebSocket | 连接失败/断开分析 | 全局 Proxy、长连接生命周期 |
+
+先小流量评估平均每 Session 增量，再扩大采样。
+
+## 10. 单实例与加载顺序
+
+同一 window 只初始化一个实例，因为 SDK 会监听或 patch 全局能力。微前端应由主应用持有并向子应用暴露受控 API。
+
+初始化越早，越能捕获首屏 navigation、资源和错误；但必须确保：
+
+- endpoint/token 已可用；
+- Consent 状态正确；
+- `blankScreen.rootSelector` 已存在或会在检查前出现；
+- 扩展已在 start 前注册。
+
+需要等待 Consent 或运行配置时使用 `autoStart: false`。
+
+## 11. 业务故障隔离
+
+SDK 设计为：
+
+- 单个插件 init 失败不阻断其他插件；
+- 非 debug 模式尽量不污染业务 Console；
+- exporter 失败不会让业务 Fetch/XHR 失败；
+- unsupported Performance API 时跳过对应能力。
+
+但自定义 Hook/插件仍是业务代码：必须快速、同步、无副作用，不应发网络请求或抛异常。上线前对 `redactUrl`、`redactAttributes`、`getPathGroup`、两个 `beforeSend` 做异常与性能测试。
+
+## 12. 灰度验收
+
+建议按以下顺序：
+
+1. 测试环境 sampleRate 1，验证所有默认 Span；
+2. 检查实际 OTLP JSON 的敏感字段；
+3. 验证跨域 Collector、鉴权、429/503；
+4. 验证 SPA route、BFCache、手动/自动 View 无重复；
+5. 弱网、后台、关闭页面时验证尽力 flush；
+6. 观察平均 Span/Session、batch body、错误率和队列丢弃；
+7. 1% 或内部用户灰度；
+8. 调整 sampleRate/排除项；
+9. 扩大流量并配置服务端监控告警。
+
+## 13. 服务端建模验收
+
+服务端需要理解：
+
+- Session/View 生命周期通过多条 Span 表达，`session.phase`、`view.phase` 与 `view.version` 用于重建状态；
+- `action.id` 负责关联窗口，不提供客户端 count；
+- `vital.value` 是原始指标；分位数服务端计算；
+- 资源网络阶段只在浏览器可见时出现；
+- IP/geo、错误指纹、聚合数不是 SDK 字段；
+- 事件时间直接使用 OTLP envelope 的 `startTimeUnixNano/endTimeUnixNano` 纳秒字符串；
+- Schema version 当前是 Resource `rum.schema.version=3`。
+
+字段级规则见[遥测字段字典](./telemetry-reference.md)。
+
+## 上线清单
+
+- [ ] 单实例、初始化位置明确
+- [ ] application name/environment/version 稳定
+- [ ] endpoint 最终为 `/v1/rum` 且 CORS 通过
+- [ ] token 最小权限，可轮换
+- [ ] sampleRate 有容量依据
+- [ ] 动态路由已分组、URL 已脱敏
+- [ ] user/action/error/custom 字段完成隐私评审
+- [ ] traceparent 只对明确 API 白名单开启
+- [ ] 流式/长轮询不延长 View loading
+- [ ] 白屏 root 和阈值经过真实页面验证
+- [ ] 可选高成本插件按需启用
+- [ ] Collector 有二次校验、服务端聚合和告警
+- [ ] 有版本回滚和关闭 `enabled`/采样的应急开关

package/skills/bk-rum-otele/references/session-context.md

@@ -0,0 +1,185 @@
+<!-- 本文件由 packages/open-telemetry/scripts/gen-skill-references.mjs 从 wikis 自动生成，请勿手改。 -->
+
+# Session 与公共上下文
+
+Session 是采样和访问会话边界；User、Device 以及 Session 字段共同组成后续 Span 自动继承的公共上下文。Session 在获得 Consent 后始终启用，不能通过 `tracking` 关闭。
+
+## Session 生命周期
+
+SDK 使用以下固定规则：
+
+| 规则 | 当前值 | 是否可配置 |
+| --- | ---: | --- |
+| 无活动超时 | 15 分钟 | 否 |
+| 最长生命周期 | 4 小时 | 否 |
+| 活动事件 | `click`、`keydown`、`scroll`、`touchstart` | 否 |
+| 活动续期节流 | 1 秒 | 否 |
+| 可见页面定期检查 | 60 秒 | 否 |
+| 采样率 | `1` | 是，`session.sampleRate` |
+
+初始化时，SDK 尝试从 localStorage 读取同一应用和 Collector 隔离的 Session Record：
+
+- Record 有效：复用 ID，并延长无活动过期时间。
+- Record 不存在：创建新 Session，发送 `browser.session` start。
+- Record 已过期：创建新 ID，发送 rotate；旧 Session 的 end 由持有旧上下文的 Tab 发送。
+- localStorage 不可访问：退回当前 JavaScript 进程内存，不影响页面采集，但不能跨页面或跨 Tab 共享。
+
+## 续期与过期
+
+用户活动会延长有效 Session。达到 15 分钟无活动或 4 小时最长生命周期时，SDK：
+
+1. 通知 View、Action 等插件 Session 已过期。
+2. 发送 `browser.session` end。
+3. 清除运行时 `session.*`。
+4. 结束当前 View。
+5. 触发一次 flush。
+6. 在下一次用户活动时创建新 Session 和 `session_renewal` View。
+
+页面重新可见时只检查和延长仍有效的 Session，不会主动创建新 Session。这样后台放置很久的页面不会仅因切回前台就复活旧访问。
+
+## 跨 Tab 行为
+
+默认 storage key 根据 `application.name` 与解析后 Endpoint host 计算，多个同源 Tab 因而共享 Session Record。
+
+- 其他 Tab 只延长当前相同 Session 时，本 Tab 会更新自己的过期 Timer。
+- 其他 Tab 使 Session 过期或替换 ID 时，本 Tab 会停用自己的 Session。
+- 已停用的 Tab 不会被其他 Tab 的新 Session 被动复活；本 Tab 发生用户活动后才读取并接管共享 Session。
+
+需要完全隔离不同接入实例时，可设置显式 `session.storageKey`。
+
+```ts
+new BkOpenTelemetry({
+  application: { name: 'order-web' },
+  transport: { endpoint: 'https://rum.example.com' },
+  session: {
+    sampleRate: 0.2,
+    storageKey: 'bk-rum-order-session',
+  },
+});
+```
+
+## Session 采样
+
+采样决定由 `application.name + "\0" + session.id` 的稳定 hash 得出：
+
+- `sampleRate <= 0`：全部不采样。
+- `sampleRate >= 1`：全部采样。
+- 中间值：同一应用、同一 Session 始终得到相同决定。
+- Session 轮换后使用新 ID 重新计算。
+
+输入有限数值会限制到 `0..1`；缺省、`NaN` 或无限值回退为 `1`。采样率写入 Resource 的 `session.sample_rate`，不是每条 Span 的业务属性。
+
+完整过滤与上报行为见[上报协议、批处理与采样](./transport-sampling.md)。
+
+## Session 遥测
+
+Span 名固定为 `browser.session`：
+
+| `session.phase` | 使用时机 | 常见 reason |
+| --- | --- | --- |
+| `start` | 首次创建 | `init` |
+| `rotate` | 旧 Session 过期后新建 | `inactivity`、`maxLifetime` |
+| `end` | 当前 Session 失效 | `inactivity`、`maxLifetime`、`external` |
+
+关键字段：
+
+- `session.id`
+- `session.start_time`
+- `session.type=user`
+- `session.has_replay=false`
+- `session.lifecycle.reason`
+- `session.previous_id`，仅存在前一个 ID 时出现
+- `session.phase`
+
+生命周期 Span 是瞬时事件，持续时间由服务端根据时间戳推导。
+
+## User 上下文
+
+初始化时可传入用户：
+
+```ts
+const bkOT = new BkOpenTelemetry({
+  application: { name: 'order-web' },
+  transport: { endpoint: 'https://rum.example.com' },
+  context: {
+    user: { id: anonymizedUserId },
+  },
+});
+
+bkOT.setUser({ id: 'user-002' });
+bkOT.setUser({ id: undefined });
+```
+
+SDK 只维护 `user.id`，并原样透传：不 hash、不截断、不验证、不自动脱敏。调用 `setUser()` 只影响之后创建的 Span，不会改写已结束数据，也不会触发 Session 轮换。
+
+## Device Resource 属性
+
+`tracking.device` 默认开启。构造阶段读取相对稳定的设备信息并写入 Resource：
+
+| 字段 | 来源 | 可能缺失 |
+| --- | --- | --- |
+| `browser.name` | UA 简单识别：Edge/Chrome/Firefox/Safari/Other | 否 |
+| `browser.version` | UA 主版本 | 未识别版本时 |
+| `os.name` | UA / UA-CH platform | 否，无法识别为 `Other` |
+| `device.type` | UA-CH mobile 或移动 UA | 否 |
+| `device.memory_gib` | `navigator.deviceMemory` | 浏览器未实现时 |
+| `device.logical_processor_count` | `navigator.hardwareConcurrency` | 浏览器未实现时 |
+
+关闭 `tracking.device` 时，这些 Device Resource 字段不写入。
+
+## Device 运行时属性
+
+Device 插件还维护：
+
+| 字段 | 更新时机 |
+| --- | --- |
+| `device.id` | 插件启动时 |
+| `browser.viewport.width/height` | 启动、resize、orientationchange |
+| `browser.screen.width/height` | 启动、resize、orientationchange |
+| `network.effective_type` | 启动和 connection change |
+| `network.connection_type` | 同上 |
+| `network.downlink` | 同上 |
+| `network.rtt` | 同上 |
+| `network.save_data` | 同上 |
+
+视口变化使用 250ms trailing debounce；网络字段只有浏览器实现 Network Information API 时才存在。这些变化不主动生成 Span，只影响后续 Span 的上下文。
+
+## Device ID 持久化
+
+默认 `persistentId=false`：每次 Device 插件初始化时创建新的匿名设备 ID，只在当前采集周期内稳定；撤销并重新授予 Consent 会重新初始化插件，因此 ID 也会变化。
+
+```ts
+tracking: {
+  device: {
+    persistentId: true,
+    storageKey: 'BK_RUM_DEVICE_ID_ORDER',
+  },
+}
+```
+
+开启后 ID 写入 localStorage；未指定 key 时按 `application.name` hash 隔离。localStorage 失败时仍生成内存 ID。持久设备 ID 会增加跨访问关联能力，也增加隐私风险，必须在取得合规依据后启用。
+
+## 公共页面属性
+
+`context.attributes.page` 在多数内置事件创建时执行：
+
+```ts
+context: {
+  attributes: {
+    page: () => ({
+      'biz.space_id': currentSpaceId,
+      'biz.module': currentModule,
+    }),
+  },
+}
+```
+
+未配置时默认返回 `rum.page.host` 和 `rum.page.path`。自定义 Hook 会完全替换默认实现，不是叠加；如仍需要默认字段，需自行返回。
+
+Hook 每次执行，应保持低成本且不要抛错。它可能包含高基数字段，但服务端聚合维度应只选择稳定、低基数属性。
+
+## Consent 对上下文的影响
+
+`trackingConsent=not-granted` 时不创建 Session、不启动 Device 插件、不建立 View，也不安装浏览器 Patch。需要注意，SDK 构造时仍会为 OpenTelemetry Resource 同步读取稳定 Device 快照（除非 `tracking.device=false`），只是未授权时没有 Span 将它发送。运行期撤销 Consent 会停止插件并清除运行时 `session.id`，但当前实现不会删除 localStorage 中的 Session Record；重新授权时如果该 Record 仍有效，Session 插件可以恢复并续期同一 ID，否则创建新 Session。
+
+完整 Consent 行为见[隐私、Consent 与字段治理](./privacy.md)。