@blueking/open-telemetry 0.0.22 → 0.0.24

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

@@ -2,245 +2,435 @@
 
 # 调试与排障
 
-本页按接入阶段常见问题组织。
+排障建议从“有没有创建有效 Session/View”开始，再看 Span 过滤、批处理和网络出口。只盯 `/v1/rum` 请求很容易把采样、Consent 或关联问题误判成 Collector 故障。
 
-## 本地看不到数据
+## 最小诊断配置
 
-先打开 debug，并使用 simple span processor。
+在测试环境临时使用：
 
 ```ts
-new BkOpenTelemetry({
+const rum = new BkOpenTelemetry({
   application: { name: 'rum-debug' },
-  debug: true,
-  session: {
-    sampleRate: 1,
-  },
   transport: {
-    endpoint: 'http://localhost:4318',
+    endpoint: 'https://rum.example.com',
     processor: 'simple',
   },
+  session: { sampleRate: 1 },
+  debug: true,
+  autoStart: false,
 });
+
+await rum.start();
 ```
 
-检查点：
+这个配置的目的：
+
+- 采样率 1 排除“Session 未命中”；
+- simple 排除 5 秒批量等待；
+- `debug: true` 在 exporter 前打印 Span，也显示插件初始化和部分丢弃警告；
+- 显式 `await start()` 让启动错误可以被捕获。
 
-- Collector 是否监听 `4318`。
-- 浏览器 Network 中是否有 `/v1/rum` 请求。
-- 是否被采样丢弃。
-- `enabled` 是否为 `false`。
+生产问题确认后应恢复 batch，避免逐 Span 请求。
 
-## 手动事件没有上报
+## 分层定位流程
 
-`reportAction()` 和 `reportCustomEvent()` 受采样控制。未采样时会静默丢弃。
+### 1. 确认实例和配置
 
 ```ts
-new BkOpenTelemetry({
-  application: { name: 'rum-debug' },
-  debug: true,
-  session: {
-    sampleRate: 1,
-  },
-  transport: { endpoint: 'https://rum-collector.example.com' },
-});
+console.log(rum.config.application);
+console.log(rum.config.transport.endpoint); // 应以 /v1/rum 结尾
 ```
 
-## 自定义插件注册失败
+检查：
 
-`use()` 必须在 `start()` 前调用。如果需要注册插件，关闭自动启动。
+- `application.name` 非空；
+- `transport.endpoint` 非空且没有把 `/v1/rum` 手工写两次；
+- 页面只创建了一个实例；
+- 没有 `enabled: false`；
+- 当前实例没有已经 `shutdown()`。
+
+### 2. 确认 Consent 与启动
 
 ```ts
-const bkOT = new BkOpenTelemetry({
-  application: { name: 'rum-debug' },
-  autoStart: false,
-  transport: { endpoint: 'https://rum-collector.example.com' },
-});
+console.log(rum.config.trackingConsent);
+await rum.start();
+```
 
-bkOT.use(myPlugin);
+`not-granted` 不会安装采集插件。授权后必须调用：
 
-await bkOT.start();
+```ts
+await rum.setTrackingConsent('granted');
 ```
 
-## 空白屏误报
+如果使用 `autoStart: true`，构造后立刻调用 `use()` 会抛错；扩展注册请改为 `autoStart: false`。自动启动没有单独暴露 ready Promise，构造后立即同步调用手动事件也不会排队，可能因为 View 尚未建立而被过滤。必须保证首个手动事件不丢时，应使用 `autoStart: false` 并显式 `await rum.start()`。
 
-SPA 应用应配置 `rootSelector` 和 loading/skeleton 忽略选择器。
+### 3. 确认 Session/View/采样
 
 ```ts
-new BkOpenTelemetry({
-  application: { name: 'rum-debug' },
-  transport: { endpoint: 'https://rum-collector.example.com' },
-  tracking: {
-    blankScreen: {
-      rootSelector: '#app',
-      ignoreSelectors: ['.bk-loading', '.skeleton'],
-      checkDelay: 5000,
-    },
-  },
+console.table(rum.getRuntimeAttributes());
+console.log({
+  sampled: rum.isSampled(),
+  session: rum.isSessionActive(),
+  view: rum.isViewActive(),
 });
 ```
 
-## 接口 span 太多
+普通 Span 导出的必要条件：
+
+- `isSampled() === true`；
+- 有 `session.id`；
+- 有 `view.id`。
 
-先确认是否有多个 SDK 实例重复初始化，尤其是微前端场景。其次用 `excludedUrls` 排除探活或高频无价值请求。
+`browser.session` 是唯一可以没有 `view.id` 的内置 Span。
+
+manual View 模式下，必须在 Session 建立后调用 `startView()`：
 
 ```ts
-new BkOpenTelemetry({
-  application: { name: 'rum-debug' },
-  transport: { endpoint: 'https://rum-collector.example.com' },
-  tracking: {
-    request: {
-      excludedUrls: [/\/health(?:\?|$)/, /\/polling\//],
-    },
-  },
-});
+await rum.start();
+rum.startView({ name: '首页' });
 ```
 
-## URL 或用户信息泄露风险
+### 4. 确认 Span 到达 exporter
 
-配置 URL 和属性脱敏。
+`debug: true` 会打印：
 
-```ts
-new BkOpenTelemetry({
-  application: { name: 'rum-debug' },
-  transport: { endpoint: 'https://rum-collector.example.com' },
-  privacy: {
-    redactUrl: url => url.replace(/([?&]token=)[^&]+/g, '$1***'),
-    redactAttributes: attributes => {
-      const next = { ...attributes };
-      delete next['user.email'];
-      return next;
-    },
-  },
-});
+```text
+[bk-ot][rum] [...ReadableSpan]
 ```
 
-## Long Task 没有数据
+如果能看到 Span、看不到网络请求，重点检查 exporter、并发、页面退出和浏览器拦截。如果完全看不到 Span，重点检查 capability 开关、浏览器 API 支持、Session/View/采样和 beforeSend。
+
+### 5. 确认网络和 Collector
+
+Network 面板过滤 `v1/rum`，检查：
+
+- URL、POST、请求体和 `Content-Type`；
+- OPTIONS 预检；
+- `Authorization` 和自定义 header；
+- response status；
+- Console 中 CORS、Mixed Content、CSP、ad blocker 错误；
+- 响应是否真的是 2xx，而非页面网关返回的 30x/HTML。
 
-Long Task API 并非所有浏览器都支持。Firefox 不支持时插件会跳过。
+## 完全没有 `/v1/rum` 请求
+
+常见原因与证据：
+
+| 原因 | 怎么确认 | 处理 |
+| --- | --- | --- |
+| batch 正在等待 | 调用 `await rum.flush()` | 联调临时 simple；生产保留 batch |
+| 未命中采样 | `rum.isSampled() === false` | 测试环境设 `sampleRate: 1` |
+| 未授权 | `rum.config.trackingConsent` | 授权后调用 `setTrackingConsent('granted')` |
+| 没有 View | `rum.isViewActive() === false` | manual 模式调用 `startView()`；检查 View 插件 |
+| SDK 未启动 | 显式 `await rum.start()` | 捕获启动异常 |
+| 全部被 Hook 丢弃 | 暂时移除两个 beforeSend | 修正返回条件 |
+| 页面没有产生结束 Span | 手动 `reportCustomEvent()` 后 flush | 再定位具体插件 |
+| endpoint 被浏览器阻止 | Console/Network | 修复 HTTPS、CSP、CORS、扩展拦截 |
+
+最小探针：
 
 ```ts
-new BkOpenTelemetry({
-  application: { name: 'rum-debug' },
-  transport: { endpoint: 'https://rum-collector.example.com' },
-  tracking: {
-    longTask: {
-      threshold: 50,
-    },
-  },
-});
+rum.reportCustomEvent({ name: 'rum_probe' });
+await rum.flush();
 ```
 
-## HTTP Body 没有数据
+若 `isSampled/session/view` 都为 true，探针仍无 exporter 日志，检查 `tracking.beforeSend` 是否返回 false。
+
+## 有 debug Span，但请求失败
+
+### CORS
 
-这是预期行为：SDK 不读取或上报请求/响应 Body。
+典型表现：OPTIONS 失败、`TypeError: Failed to fetch`、响应在 DevTools 中不可读。
 
-## WebSocket 采集异常
+Collector 需要允许页面 origin、POST/OPTIONS 和实际 header。使用 token 时必须允许 `authorization`；自定义 header 也要列入 allow headers。
 
-WebSocket 插件会 Proxy 全局 `WebSocket`。如果应用或第三方库也 patch 了 WebSocket，应避免重复 patch。
+### URL 错误
+
+SDK固定追加 `/v1/rum`。如果配置：
 
 ```ts
-new BkOpenTelemetry({
-  application: { name: 'rum-debug' },
-  transport: { endpoint: 'https://rum-collector.example.com' },
-  tracking: {
-    websocket: true,
-  },
-});
+endpoint: 'https://rum.example.com/v1/rum'
+```
+
+最终是：
+
+```text
+https://rum.example.com/v1/rum/v1/rum
 ```
 
-# FAQ
+应传上报根地址。
 
-## SDK 会采集哪些数据？
+### 401/403
 
-默认采集页面访问与稳定耗时、用户动作、资源加载、fetch/xhr、JavaScript 错误、Web Vitals、空白屏、设备信息和会话信息。HTTP body、Long Task、CSP、WebSocket 默认关闭。
+检查：
+
+- token 是否过期、是否误含 `Bearer ` 前缀；SDK 会自行添加；
+- `headers.Authorization` 是否覆盖了 token 生成的 header；
+- Collector 是否允许浏览器凭证和当前应用/租户；
+- 预检是否允许 Authorization。
+
+### 404/405
+
+Collector 没有暴露 SDK 约定的 `/v1/rum` POST，或网关路径重写不一致。不要把它改成 `/v1/traces` 除非网关明确把 `/v1/rum` 转发到对应处理器。
+
+### 413
+
+批量 body 超过网关限制。降低 `maxExportBatchSize`，并确认 Collector body limit。队列大小影响内存与丢弃，不直接限定单个 body 字节数。
+
+### 429/502/503/504
+
+当前 exporter 会在总体 `timeoutMillis` 内重试，支持 `Retry-After`。持续失败时：
+
+- 修复 Collector 容量或限流；
+- 适当降低采样率；
+- 避免同时开启高成本/高事件量能力；
+- 不要仅无限增大客户端 queue 和 timeout。
+
+## 手动事件不上报
+
+按以下顺序完整排查，不要只检查事件 payload。
+
+### 1. 启动与 Consent
 
 ```ts
-new BkOpenTelemetry({
-  application: { name: 'demo' },
-  transport: { endpoint: 'https://rum-collector.example.com' },
-  tracking: {
-    action: true,
-    longTask: true,
-    websocket: true,
-  },
+console.log({
+  enabled: rum.config.enabled,
+  consent: rum.config.trackingConsent,
 });
 ```
 
-## `user.id` 会被 SDK 脱敏吗？
+- `enabled` 必须为 true；
+- Consent 必须为 `granted`；
+- 实例不能已经 shutdown；
+- 默认 autoStart 是异步的，手动事件不会在启动完成前排队。需要确定时序时改用：
 
-不会。`user.id` 由接入方提供，SDK 原样透传。如果业务要求 hash，需要在传入前处理。
+```ts
+const rum = new BkOpenTelemetry({
+  application: { name: 'rum-debug' },
+  transport: { endpoint: 'https://rum.example.com' },
+  autoStart: false,
+});
+
+await rum.start();
+```
+
+### 2. Session、采样和 View
 
 ```ts
-new BkOpenTelemetry({
-  application: { name: 'demo' },
-  transport: { endpoint: 'https://rum-collector.example.com' },
-  context: {
-    user: {
-      id: hashUserId(rawUserId),
-    },
-  },
+console.log({
+  sampled: rum.isSampled(),
+  session: rum.isSessionActive(),
+  view: rum.isViewActive(),
 });
 ```
 
-## `session.sampleRate` 是 trace 级采样吗？
+三者对普通手动事件都应为 true。`reportAction()` 和 `reportCustomEvent()` 未采样时直接返回；manual View 未建立时，即使创建 Span 也会在过滤层因缺少 `view.id` 被丢弃。manual 模式应在 `await rum.start()` 后调用一次当前路由的 `startView()`。
+
+### 3. Payload 和 Hook
 
-不是。它是会话级确定性采样，同一会话内保持一致。
+- `name` 类型必须是 string，并建议使用非空、低基数枚举；
+- 当前运行时不拒绝空字符串：`reportCustomEvent({ name: '' })` 会尝试生成名为 `custom.` 的 Span，`reportAction({ name: '' })` 会生成空的 `action.name`，都不会仅因空 name 抛错或丢弃，但数据不可用，不应依赖该行为；
+- attributes 只能使用合法 OTel Attribute 类型；
+- `context.attributes.page/custom` 与 `privacy.redactAttributes` 不应抛错；
+- `tracking.beforeSend` 不能按 name 返回 false；Custom Event 不经过请求级 `request.beforeSend`。
+
+### 4. 强制结束 batch 并观察 exporter
 
 ```ts
-new BkOpenTelemetry({
-  application: { name: 'demo' },
-  transport: { endpoint: 'https://rum-collector.example.com' },
-  session: {
-    sampleRate: 0.2,
-  },
-});
+rum.reportCustomEvent({ name: 'rum_probe' });
+await rum.flush();
 ```
 
-## 为什么不使用 OpenTelemetry userInteraction instrumentation？
+临时启用 `debug: true` 并使用 `transport.processor: 'simple'`。若控制台存在 `[bk-ot][rum]` Span 而 Network 没有成功请求，事件创建和过滤已经通过，应转查 exporter/CORS；若没有 debug Span，继续检查前述上下文和 Hook。
+
+### 5. 网络与 Collector
+
+- URL 是 `<endpoint>/v1/rum`，未重复追加路径；
+- OPTIONS/POST、Content-Type、鉴权和自定义 Header 的 CORS 正确；
+- 返回 2xx，而不是 30x、HTML 错误页或可重试失败；
+- 没有 Mixed Content、CSP、广告拦截器、超时或并发队列问题。
+
+如果探针成功、业务事件失败，再比较两者的 name、attributes 和业务 Hook 分支；如果探针也失败，按本页开头的分层流程继续检查通用出口。
+
+## Fetch/XHR 没有 Span
+
+1. `tracking.request !== false`；
+2. URL 没命中 `excludedUrls`；
+3. `request.beforeSend` 没返回 false；
+4. 请求是 SDK 启动之后发生；
+5. 页面没有第二个实例/第三方库反复覆盖 `fetch` 或 XHR prototype；
+6. SDK 自身 `/v1/rum` 请求会被有意排除；
+7. Span 有 Session/View 并命中采样。
+
+`resource.*` 网络阶段缺失不代表请求 Span 丢失。跨域没有 `Timing-Allow-Origin`、浏览器清理 buffer、匹配等待超过 200ms 都可能只保留基础 Fetch/XHR 属性。
 
-官方 userInteraction instrumentation 主要用于把交互回调中的异步任务组织成 trace，但没有稳定的 RUM action 语义、动作命名、页面活动窗口和关联计数。本 SDK 统一使用 `action` 插件，避免同一次点击重复上报；内置 request 采集统一负责 Fetch/XHR 网络 trace。
+## `traceparent` 没有注入
+
+这是默认行为。只有 URL 明确命中 `allowedTracingUrls` 才注入，同源也不会自动注入：
 
 ```ts
-bkOT.reportAction({
-  name: '确认提交',
-  attributes: {
-    'biz.scene': 'strategy-create',
+tracking: {
+  request: {
+    allowedTracingUrls: ['https://api.example.com/'],
   },
-});
+}
 ```
 
-## 可以只上报 traces，不上报 metrics/logs 吗？
+跨域还需要服务端 CORS 允许请求头 `traceparent`。如果预检失败，缩小白名单并修复 API 服务的 CORS；不要把所有第三方 URL 加入白名单。
+
+## 请求 Span 太多或 View loading 一直不结束
 
-SDK 固定只上报 RUM Trace，不创建 Metrics/Logs Provider，无需配置开关。
+使用两个不同的排除入口：
 
 ```ts
-new BkOpenTelemetry({
-  application: { name: 'demo' },
-  transport: { endpoint: 'https://trace-gateway.example.com' },
-});
+tracking: {
+  request: {
+    excludedUrls: [/\/rum-noise/],
+  },
+  view: {
+    excludedActivityUrls: [/\/events\/stream/, /\/long-poll/],
+  },
+}
 ```
 
-Endpoint 会解析为 `https://trace-gateway.example.com/v1/rum`。
+- `request.excludedUrls`：完全不采集、不传播、不计活动；
+- `view.excludedActivityUrls`：请求仍可采集，但不延长 View loading time。
+
+长轮询、SSE fetch、埋点和永不结束的流式请求通常应配置第二项。
+
+## 静态资源字段不完整
+
+常见原因：
+
+- 浏览器不提供新字段；
+- 跨域资源没有 `Timing-Allow-Origin`，大小和详细时序被限制；
+- Service Worker/cache 让某些阶段为 0；
+- Resource Timing buffer 已满；
+- 条目时间顺序异常，SDK 会省略无效阶段而不是上报负值。
+
+先判断 `browser.resource` 是否存在，再判断单个可选字段，不要把“字段缺失”当成“插件未工作”。
+
+## Web Vitals 缺失或值不同
+
+- 指标依赖浏览器支持和页面生命周期，不保证每个 View 都有五项；
+- LCP/CLS 等在隐藏或 View 结束时定稿；
+- INP 需要真实 interaction；没有交互时可缺失；
+- SPA 每个 View 的聚合边界由 SDK 维护，与只计算整页一次的工具可能不同；
+- BFCache 会创建新的 View loading type；
+- attribution 字段比核心 value 更依赖浏览器能力。
 
-## 为什么不建议多个实例同时运行？
+不要用刷新后立刻查看网络来断言缺失；先触发交互、切换可见性或调用 `flush()`。
 
-fetch、xhr、action、websocket 等能力会监听或 patch 全局 API。多个实例可能重复采集、重复上报或互相影响。
+## Action 名称不符合预期
+
+默认 `nameCollection: 'explicit'`：
+
+1. 从点击元素和祖先读取 `data-bk-action-name`；
+2. 没有显式名称时使用元素标签名；
+3. 不读取按钮可见文字。
+
+推荐补 `data-bk-action-name`。只有确实接受文本隐私风险时才设置 `nameCollection: 'text'`。
+
+如果没有 Action：确认点击是主按钮、Action 开启、Session/View 有效，并检查页面是否有覆盖层/Shadow DOM 目标。SDK 最多向上检查 10 层父节点进行部分命名和可交互判断。
+
+## Rage/Dead/Error Click 不符合预期
+
+- Rage click：1 秒内至少 3 次、位置距离不超过 100px 的点击链；报告会等待连击窗口；
+- Error click：Action 生命周期内捕获到错误活动；
+- Dead click：点击后没有被认为有效的请求、DOM、导航、错误等副作用，并排除输入/选择/滚动等情况；
+- Action 最长默认 10 秒，页面活动安静后还需短暂确认。
+
+这些是启发式信号，不是业务失败结论。服务端应保留原始 frustration type，结合 View/资源/错误分析。
+
+## 白屏误报
+
+按顺序检查：
+
+1. `rootSelector` 是否指向实际应用根节点；
+2. 页面是否用 Canvas/WebGL/iframe 等九点 DOM 采样难以识别的渲染方式；
+3. 骨架屏/加载层是否被错误忽略；
+4. 页面布局的主要内容是否避开了九个采样点；
+5. `checkDelay` 是否覆盖真实异步渲染时间；
+6. `threshold` 是否过低。
 
 ```ts
-if (!window.__BK_RUM_INSTANCE__) {
-  window.__BK_RUM_INSTANCE__ = new BkOpenTelemetry({
-    application: { name: 'demo' },
-    transport: {
-      endpoint: 'https://rum-collector.example.com',
-    },
-  });
+tracking: {
+  blankScreen: {
+    rootSelector: '#app',
+    checkDelay: 2000,
+    confirmationDelay: 300,
+    threshold: 0.9,
+    ignoreSelectors: ['.my-skeleton'],
+  },
 }
 ```
 
-## 如何在页面离开前尽量 flush？
+根节点暂时不存在会被判断为 `missing_root` 候选。每个 View 最多上报一次，修改配置后要创建新 View 才能重新验证。
 
-SDK 已监听部分页面生命周期事件。业务也可以在关键流程后主动调用 `flush()`。
+## Long Task 没数据
 
-```ts
-await saveCriticalConfig();
-await bkOT.flush();
+- 默认关闭，需要 `tracking.longTask: true`；
+- 需要 `PerformanceObserver`；
+- 优先 `long-animation-frame`，否则回退 `longtask`；
+- entry duration 必须达到 threshold；
+- 浏览器可能只支持基础 Long Task，没有脚本归因；
+- 页面后台、跨域 iframe 与浏览器实现会限制 attribution。
+
+## CSP 没数据
+
+- 默认关闭，需要 `tracking.cspViolation: true`；
+- SDK 只能接收页面派发的 `securitypolicyviolation` 事件；
+- Collector 自身被 CSP `connect-src` 阻止时，CSP Span 也无法上报；
+- Report-Only 和强制策略的浏览器行为要用真实浏览器验证；
+- `original_policy` 等字段可能被 `redactAttributes` 删除。
+
+## WebSocket 没数据
+
+- 默认关闭，需要 `tracking.websocket: true`；
+- 只记录 connect/open/error/close 生命周期，不记录 message；
+- SDK 启动前已经创建的连接无法追溯；
+- 多实例或其他库重复 patch WebSocket 会造成冲突；
+- 连接未关闭时，最终 close Span 需要等事件或 shutdown 逻辑，不能只看刚创建后的网络。
+
+## View 重复、缺失或基数过高
+
+- query-only 变化不会新建自动 View；
+- pathname 或非纯锚点 hash 变化会触发；
+- Router 同时手动 `startView()` 且使用 auto 会重复；
+- 微前端多个实例会重复；
+- `getPathGroup` 默认仅返回 pathname，不会自动识别 `/orders/123` 动态 ID；
+- `setViewName()` 是改名，不创建新 View；
+- Session 续期和 BFCache 恢复会创建具有特定 loading type 的 View。
+
+选择 auto 或 manual 一种边界来源，并配置低基数 path group。
+
+## 队列丢数据
+
+Batch queue 默认 2048。高事件量页面同时开启 Resource、Long Task、CSP、WebSocket 等能力时可能塞满。表现通常是 debug/OTel diag 中 dropped warning，而不是业务异常。
+
+处理优先级：
+
+1. 降低 `session.sampleRate`；
+2. 关闭不需要的高量能力；
+3. 排除噪声 URL/活动；
+4. 确认 Collector 性能和网络成功率；
+5. 再评估 queue/batch 大小，避免只增加浏览器内存。
+
+## 插件初始化失败
+
+PluginManager 会隔离单个插件异常：失败插件不进入 started 列表，其余插件继续。设置 `debug: true` 查看：
+
+```text
+[bk-ot] plugin "<name>" init failed
 ```
+
+自定义插件应在 init 失败前自行清理已经安装的部分监听；因为 init 抛错后 PluginManager 不会为该插件调用 shutdown。
+
+## 提交问题时应附带
+
+- SDK 版本、浏览器版本、框架/路由模式；
+- 精简后的构造配置（删除 token 和敏感字段）；
+- `isSampled/isSessionActive/isViewActive` 结果；
+- `/v1/rum` 请求 URL、status、CORS 信息；
+- debug 模式的 Span name 和关键属性，不要粘贴敏感完整 body；
+- 是否多实例、微前端、Service Worker、代理或浏览器扩展；
+- 最小复现步骤以及预期/实际 Span 名。