@blueking/open-telemetry 0.0.10 → 0.0.12

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

@@ -0,0 +1,451 @@
+<!-- 本文件由 packages/open-telemetry/scripts/gen-skill-references.mjs 从 wikis 自动生成，请勿手改。 -->
+
+# 插件总览
+
+插件是 `@blueking/open-telemetry` 的能力边界。SDK 内部先启动官方 instrumentation，再按采样结果启动 RUM 插件。
+
+## 默认插件组合
+
+```ts
+new BkOpenTelemetry({
+  instrumentations: {
+    documentLoad: true,
+    fetch: true,
+    xhr: true,
+    userInteraction: true,
+  },
+  plugins: {
+    pageView: true,
+    resource: true,
+    error: true,
+    webVitals: true,
+    blankScreen: true,
+    device: true,
+    session: true,
+  },
+});
+```
+
+## 能力分类
+
+| 分类       | 插件                                                              | 主要信号                      |
+| ---------- | ----------------------------------------------------------------- | ----------------------------- |
+| 基础上下文 | `session`、`device`、`pageView`                                   | log、span、runtime attributes |
+| 性能体验   | `resource`、`webVitals`、`blankScreen`、`longTask`、`routeTiming` | span、metric、log             |
+| 错误安全   | `error`、`cspViolation`                                           | span、log                     |
+| 网络扩展   | `httpBody`、`websocket`                                           | log、span、metric             |
+| 用户行为   | `action`、`reportAction()`                                        | span                          |
+
+## 插件启用规则
+
+RUM 插件只在会话命中采样时启动。未命中采样时，SDK 仍可注册核心 provider，但不会启动主动产生数据的插件。
+
+```ts
+new BkOpenTelemetry({
+  sampling: {
+    rate: 0.1,
+  },
+  plugins: {
+    pageView: true,
+    error: true,
+    webVitals: true,
+    action: true,
+  },
+});
+```
+
+## 选择建议
+
+- 首次接入：使用默认插件即可。
+- 需要分析慢页面：开启 `longTask` 和 `routeTiming`。
+- 需要分析接口错误体：开启 `httpBody`，并配置 `redact`。
+- 需要分析 CSP：开启 `cspViolation`。
+- 需要分析实时通信：开启 `websocket`，注意避免多个 SDK 实例重复 patch。
+
+# 基础采集插件
+
+基础插件负责建立 RUM 数据的关联上下文：哪个用户、哪个会话、哪个页面、哪个设备。
+
+## session
+
+`session` 插件维护 `session.id`，并在会话开始和轮换时写入 log。默认开启。
+
+默认规则：
+
+- 不活跃超过 30 分钟后轮换。
+- 会话最长 24 小时。
+- storage key 会按 endpoint host 隔离。
+
+```ts
+new BkOpenTelemetry({
+  plugins: {
+    session: {
+      inactivityMs: 30 * 60 * 1000,
+      maxLifetimeMs: 24 * 60 * 60 * 1000,
+      storageKey: 'bk-rum-session',
+    },
+  },
+});
+```
+
+**产出遥测**：log `session.start` / `session.rotate`，并维护运行时属性 `session.id`。
+
+## device
+
+`device` 插件写入设备、浏览器、系统、视口、网络等运行时属性。默认开启。
+
+```ts
+new BkOpenTelemetry({
+  plugins: {
+    device: {
+      storageKey: 'bk-rum-device',
+    },
+  },
+});
+```
+
+后续 span/log 会自动带上这些属性，便于按浏览器、系统、网络类型下钻。
+
+**产出遥测**：只写入运行时属性（如 `device.id`、`browser_name`、`os_name`、`device_type`、`network.effective_type`），本身不单独产生 span/metric/log。
+
+## pageView
+
+`pageView` 插件负责初始页面和 SPA 路由 view。它会维护：
+
+- `view.id`
+- `view.url`
+- `view.url_path_group`
+- `view.loading_type`
+
+```ts
+new BkOpenTelemetry({
+  route: {
+    getPathGroup: url => {
+      const { pathname } = new URL(url, window.location.href);
+      return pathname.replace(/\/\d+/g, '/:id');
+    },
+  },
+  plugins: {
+    pageView: true,
+  },
+});
+```
+
+**产出遥测**：span `browser.view`（有持续时间）与 `browser.page_view`（0ms 瞬时），并维护 `view.*` 运行时属性。
+
+## action
+
+`action` 插件默认关闭。开启后可以自动监听 click、submit、keydown 等事件，并生成 `action` span。
+
+**产出遥测**：span `action.<type>`（如 `action.click`，`span_type=action`）。`reportAction()` 走同一套字段。
+
+```ts
+new BkOpenTelemetry({
+  plugins: {
+    action: {
+      eventNames: ['click', 'submit', 'keydown'],
+    },
+  },
+});
+```
+
+对关键业务动作，推荐使用 `reportAction()` 显式上报，字段更稳定。
+
+```ts
+bkOT.reportAction({
+  type: 'click',
+  targetTag: 'button',
+  targetText: '立即支付',
+  attributes: {
+    'biz.order_id': '202605270001',
+  },
+});
+```
+
+# 体验与性能插件
+
+体验类插件关注页面加载、资源、核心 Web 指标、空白屏、主线程阻塞和 SPA 路由切换。
+
+## resource
+
+`resource` 插件默认开启，基于 PerformanceObserver 采集静态资源加载 span。
+
+```ts
+new BkOpenTelemetry({
+  plugins: {
+    resource: true,
+  },
+});
+```
+
+常见字段包括 `initiator_type`、`transfer_size`、`next_hop_protocol`、`target_domain`、`target_path_template`。
+
+**产出遥测**：span `browser.resource`（`span_type=resource`）。
+
+## webVitals
+
+`webVitals` 插件默认开启，采集 CLS、FCP、INP、LCP、TTFB。它会同时产生 metric 和 span：metric 用于聚合，span 用于定位具体页面和归因信息。
+
+**产出遥测**：metric `browser.web_vital.cls`（unit `1`）、`browser.web_vital.duration`（unit `ms`，FCP/INP/LCP/TTFB 共用）+ span `browser.web_vital`（`span_type=vital`，含 attribution 归因）。
+
+```ts
+new BkOpenTelemetry({
+  plugins: {
+    webVitals: true,
+  },
+});
+```
+
+## blankScreen
+
+`blankScreen` 插件默认开启。它会在页面加载后一段时间检查视口采样点，如果空白比例超过阈值，则上报空白屏结果。
+
+```ts
+new BkOpenTelemetry({
+  plugins: {
+    blankScreen: {
+      rootSelector: '#app',
+      checkDelay: 3000,
+      threshold: 0.8,
+      ignoreSelectors: ['.global-loading', '.skeleton'],
+    },
+  },
+});
+```
+
+SPA 应用建议配置 `rootSelector`，否则默认以整个页面判断，容易受外层布局影响。
+
+**产出遥测**（仅判定为白屏时）：metric `browser.blank_screen.count` + error span `browser.blank_screen`（`span_type=error`）。
+
+## longTask
+
+`longTask` 插件默认关闭。开启后通过 Long Task API 采集主线程阻塞。
+
+```ts
+new BkOpenTelemetry({
+  plugins: {
+    longTask: {
+      threshold: 80,
+    },
+  },
+});
+```
+
+Firefox 对 Long Task API 支持有限，不支持时插件会跳过。
+
+**产出遥测**：metric `browser.long_task.count` / `browser.long_task.duration`（unit `ms`）+ span `browser.long_task`（`span_type=longtask`）。
+
+## routeTiming
+
+`routeTiming` 插件默认关闭。它会监听 SPA 路由变化，并通过双 `requestAnimationFrame` 和 `setTimeout` 估算路由切换到渲染稳定的耗时。
+
+**产出遥测**：metric `browser.route_change.duration`（unit `ms`）+ span `browser.route_change`（`span_type=route`）。tab 切到后台时数据会被丢弃，避免污染 P99。
+
+```ts
+new BkOpenTelemetry({
+  plugins: {
+    routeTiming: true,
+  },
+});
+```
+
+如果业务路由有异步数据加载，建议结合自定义事件补充更精确的业务完成点。
+
+```ts
+const span = bkOT.startSpan('custom.route_data_ready', {
+  'route.name': 'alarm-detail',
+});
+
+await loadAlarmDetail();
+span.end();
+```
+
+# 错误与安全插件
+
+错误类插件帮助定位 JavaScript 异常、Promise 异常、资源加载失败、CSP 违规和空白屏等问题。
+
+## error
+
+`error` 插件默认开启，监听：
+
+- `window.error`
+- `unhandledrejection`
+- 资源加载错误
+
+插件会生成 error span，并使用 fingerprint 做窗口内节流，避免相同错误在短时间内刷屏。
+
+**产出遥测**：span `browser.error`（JS 错误）、`browser.unhandledrejection`（Promise 异常）、`browser.resource_error`（资源加载失败），均为 `span_type=error`，带 `exception.*`、`error.source`、`error.window_count`。
+
+```ts
+new BkOpenTelemetry({
+  plugins: {
+    error: {
+      maxPerWindow: 5,
+      windowMs: 60_000,
+    },
+  },
+});
+```
+
+## 手动上报错误事件
+
+业务捕获到错误后，可以通过 `reportCustomEvent()` 上报。
+
+```ts
+try {
+  await submitOrder();
+} catch (error) {
+  bkOT.reportCustomEvent({
+    name: 'submit_order_failed',
+    error: error instanceof Error ? error : new Error(String(error)),
+    attributes: {
+      'biz.order_id': '202605270001',
+    },
+  });
+}
+```
+
+## cspViolation
+
+`cspViolation` 插件默认关闭。开启后监听浏览器 `securitypolicyviolation` 事件，并写入 error span。
+
+**产出遥测**：span `csp.violation`（`span_type=error`），带 `csp.*` 字段；完整策略 `csp.original_policy` 仅在节流窗口首条携带。
+
+```ts
+new BkOpenTelemetry({
+  plugins: {
+    cspViolation: true,
+  },
+});
+```
+
+建议与站点 CSP 响应头一起使用。
+
+```http
+Content-Security-Policy: default-src 'self'; report-uri /csp-report
+```
+
+## blankScreen 与错误排查
+
+空白屏通常是错误、资源失败或首屏渲染失败的结果。建议同时开启 `blankScreen`、`error`、`resource`。
+
+```ts
+new BkOpenTelemetry({
+  plugins: {
+    blankScreen: {
+      rootSelector: '#app',
+    },
+    error: true,
+    resource: true,
+  },
+});
+```
+
+通过 `view.id` 和 `session.id` 可以把空白屏、JS 错误、资源失败关联到同一次页面访问。
+
+# 网络与扩展插件
+
+网络类能力覆盖 fetch/xhr、HTTP body 错误路径和 WebSocket。由于这些能力会 patch 浏览器原生 API，微前端或多 SDK 实例场景需要特别注意避免重复初始化。
+
+## fetch / xhr instrumentation
+
+fetch 和 xhr 默认开启，会生成 HTTP span，并对 URL 做脱敏处理。
+
+**产出遥测**：HTTP span（span 名由官方探针决定，如 `HTTP GET`，`span_type=http`），带 `http.request.method`、`http.response.status_code`、`url.full`、`status_class` 等。
+
+```ts
+new BkOpenTelemetry({
+  privacy: {
+    redactUrl: url => url.replace(/\/orders\/\d+/g, '/orders/:id'),
+  },
+  instrumentations: {
+    fetch: true,
+    xhr: true,
+  },
+});
+```
+
+### traceparent 透传（前后端 trace 串联）
+
+fetch/xhr 请求会自动给**同源**请求注入 W3C `traceparent` 请求头（内含 OpenTelemetry traceId）。后台 API 通常是跨域的，需要通过 `propagateTraceHeaderUrls` 显式纳入注入范围：
+
+```ts
+new BkOpenTelemetry({
+  instrumentations: {
+    // 字符串子串 / 正则 / 数组 / (url) => boolean / 'all' 均可
+    propagateTraceHeaderUrls: ['api.example.com', /\.internal\.com\//],
+  },
+});
+```
+
+向跨域服务注入自定义头会触发 CORS 预检，目标服务需在 `Access-Control-Allow-Headers` 中放行 `traceparent`（以及按需的 `tracestate`）。`propagateTraceHeaderUrls` 的完整取值（`'all'` / 字符串 / 正则 / 数组 / 函数）见[配置总览](./configuration.md#instrumentation-配置)。
+
+## httpBody
+
+`httpBody` 默认关闭。开启后只在错误路径采集请求/响应 body，适合排查接口错误，但必须配置脱敏策略。
+
+**产出遥测**：log `HTTP request completed`（成功，INFO）/ `HTTP request completed with error`（错误，ERROR，带 `http.request.body`、`http.response.body`、`http_body.*.truncated`）。
+
+```ts
+new BkOpenTelemetry({
+  plugins: {
+    httpBody: {
+      maxBodySize: 10 * 1024,
+      redact: ({ body, status, type }) => {
+        if (status && status < 500) {
+          return '[body hidden for non-5xx error]';
+        }
+        return type === 'request' ? '[request body redacted]' : body;
+      },
+    },
+  },
+});
+```
+
+## websocket
+
+`websocket` 默认关闭。开启后会用 Proxy 包装 WebSocket，采集连接、消息大小、错误和关闭事件。
+
+**产出遥测**：span `websocket.connect`（`span_type=custom`，仅建连阶段）；metric `browser.websocket.message.count` / `.message.bytes` / `.error.count` / `.connect.duration`；log `websocket.error` / `websocket.close`。
+
+```ts
+new BkOpenTelemetry({
+  plugins: {
+    websocket: true,
+  },
+});
+```
+
+业务发送消息时无需改造。
+
+```ts
+const socket = new WebSocket('wss://message.example.com/ws');
+
+socket.addEventListener('open', () => {
+  socket.send(JSON.stringify({ type: 'ping' }));
+});
+```
+
+## 自定义网络事件
+
+如果业务已有请求封装，也可以在封装层补充更稳定的业务 span。
+
+```ts
+export const requestWithRum = async <T>(url: string, init?: RequestInit): Promise<T> => {
+  const span = bkOT.startSpan('custom.biz_request', {
+    'biz.request.url': url.replace(/\/\d+/g, '/:id'),
+    'biz.request.method': init?.method || 'GET',
+  });
+
+  try {
+    const response = await fetch(url, init);
+    span.setAttribute('http.response.status_code', response.status);
+    return response.json() as Promise<T>;
+  } catch (error) {
+    span.recordException(error as Error);
+    throw error;
+  } finally {
+    span.end();
+  }
+};
+```

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

@@ -0,0 +1,117 @@
+<!-- 本文件由 packages/open-telemetry/scripts/gen-skill-references.mjs 从 wikis 自动生成，请勿手改。 -->
+
+# 隐私与公共属性
+
+RUM 数据常包含 URL、用户标识、接口路径、错误信息和业务属性。SDK 不会替接入方猜测哪些字段敏感，因此提供 `privacy` 和 `attributes` 两类入口，由业务显式控制。
+
+## URL 脱敏
+
+`privacy.redactUrl` 会处理写入 attribute 的 URL 类字段。
+
+```ts
+new BkOpenTelemetry({
+  privacy: {
+    redactUrl: url =>
+      url
+        .replace(/([?&]token=)[^&]+/g, '$1***')
+        .replace(/([?&]bk_ticket=)[^&]+/g, '$1***')
+        .replace(/\/users\/[^/?#]+/g, '/users/:id'),
+  },
+});
+```
+
+## 属性脱敏
+
+`privacy.redactAttributes` 会在 SDK 自定义插件 emit 前过滤属性，适合删除 authorization、手机号、邮箱等字段。
+
+```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;
+    },
+  },
+});
+```
+
+## 公共属性
+
+`attributes` 提供四类 hook：
+
+- `page`：页面、动作、错误等需要页面上下文的事件。
+- `metric`：metric 维度，必须避免高基数字段。
+- `error`：错误事件补充属性。
+- `custom`：手动自定义事件补充属性。
+
+```ts
+new BkOpenTelemetry({
+  attributes: {
+    page: () => ({
+      'biz.space_id': window.__BK_SPACE_ID__,
+      'biz.project_id': window.__BK_PROJECT_ID__,
+    }),
+    metric: () => ({
+      'biz.app_code': 'bk-monitor',
+    }),
+    error: () => ({
+      'biz.release_channel': window.__BK_RELEASE_CHANNEL__,
+    }),
+    custom: () => ({
+      'biz.scene': 'checkout',
+    }),
+  },
+});
+```
+
+## 用户标识
+
+`user.id` 由接入方提供，SDK 原样透传，不 hash、不脱敏、不改写。如果业务要求 hash 或匿名化，应在传给 SDK 前完成。
+
+```ts
+new BkOpenTelemetry({
+  user: {
+    id: hashUserId(window.__BK_USER__?.id),
+  },
+});
+```
+
+## HTTP body 脱敏
+
+`httpBody` 默认关闭。开启后只在错误路径采集请求/响应 body，并支持 `redact`。
+
+```ts
+new BkOpenTelemetry({
+  plugins: {
+    httpBody: {
+      maxBodySize: 4096,
+      redact: ({ body, contentType, type }) => {
+        if (contentType?.includes('application/json')) {
+          return body.replace(/"password"\s*:\s*"[^"]+"/g, '"password":"***"');
+        }
+        return type === 'request' ? '[request body redacted]' : body;
+      },
+    },
+  },
+});
+```
+
+## 低基数路由
+
+路由模板会写入 `view.url_path_group` 和部分目标路径字段。推荐把动态 ID 替换成模板，避免指标维度爆炸。
+
+```ts
+new BkOpenTelemetry({
+  route: {
+    getPathGroup: url => {
+      const { pathname } = new URL(url, window.location.href);
+      return pathname
+        .replace(/\/\d+/g, '/:id')
+        .replace(/\/[0-9a-f]{24}/g, '/:objectId');
+    },
+  },
+});
+```