@blueking/open-telemetry 0.0.10 → 0.0.12

package/skills/bk-rum-otele/references/telemetry-reference.md

@@ -0,0 +1,228 @@
+<!-- 本文件由 packages/open-telemetry/scripts/gen-skill-references.mjs 从 wikis 自动生成，请勿手改。 -->
+
+# 遥测参考
+
+本页是 SDK **实际产出**的 span 名、metric 名、log 事件名和属性字段的权威速查表，供数据看板、告警规则、后端建模对齐。所有名称都与 SDK 源码保持一致，随版本更新。
+
+> 概念与设计边界见[数据模型](./data-model.md)；本页只做「叫什么名字、带哪些字段」的查询。
+
+## 命名规则
+
+- **信号名**：`browser.*` 表示内置浏览器事件（如 `browser.web_vital`）；`action.<type>`、`custom.<name>` 是运行期动态拼接；`csp.violation`、`websocket.*` 使用领域前缀。
+- **属性 key**：沿用 OpenTelemetry 语义约定的字段用点号（如 `http.request.method`、`exception.type`、`view.id`、`session.id`、`user.id`）；RUM 归一与低基数聚合维度用下划线（如 `span_type`、`result`、`browser_name`、`device_type`）。这一区分是有意为之，字段常量集中定义在 `src/schema/attributes.ts`。
+
+## 公共上下文属性
+
+以下属性由运行时上下文自动挂到**几乎所有** span / log 上（metric 视插件而定），后续各清单不再重复列出：
+
+| key | 类型 | 说明 | 低基数 |
+| --- | --- | --- | --- |
+| `service.name` | string | 应用名（`app.name`） | 是 |
+| `service.version` | string | 应用版本（`app.version`，可选） | 是 |
+| `deployment.environment.name` | string | 环境（`app.environment`） | 是 |
+| `rum.provider` | string | 固定 `blueking` | 是 |
+| `telemetry.sdk.language` | string | 固定 `webjs` | 是 |
+| `user.id` | string | 接入方提供，原样透传 | 否 |
+| `session.id` | string | session 插件生成/轮换 | 否 |
+| `session.has_replay` | boolean | 当前固定 `false` | 是 |
+| `view.id` | string | pageView 维护的 view 实例 ID | 否 |
+| `view.url` | string | 当前 view URL（已脱敏） | 否 |
+| `view.url_path_group` | string | 低基数路由模板 | 是 |
+| `view.loading_type` | string | `initial_load` / `route_change` | 是 |
+| `device_type` | string | `mobile` / `desktop` | 是 |
+| `browser_name` / `browser_version` | string | 浏览器信息 | 是 |
+| `os_name` | string | 操作系统 | 是 |
+| `network.effective_type` | string | 网络质量（`4g` 等） | 是 |
+
+> span 还会带上 `span_type` / `span_subtype` / `result` / `error_type` / `event_label` / `target_label` 等归一字段（见下方[归一字段](#归一字段)）。默认 `attributes.page` 会额外注入 `rum.page.host` / `rum.page.path`。
+
+## Span 清单
+
+| span 名 | span_type | 来源 | 关键属性 | 备注 |
+| --- | --- | --- | --- | --- |
+| `browser.view` | `document` / `route` | pageView 插件 | `url.previous`、`event.source`、`view.end_reason` | 有持续时间，下一次 view 或 pagehide 时结束 |
+| `browser.page_view` | `document`（初始）/ `route`（路由） | pageView 插件 | `document.referrer`（仅初始加载） | 0ms 瞬时事件 |
+| `HTTP <METHOD>` | `http` | fetch / xhr instrumentation | `http.request.method`、`http.response.status_code`、`url.full`、`target_domain`、`target_path_template`、`status_class` | span 名由官方探针决定 |
+| `documentLoad` / `documentFetch` / `resourceFetch` | `document` / `resource` | documentLoad instrumentation | `trace_scene=page_load` | span 名由官方探针决定 |
+| `browser.resource` | `resource` | resource 插件 | `url.full`、`initiator_type`、`transfer_size`、`next_hop_protocol`、`cache_hit`、`resource.encoded_body_size`、`resource.decoded_body_size` | |
+| `browser.web_vital` | `vital` | webVitals 插件 | `vital.metric`、`vital.value`、`vital.rating`、`vital.id`、`rum.navigation.type`、`vital.<lcp\|cls\|inp\|fcp\|ttfb>.*` | 每个指标一条 |
+| `browser.blank_screen` | `error` | blankScreen 插件（判定为白屏时） | `blank_screen.score`、`blank_screen.threshold`、`blank_screen.detected`、`blank_screen.root`、`blank_screen.sample_*`、`blank_screen.center_element`、`blank_screen.dom_node_count` | |
+| `browser.error` | `error` | error 插件（`window.error`） | `exception.*`、`error.source=window.error`、`error.window_count`、`code.filepath`、`code.lineno`、`code.column`、`error.cross_origin` | |
+| `browser.unhandledrejection` | `error` | error 插件（Promise 异常） | `exception.*`、`error.source=unhandledrejection` | |
+| `browser.resource_error` | `error` | error 插件（资源加载失败） | `exception.*`、`error.source=resource`、`url.full`、`html.tag` | |
+| `browser.long_task` | `longtask` | longTask 插件 | `longtask.blocking_duration`、`longtask.attribution_script`、`target_value` | |
+| `browser.route_change` | `route` | routeTiming 插件 | `url.full`、`url.previous`、`route.change.source`、`target_value`（耗时） | |
+| `csp.violation` | `error` | cspViolation 插件 | `csp.blocked_uri`、`csp.violated_directive`、`csp.effective_directive`、`csp.source_file`、`csp.line_number`、`csp.status_code`、`csp.fingerprint`、`csp.window_count`、`csp.original_policy`（窗口首条） | |
+| `websocket.connect` | `custom` | websocket 插件（仅建连阶段） | `url.full`、`url.scheme`、`server.address`、`network.protocol.name=websocket`、`target_domain` | 长连接生命周期不绑定 span |
+| `action.<type>` | `action` | action 插件 & `reportAction()` | `action.type`、`target.tag`、`target.text_short`、`target_label` | 如 `action.click` |
+| `custom.<name>` | `custom` | `reportCustomEvent()` / 自定义插件 | `rum.custom.name`、业务自定义属性 | 带 `error` 时附 `exception.*` |
+
+## Metric 清单
+
+| 名称 | 类型 | 单位 | 主要维度 | 来源 |
+| --- | --- | --- | --- | --- |
+| `browser.web_vital.cls` | Histogram | `1` | `vital.metric`、`vital.rating`、`rum.navigation.type`、`view.url_path_group` | webVitals |
+| `browser.web_vital.duration` | Histogram | `ms` | 同上（FCP/INP/LCP/TTFB 靠 `vital.metric` 区分） | webVitals |
+| `browser.blank_screen.count` | Counter | - | `view.url_path_group`、`blank_screen.root` | blankScreen |
+| `browser.long_task.count` | Counter | - | `view.url_path_group`、`longtask.attribution_script` | longTask |
+| `browser.long_task.duration` | Histogram | `ms` | 同上 | longTask |
+| `browser.route_change.duration` | Histogram | `ms` | `view.url_path_group`、`route.change.source` | routeTiming |
+| `browser.websocket.message.count` | Counter | - | `server.address`、`url.scheme`、`websocket.direction`（in/out） | websocket |
+| `browser.websocket.message.bytes` | Counter | `By` | 同上 | websocket |
+| `browser.websocket.error.count` | Counter | - | `server.address`、`url.scheme`、`websocket.error.phase`（connect/runtime） | websocket |
+| `browser.websocket.connect.duration` | Histogram | `ms` | `server.address`、`url.scheme` | websocket，仅成功建连 |
+
+> 各 metric 还会合并 `attributes.metric` hook 返回的自定义低基数维度；具体附加的公共维度（如 `attributes.page`）因插件而异。**metric 维度务必保持低基数**，不要把 URL、订单号、用户输入等放进来。
+
+## Log 事件清单
+
+| body | severity | 来源 | 关键属性 |
+| --- | --- | --- | --- |
+| `session.start` | INFO | session 插件（首次新建） | `session.id`、`session.start_time`、`session.rotate.reason=init` |
+| `session.rotate` | INFO | session 插件（轮换） | + `session.previous_id`、`session.rotate.reason`（`inactivity` / `maxLifetime`） |
+| `HTTP request completed` | INFO | httpBody 插件（成功请求） | `http.request.method`、`http.response.status_code`、`url.full`、`http.duration` |
+| `HTTP request completed with error` | ERROR | httpBody 插件（错误路径） | + `http.request.body`、`http.response.body`、`http_body.request.truncated`、`http_body.response.truncated`、`exception.*` |
+| `websocket.error` | ERROR | websocket 插件 | `url.full`、`websocket.error.phase`、`websocket.error.window_count` |
+| `websocket.close` | INFO | websocket 插件 | `websocket.close.code`、`websocket.close.reason`、`websocket.close.was_clean` |
+
+> 错误主数据统一走 `error` span（见 Span 清单），SDK **不再**为同一个错误额外 emit error log，避免重复计数。
+
+## 属性字典
+
+### 归一字段
+
+由 `buildRumSpanAttributes` 等构造器写入，用于跨事件类型统一检索。
+
+| key | 类型 | 说明 | 低基数 |
+| --- | --- | --- | --- |
+| `span_type` | string | `document`/`http`/`resource`/`vital`/`error`/`longtask`/`action`/`route`/`custom` | 是 |
+| `span_subtype` | string | 子类型，如 `fetch`/`xhr`/`js`/`promise`/`lcp` | 是 |
+| `result` | string | `success`/`warning`/`error`/`timeout`/`abort` | 是 |
+| `error_type` | string | 错误细分，如 `http_5xx`/`network_timeout`/`slow`/`none` | 是 |
+| `duration_bucket` | string | `<100ms`/`100~500ms`/`500ms~2s`/`>2s` | 是 |
+| `event_label` | string | 中文事件标签，如 `API 调用`/`错误` | 是 |
+| `target_label` | string | 跨类型主标签，用于统一检索 | 中 |
+| `target_value` | number/string/bool | 主数值（状态码、耗时、字节数等） | 否 |
+| `target_domain` | string | 目标域名 | 中 |
+| `target_path_template` | string | 目标低基数路径模板 | 是 |
+| `status_class` | string | HTTP 状态段，如 `2xx`/`5xx` | 是 |
+| `trace_scene` | string | `page_load` / `route_change` | 是 |
+
+### HTTP / Resource
+
+| key | 类型 | 说明 |
+| --- | --- | --- |
+| `http.request.method` | string | 请求方法（大写） |
+| `http.response.status_code` | number | 响应状态码 |
+| `url.full` | string | 完整 URL（已脱敏） |
+| `url.previous` | string | 跳转前 URL |
+| `transfer_size` | number | 传输字节数 |
+| `cache_hit` | boolean | 是否命中缓存 |
+| `next_hop_protocol` | string | 协议，如 `h2` |
+| `initiator_type` | string | 资源发起类型 |
+| `resource.encoded_body_size` / `resource.decoded_body_size` | number | 资源体积 |
+| `http.duration` | number | httpBody 插件记录的请求耗时（ms） |
+| `http.request.body` / `http.response.body` | string | 仅 httpBody 错误路径，经 `redact` 脱敏 |
+| `http_body.request.truncated` / `http_body.response.truncated` | boolean | body 是否被截断 |
+
+### Web Vitals
+
+| key | 类型 | 说明 |
+| --- | --- | --- |
+| `vital.metric` | string | `cls`/`fcp`/`inp`/`lcp`/`ttfb` |
+| `vital.value` | number | 指标值 |
+| `vital.rating` | string | `good`/`needs-improvement`/`poor` |
+| `vital.id` | string | 单条度量唯一 ID（仅 span） |
+| `rum.navigation.type` | string | 导航类型，含 `back-forward-cache` 等 |
+| `vital.lcp.*` / `vital.cls.*` / `vital.inp.*` / `vital.fcp.*` / `vital.ttfb.*` | mixed | attribution 归因明细（仅 span） |
+
+### 错误 / 异常
+
+| key | 类型 | 说明 |
+| --- | --- | --- |
+| `exception.type` | string | 异常类型/名称 |
+| `exception.message` | string | 异常消息 |
+| `exception.message_short` | string | 消息前 80 字符 |
+| `exception.stacktrace` | string | 堆栈 |
+| `exception.stack_top_frame` | string | 栈顶帧 |
+| `exception.fingerprint` | string | 节流分组指纹（djb2 hash） |
+| `error.source` | string | `window.error`/`unhandledrejection`/`resource`/`csp` |
+| `error.handled` | boolean | 是否被业务捕获（自动采集恒为 `false`） |
+| `error.window_count` | number | 当前节流窗口内同指纹总触发次数 |
+| `error.cross_origin` | boolean | 跨域脚本错误（`Script error.`） |
+| `code.filepath` / `code.lineno` / `code.column` | string/number | JS 错误位置 |
+| `html.tag` | string | 资源错误的元素标签 |
+
+### 设备 / 浏览器 / 网络
+
+| key | 类型 | 说明 |
+| --- | --- | --- |
+| `device.id` | string | 设备终身标识（localStorage 持久） |
+| `device.memory` / `device.cpu_cores` | number | 硬件能力 |
+| `device.platform` / `device.mobile` | string/bool | UA-CH 平台信息 |
+| `browser.viewport.width` / `browser.viewport.height` | number | 视口尺寸 |
+| `browser.screen.width` / `browser.screen.height` | number | 屏幕尺寸 |
+| `network.connection_type` / `network.downlink` / `network.rtt` / `network.save_data` | mixed | 网络信息 |
+| `user_agent.name` / `user_agent.version` / `user_agent.os.name` | string | UA 解析结果 |
+
+### 用户动作 / 会话
+
+| key | 类型 | 说明 |
+| --- | --- | --- |
+| `action.type` | string | 动作类型 |
+| `target.tag` | string | 目标元素标签 |
+| `target.text_short` | string | 目标文本前 32 字符 |
+| `session.start_time` | number | 会话开始时间戳 |
+| `session.previous_id` | string | 轮换前的 session.id |
+| `session.rotate.reason` | string | `init`/`inactivity`/`maxLifetime` |
+
+### Long Task
+
+| key | 类型 | 说明 |
+| --- | --- | --- |
+| `longtask.blocking_duration` | number | 长任务时长（ms） |
+| `longtask.attribution_script` | string | 归因脚本 |
+
+### CSP
+
+| key | 类型 | 说明 |
+| --- | --- | --- |
+| `csp.blocked_uri` | string | 被拦截资源（URL 类值已脱敏） |
+| `csp.violated_directive` / `csp.effective_directive` | string | 违反的指令 |
+| `csp.disposition` | string | `enforce` / `report` |
+| `csp.source_file` | string | 触发脚本（已脱敏） |
+| `csp.line_number` / `csp.column_number` | number | 位置 |
+| `csp.status_code` | number | 状态码 |
+| `csp.fingerprint` / `csp.window_count` | string/number | 节流指纹与窗口内触发次数 |
+| `csp.original_policy` | string | 完整策略，仅窗口首条携带 |
+
+### WebSocket
+
+| key | 类型 | 说明 |
+| --- | --- | --- |
+| `url.scheme` | string | `ws` / `wss` |
+| `server.address` | string | 目标 host |
+| `network.protocol.name` | string | 固定 `websocket` |
+| `websocket.direction` | string | `in` / `out`（仅 metric） |
+| `websocket.error.phase` | string | `connect` / `runtime` |
+| `websocket.error.window_count` | number | 错误日志节流窗口内触发次数 |
+| `websocket.close.code` / `websocket.close.reason` / `websocket.close.was_clean` | mixed | 关闭事件详情 |
+
+### 白屏
+
+| key | 类型 | 说明 |
+| --- | --- | --- |
+| `blank_screen.score` | number | 空白样本比例 |
+| `blank_screen.threshold` | number | 判定阈值 |
+| `blank_screen.detected` | boolean | 是否判为白屏 |
+| `blank_screen.root` | string | 采样根选择器 |
+| `blank_screen.sample_total` / `blank_screen.sample_valid` / `blank_screen.sample_loading` | number | 采样统计 |
+| `blank_screen.center_element` | string | 视口中心元素选择器 |
+| `blank_screen.dom_node_count` | number | body 下 DOM 节点总数 |
+
+### 自定义事件
+
+| key | 类型 | 说明 |
+| --- | --- | --- |
+| `rum.custom.name` | string | `reportCustomEvent()` 的事件名 |
+| `rum.page.host` / `rum.page.path` | string | 默认 `attributes.page` 注入的页面上下文 |

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

@@ -0,0 +1,239 @@
+<!-- 本文件由 packages/open-telemetry/scripts/gen-skill-references.mjs 从 wikis 自动生成，请勿手改。 -->
+
+# 调试与排障
+
+本页按接入阶段常见问题组织。
+
+## 本地看不到数据
+
+先打开 debug，并使用 simple span processor。
+
+```ts
+new BkOpenTelemetry({
+  debug: true,
+  spanProcessor: 'simple',
+  sampling: {
+    rate: 1,
+  },
+  transport: {
+    endpoint: 'http://localhost:4318',
+  },
+});
+```
+
+检查点：
+
+- Collector 是否监听 `4318`。
+- 浏览器 Network 中是否有 `/v1/traces`、`/v1/metrics`、`/v1/logs` 请求。
+- 是否被采样丢弃。
+- `enabled` 是否为 `false`。
+
+## 手动事件没有上报
+
+`reportAction()` 和 `reportCustomEvent()` 受采样控制。未采样时会静默丢弃。
+
+```ts
+new BkOpenTelemetry({
+  debug: true,
+  sampling: {
+    rate: 1,
+  },
+});
+```
+
+## 自定义插件注册失败
+
+`use()` 必须在 `start()` 前调用。如果需要注册插件，关闭自动启动。
+
+```ts
+const bkOT = new BkOpenTelemetry({
+  autoStart: false,
+});
+
+bkOT.use(myPlugin);
+
+await bkOT.start();
+```
+
+## 空白屏误报
+
+SPA 应用应配置 `rootSelector` 和 loading/skeleton 忽略选择器。
+
+```ts
+new BkOpenTelemetry({
+  plugins: {
+    blankScreen: {
+      rootSelector: '#app',
+      ignoreSelectors: ['.bk-loading', '.skeleton'],
+      checkDelay: 5000,
+    },
+  },
+});
+```
+
+## 接口 span 太多
+
+先确认是否有多个 SDK 实例重复初始化，尤其是微前端场景。其次可以关闭不需要的 instrumentation。
+
+```ts
+new BkOpenTelemetry({
+  instrumentations: {
+    fetch: true,
+    xhr: false,
+  },
+});
+```
+
+## URL 或用户信息泄露风险
+
+配置 URL 和属性脱敏。
+
+```ts
+new BkOpenTelemetry({
+  privacy: {
+    redactUrl: url => url.replace(/([?&]token=)[^&]+/g, '$1***'),
+    redactAttributes: attributes => {
+      const next = { ...attributes };
+      delete next['user.email'];
+      return next;
+    },
+  },
+});
+```
+
+## Long Task 没有数据
+
+Long Task API 并非所有浏览器都支持。Firefox 不支持时插件会跳过。
+
+```ts
+new BkOpenTelemetry({
+  plugins: {
+    longTask: {
+      threshold: 50,
+    },
+  },
+});
+```
+
+## HTTP body 没有数据
+
+`httpBody` 只在错误路径采集，且默认关闭。
+
+```ts
+new BkOpenTelemetry({
+  plugins: {
+    httpBody: {
+      maxBodySize: 4096,
+      redact: ({ body }) => body,
+    },
+  },
+});
+```
+
+## WebSocket 采集异常
+
+WebSocket 插件会 Proxy 全局 `WebSocket`。如果应用或第三方库也 patch 了 WebSocket，应避免重复 patch。
+
+```ts
+new BkOpenTelemetry({
+  plugins: {
+    websocket: true,
+  },
+});
+```
+
+# FAQ
+
+## SDK 会采集哪些数据？
+
+默认采集页面访问、资源加载、fetch/xhr、JavaScript 错误、Web Vitals、空白屏、设备信息和会话信息。动作、HTTP body、Long Task、路由耗时、CSP、WebSocket 默认关闭。
+
+```ts
+new BkOpenTelemetry({
+  plugins: {
+    action: true,
+    longTask: true,
+    routeTiming: true,
+    websocket: true,
+  },
+});
+```
+
+## `user.id` 会被 SDK 脱敏吗？
+
+不会。`user.id` 由接入方提供，SDK 原样透传。如果业务要求 hash，需要在传入前处理。
+
+```ts
+new BkOpenTelemetry({
+  user: {
+    id: hashUserId(rawUserId),
+  },
+});
+```
+
+## `sampling.rate` 是 trace 级采样吗？
+
+不是。它是会话级 sticky 采样，同一会话内保持一致。
+
+```ts
+new BkOpenTelemetry({
+  sampling: {
+    rate: 0.2,
+  },
+});
+```
+
+## 为什么开启了 userInteraction 还需要 action 插件？
+
+`userInteraction` 是 OpenTelemetry 官方 instrumentation，产生的是官方用户交互 span；`action` 插件和 `reportAction()` 会写入 SDK 的 RUM action 归一字段。需要稳定的业务动作模型时，推荐使用 `action` 或 `reportAction()`。
+
+```ts
+bkOT.reportAction({
+  type: 'click',
+  targetText: '确认提交',
+  attributes: {
+    'biz.scene': 'strategy-create',
+  },
+});
+```
+
+## 可以只上报 traces，不上报 metrics/logs 吗？
+
+当前 SDK 会初始化三类 provider。可以在 Collector 或网关层按信号丢弃，也可以为不同信号配置不同 endpoint。
+
+```ts
+new BkOpenTelemetry({
+  transport: {
+    signals: {
+      endpoints: {
+        traces: 'https://trace-gateway.example.com/v1/traces',
+        metrics: 'https://metric-gateway.example.com/v1/metrics',
+        logs: 'https://log-gateway.example.com/v1/logs',
+      },
+    },
+  },
+});
+```
+
+## 为什么不建议多个实例同时运行？
+
+fetch、xhr、userInteraction、websocket 等能力会 patch 全局 API。多个实例可能重复 patch、重复上报或互相影响。
+
+```ts
+if (!window.__BK_RUM_INSTANCE__) {
+  window.__BK_RUM_INSTANCE__ = new BkOpenTelemetry({
+    transport: {
+      endpoint: 'https://rum-collector.example.com',
+    },
+  });
+}
+```
+
+## 如何在页面离开前尽量 flush？
+
+SDK 已监听部分页面生命周期事件。业务也可以在关键流程后主动调用 `flush()`。
+
+```ts
+await saveCriticalConfig();
+await bkOT.flush();
+```