@blueking/open-telemetry 0.0.10 → 0.0.12

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

@@ -0,0 +1,318 @@
+<!-- 本文件由 packages/open-telemetry/scripts/gen-skill-references.mjs 从 wikis 自动生成，请勿手改。 -->
+
+# 配置总览
+
+SDK 的配置入口是 `BkOTOptions`。推荐先完成 `app`、`transport`、`sampling`、`route`、`privacy` 五类基础配置，再按需打开插件。
+
+## 完整配置示例
+
+```ts
+import { BkOpenTelemetry } from '@blueking/open-telemetry';
+
+const bkOT = new BkOpenTelemetry({
+  enabled: true,
+  autoStart: true,
+  debug: false,
+  app: {
+    name: 'bk-monitor-web',
+    environment: 'production',
+    version: '1.4.2',
+  },
+  user: {
+    id: 'user-12345',
+  },
+  transport: {
+    endpoint: 'https://rum-collector.example.com',
+    token: 'report-token',
+    headers: {
+      'x-bk-tenant-id': 'system',
+    },
+  },
+  sampling: {
+    rate: 0.2,
+  },
+  route: {
+    getPathGroup: url => new URL(url).pathname.replace(/\/\d+/g, '/:id'),
+  },
+  privacy: {
+    redactUrl: url => url.replace(/([?&](token|bk_ticket)=)[^&]+/g, '$1***'),
+    redactAttributes: attributes => attributes,
+  },
+  attributes: {
+    page: () => ({
+      'biz.space_id': window.__BK_SPACE_ID__,
+    }),
+    custom: () => ({
+      'biz.app_code': 'bk-monitor',
+    }),
+  },
+  instrumentations: {
+    documentLoad: true,
+    fetch: true,
+    xhr: true,
+    userInteraction: true,
+  },
+  plugins: {
+    pageView: true,
+    resource: true,
+    error: true,
+    webVitals: true,
+    blankScreen: {
+      rootSelector: '#app',
+      checkDelay: 3000,
+      threshold: 0.8,
+    },
+    session: true,
+    device: true,
+    action: false,
+    httpBody: false,
+    longTask: false,
+    routeTiming: false,
+    cspViolation: false,
+    websocket: false,
+  },
+});
+
+export default bkOT;
+```
+
+## 顶层配置
+
+| 配置 | 默认值 | 说明 |
+| --- | --- | --- |
+| `enabled` | `true` | 为 `false` 时不注册 provider，也不启动插件。 |
+| `autoStart` | `true` | 构造后自动调用 `start()`。需要注册自定义插件时建议设为 `false`。 |
+| `debug` | `false` | 打印 exporter 输出和部分调试日志。 |
+| `app.name` | `unknown_service` | 写入 `service.name`。 |
+| `app.environment` | `production` | 写入 `deployment.environment.name`。 |
+| `app.version` | `undefined` | 写入 `service.version`。 |
+| `spanProcessor` | `batch` | 可选 `batch` 或 `simple`。本地调试可用 `simple`。 |
+
+### 固定行为（当前不可配置）
+
+- **Metric 上报间隔固定 60s**（`PeriodicExportingMetricReader`），暂不开放配置。
+- SDK 会向 resource 注入固定属性：`rum.provider=blueking`、`telemetry.sdk.language=webjs`，以及由 `app` 派生的 `service.name`、`service.version`、`deployment.environment.name`。
+
+示例：只在生产环境开启。
+
+```ts
+new BkOpenTelemetry({
+  enabled: import.meta.env.PROD,
+  app: {
+    name: 'bk-monitor-web',
+    environment: import.meta.env.MODE,
+  },
+  transport: {
+    endpoint: 'https://rum-collector.example.com',
+  },
+});
+```
+
+## Instrumentation 配置
+
+| 配置 | 默认值 | 说明 |
+| --- | --- | --- |
+| `documentLoad` | `true` | 采集文档加载和导航性能 span。 |
+| `fetch` | `true` | patch `fetch`，采集 HTTP span，并支持同源 traceparent。 |
+| `xhr` | `true` | patch `XMLHttpRequest`，采集 HTTP span。 |
+| `userInteraction` | `true` | 使用 OpenTelemetry 官方用户交互 instrumentation。 |
+| `propagateTraceHeaderUrls` | `undefined`（仅同源） | 把跨域后台 API 纳入 `traceparent`（含 OpenTelemetry traceId）注入范围。 |
+
+`propagateTraceHeaderUrls` 用于让 fetch/xhr 请求在调用后台 API 时带上 W3C `traceparent` 请求头，实现前后端 trace 串联。同源请求始终注入，该配置只用于在此基础上扩展跨域目标，取值支持：
+
+- `'all'`：所有请求都注入（含跨域，使用前确认隐私/CORS 影响）。
+- `string`：URL 包含该子串即注入，例如 `'api.example.com'`。
+- `RegExp`：URL 匹配该正则即注入。
+- 上述字符串/正则组成的数组：命中任意一个即注入。
+- `(url: string) => boolean`：完全自定义判断。
+
+```ts
+new BkOpenTelemetry({
+  instrumentations: {
+    // 给所有调用 api.example.com / api.internal.com 的后台请求注入 traceparent
+    propagateTraceHeaderUrls: [/https:\/\/api\.example\.com/, 'api.internal.com'],
+  },
+});
+```
+
+> 注意：向跨域服务注入自定义头会触发 CORS 预检，目标服务需在 `Access-Control-Allow-Headers` 中放行 `traceparent`（以及按需的 `tracestate`），否则请求会被浏览器拦截。
+
+示例：关闭接口自动采集。
+
+```ts
+new BkOpenTelemetry({
+  instrumentations: {
+    fetch: false,
+    xhr: false,
+  },
+});
+```
+
+## 插件默认开关
+
+| 插件 | 默认状态 | 说明 |
+| --- | --- | --- |
+| `pageView` | 开 | 初始页面和 SPA 路由 view。 |
+| `resource` | 开 | 静态资源 PerformanceObserver。 |
+| `error` | 开 | JS error、unhandledrejection、资源错误。 |
+| `webVitals` | 开 | CLS、FCP、INP、LCP、TTFB。 |
+| `blankScreen` | 开 | 延迟检测页面空白比例。 |
+| `device` | 开 | 设备、浏览器、OS、viewport、网络属性。 |
+| `session` | 开 | session.id 生成、轮换和跨 tab 同步。 |
+| `action` | 关 | 自动采集 click、submit、keydown 等动作。 |
+| `httpBody` | 关 | 错误路径采集请求/响应 body。 |
+| `longTask` | 关 | Long Task API。 |
+| `routeTiming` | 关 | SPA 路由切换渲染耗时估算。 |
+| `cspViolation` | 关 | CSP 违规 error span。 |
+| `websocket` | 关 | WebSocket 连接、消息、错误、关闭。 |
+
+示例：开启高成本插件。
+
+```ts
+new BkOpenTelemetry({
+  plugins: {
+    longTask: {
+      threshold: 80,
+    },
+    httpBody: {
+      maxBodySize: 4096,
+      redact: ({ body, type }) => (type === 'request' ? '[redacted request body]' : body),
+    },
+    websocket: true,
+  },
+});
+```
+
+# 上报与采样
+
+SDK 使用 OTLP HTTP exporter 分别上报 traces、metrics、logs。默认 endpoint 是 `http://localhost:4318`，会自动拼接 `/v1/traces`、`/v1/metrics`、`/v1/logs`。
+
+## 统一 endpoint
+
+```ts
+new BkOpenTelemetry({
+  transport: {
+    endpoint: 'https://rum-collector.example.com',
+    token: 'report-token',
+  },
+});
+```
+
+实际使用的上报地址为：
+
+- traces：`https://rum-collector.example.com/v1/traces`
+- metrics：`https://rum-collector.example.com/v1/metrics`
+- logs：`https://rum-collector.example.com/v1/logs`
+
+## 分信号 endpoint
+
+如果 traces、metrics、logs 由不同网关接收，可以使用 `transport.signals`。
+
+```ts
+new BkOpenTelemetry({
+  transport: {
+    endpoint: 'https://rum-collector.example.com',
+    headers: {
+      'x-bk-app-code': 'bk-monitor',
+    },
+    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',
+      },
+      traces: {
+        timeoutMillis: 5000,
+        concurrencyLimit: 4,
+      },
+      logs: {
+        headers: {
+          'x-bk-log-source': 'browser',
+        },
+      },
+    },
+  },
+});
+```
+
+`transport.token` 会生成默认 `Authorization: Bearer <token>`，显式配置的 `headers` 会继续合并进去。
+
+## 避免自循环采集
+
+SDK 内置 `FilteringSpanProcessor`，会过滤指向自身 OTLP endpoint 的 span，避免上报请求本身再次被 fetch/xhr instrumentation 采集。
+
+示例：自定义 Collector 地址时无需手动忽略自身上报。
+
+```ts
+new BkOpenTelemetry({
+  transport: {
+    endpoint: 'https://rum-collector.example.com/otlp',
+  },
+  instrumentations: {
+    fetch: true,
+    xhr: true,
+  },
+});
+```
+
+## 同源 traceparent 传播
+
+fetch/xhr instrumentation 会给符合条件的同源请求注入 W3C `traceparent`，用于打通前后端 trace。跨域请求是否能传播还取决于服务端 CORS 是否允许该 header。
+
+示例：前端请求同源 API。
+
+```ts
+await fetch('/api/orders/202605270001', {
+  method: 'GET',
+});
+```
+
+## 会话级 sticky 采样
+
+`sampling.rate` 范围是 `0` 到 `1`。SDK 会将采样结果保存在 session 维度，保证同一会话内行为一致。
+
+```ts
+new BkOpenTelemetry({
+  sampling: {
+    rate: 0.05,
+  },
+  transport: {
+    endpoint: 'https://rum-collector.example.com',
+  },
+});
+```
+
+需要注意：
+
+- `rate: 1` 表示全量上报。
+- `rate: 0` 表示 RUM 插件和手动事件都不上报。
+- 未命中采样时，主动产生数据的 RUM 插件不会启动。
+- 调试时建议临时设置 `rate: 1` 和 `debug: true`。
+
+## Batch 与 Simple Processor
+
+默认使用 batch 处理器，适合生产环境。调试时可以用 simple 处理器减少等待。
+
+```ts
+new BkOpenTelemetry({
+  debug: true,
+  spanProcessor: 'simple',
+  transport: {
+    endpoint: 'http://localhost:4318',
+  },
+});
+```
+
+批量参数可以通过 `spanBatch` 调整。
+
+```ts
+new BkOpenTelemetry({
+  spanProcessor: 'batch',
+  spanBatch: {
+    maxQueueSize: 2048,
+    maxExportBatchSize: 256,
+    scheduledDelayMillis: 5000,
+    exportTimeoutMillis: 30000,
+  },
+});
+```

package/skills/bk-rum-otele/references/custom-plugin.md

@@ -0,0 +1,158 @@
+<!-- 本文件由 packages/open-telemetry/scripts/gen-skill-references.mjs 从 wikis 自动生成，请勿手改。 -->
+
+# 自定义插件
+
+自定义插件适合封装业务事件、补充特定浏览器 API 采集，或接入额外 OpenTelemetry instrumentation。
+
+## 插件契约
+
+插件由 `createPlugin()` 创建，核心字段是 `name`、`enabled`、`init`、`flush`、`shutdown`。
+
+```ts
+import { createPlugin } from '@blueking/open-telemetry';
+
+const bizPlugin = createPlugin({
+  name: 'biz-plugin',
+  enabled: config => config.enabled,
+  init(context) {
+    const span = context.startSpan('custom.biz_plugin_init', {
+      'biz.plugin': 'ready',
+    });
+    span.end();
+  },
+  flush() {
+    // 可在这里刷新插件内部缓存
+  },
+  shutdown() {
+    // 可在这里移除事件监听
+  },
+});
+```
+
+## 注册插件
+
+`use()` 必须在 `start()` 之前调用。
+
+```ts
+import { BkOpenTelemetry } from '@blueking/open-telemetry';
+import { bizPlugin } from './biz-plugin';
+
+const bkOT = new BkOpenTelemetry({
+  autoStart: false,
+  transport: {
+    endpoint: 'https://rum-collector.example.com',
+  },
+});
+
+bkOT.use(bizPlugin);
+
+await bkOT.start();
+```
+
+## 使用 runtime context
+
+`init(context)` 中可以访问 `tracer`、`meter`、`logger`、`startSpan()`、`emitLog()`、`getRuntimeAttributes()` 等能力。
+
+```ts
+const visibilityPlugin = createPlugin({
+  name: 'visibility-change',
+  init(context) {
+    const onVisibilityChange = () => {
+      context.emitLog({
+        severityText: 'INFO',
+        body: 'document.visibilitychange',
+        attributes: {
+          'document.visibility_state': document.visibilityState,
+        },
+      });
+    };
+
+    document.addEventListener('visibilitychange', onVisibilityChange);
+
+    return undefined;
+  },
+});
+```
+
+## 清理事件监听
+
+插件应在 `shutdown()` 中释放自己注册的监听器。
+
+```ts
+const resizePlugin = createPlugin({
+  name: 'window-resize',
+  init(context) {
+    const onResize = () => {
+      const span = context.startSpan('custom.window_resize', {
+        'window.inner_width': window.innerWidth,
+        'window.inner_height': window.innerHeight,
+      });
+      span.end();
+    };
+
+    window.addEventListener('resize', onResize);
+
+    this.shutdown = () => {
+      window.removeEventListener('resize', onResize);
+    };
+  },
+});
+```
+
+更推荐使用闭包保存清理函数，避免依赖 `this`。
+
+```ts
+const createResizePlugin = () => {
+  let teardown = () => {};
+
+  return createPlugin({
+    name: 'window-resize',
+    init(context) {
+      const onResize = () => {
+        const span = context.startSpan('custom.window_resize');
+        span.end();
+      };
+
+      window.addEventListener('resize', onResize);
+      teardown = () => window.removeEventListener('resize', onResize);
+    },
+    shutdown() {
+      teardown();
+    },
+  });
+};
+```
+
+## 注册额外 instrumentation
+
+第三方 OpenTelemetry instrumentation 属于 instrumentation 而非 bk-ot 插件，因此挂在顶层 `instrumentations.custom` 下，或通过 `useInstrumentation()` 链式注册。两者区别详见 [Plugin 与 Instrumentation 的区别](./concepts.md)。
+
+配置式：
+
+```ts
+const bkOT = new BkOpenTelemetry({
+  instrumentations: {
+    custom: [new SomeWebInstrumentation()],
+  },
+  transport: {
+    endpoint: 'https://rum-collector.example.com',
+  },
+});
+```
+
+链式（适合运行时动态追加，必须在 `start()` 之前）：
+
+```ts
+const bkOT = new BkOpenTelemetry({
+  autoStart: false,
+  transport: {
+    endpoint: 'https://rum-collector.example.com',
+  },
+});
+
+bkOT.useInstrumentation(new SomeWebInstrumentation());
+
+await bkOT.start();
+```
+
+> 与受采样影响的 RUM 插件不同，instrumentation 只要 SDK 启用（`enabled !== false`）就会注册，不受 `sampling.rate` 影响。

package/skills/bk-rum-otele/references/data-model.md

@@ -0,0 +1,122 @@
+<!-- 本文件由 packages/open-telemetry/scripts/gen-skill-references.mjs 从 wikis 自动生成，请勿手改。 -->
+
+# 数据模型
+
+SDK 的数据模型遵循“浏览器 SDK 负责低成本原始数据和单事件归一，跨事件聚合交给后端”的边界。
+
+## 分层模型
+
+1. OpenTelemetry 原生字段：trace、span、resource、metric、log 的标准字段。
+2. RUM 归一字段：`span_type`、`span_subtype`、`result`、`error_type`、`duration_bucket`、`target_label` 等。
+3. 运行时上下文：`user.id`、`session.id`、`view.id`、`view.url`、`view.url_path_group` 等。
+4. 后端派生字段：session/view duration、count、地理信息、影响用户数、trace tree 分析等。
+
+## Span 类型
+
+| 类型 | 说明 | 常见来源 |
+| --- | --- | --- |
+| `document` | 文档加载 | documentLoad instrumentation、pageView 插件（初始加载） |
+| `http` | 接口请求 | fetch/xhr instrumentation、httpBody 插件 |
+| `resource` | 静态资源 | resource 插件、documentLoad instrumentation |
+| `vital` | Web Vitals | webVitals 插件 |
+| `error` | 错误 | error 插件、blankScreen 插件、cspViolation 插件、自定义事件错误 |
+| `longtask` | 长任务 | longTask 插件 |
+| `action` | 用户动作 | action 插件、reportAction |
+| `route` | 路由切换 | pageView 插件（SPA 路由）、routeTiming 插件 |
+| `custom` | 自定义事件 | reportCustomEvent、自定义插件、websocket 插件 |
+
+> 每种 span 的具体 span 名（如 `browser.web_vital`、`browser.route_change`）、metric 名、log 事件名和完整属性字典见[遥测参考](./telemetry-reference.md)。
+
+示例：自定义业务事件归一为 `custom`。
+
+```ts
+import { RUM_SPAN_TYPE, buildRumSpanAttributes } from '@blueking/open-telemetry';
+
+const span = bkOT.startSpan('custom.search', {
+  ...buildRumSpanAttributes({
+    spanType: RUM_SPAN_TYPE.custom,
+    spanSubtype: 'search',
+    eventLabel: '业务搜索',
+    targetLabel: 'alarm',
+  }),
+  'biz.keyword_length': 6,
+});
+
+span.end();
+```
+
+## Result 与 Error Type
+
+`result` 描述事件结果，取值包括：
+
+- `success`
+- `warning`
+- `error`
+- `timeout`
+- `abort`
+
+HTTP span 会根据状态码推导结果：`408`、`504` 为 timeout，`>= 400` 为 error，其余为 success。
+
+```ts
+bkOT.reportCustomEvent({
+  name: 'upload_timeout',
+  error: new Error('request timeout'),
+  attributes: {
+    'biz.file_size': 1024 * 1024,
+  },
+});
+```
+
+## Duration Bucket
+
+有耗时的事件会写入 `duration_bucket`：
+
+- `<100ms`
+- `100~500ms`
+- `500ms~2s`
+- `>2s`
+
+```ts
+import { getDurationBucket } from '@blueking/open-telemetry';
+
+console.log(getDurationBucket(80)); // <100ms
+console.log(getDurationBucket(1200)); // 500ms~2s
+```
+
+## SDK 直接采集
+
+以下字段由浏览器 API、接入方配置或 SDK 运行期上下文直接提供：
+
+- 应用与环境：`service.name`、`deployment.environment.name`、`service.version`
+- 用户与会话：`user.id`、`session.id`
+- View：`view.id`、`view.url`、`view.url_path_group`、`view.loading_type`
+- 终端信息：`device_type`、`browser_name`、`browser_version`、`os_name`、`network.effective_type`
+- HTTP / Resource：`http.request.method`、`http.response.status_code`、`url.full`、`transfer_size`
+- Web Vitals：`vital.metric`、`vital.value`、`vital.rating`
+- Error：`exception.type`、`exception.message`、`exception.stacktrace`、`exception.fingerprint`
+
+## 后端派生
+
+以下字段不在浏览器 SDK 中直接生成：
+
+- Session 聚合：`session.duration`、`view_count`、`trace_count`、`error_count`、`action_count`
+- View 聚合：`view.duration`、`request_count`、`resource_count`、`longtask_count`
+- Trace 树：`relative_start`、`hierarchy_level`、`parent_span_name`、`is_critical_path`
+- 影响面：`affected_user_count`
+- 地理信息：`geo.country`、`geo.city`
+
+## 高基数字段策略
+
+高基数字段可以进入 span/log，但不应进入 metric 维度。比如订单 ID、用户输入、完整 URL query 都应谨慎使用。
+
+```ts
+bkOT.reportCustomEvent({
+  name: 'order_submit',
+  attributes: {
+    'biz.order_id': '202605270001',
+    'biz.order_type': 'normal',
+  },
+});
+```
+
+上例中 `biz.order_id` 适合放在 span/log 中定位单次问题，不适合作为 metric 维度做长期聚合。