@blueking/open-telemetry 0.0.15 → 0.0.17

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

@@ -0,0 +1,141 @@
+<!-- 本文件由 packages/open-telemetry/scripts/gen-skill-references.mjs 从 wikis 自动生成，请勿手改。 -->
+
+# 架构与数据流
+
+本页描述当前 `src/` 的实现边界，适合 SDK 维护者、扩展插件作者和需要解释“为什么数据没有被导出”的接入方。
+
+## 源码模块
+
+| 目录/文件 | 职责 | 稳定入口 |
+| --- | --- | --- |
+| `src/index.ts` | ESM 公共导出边界 | npm import 只能依赖这里导出的符号 |
+| `src/browser.ts` | CDN/IIFE 入口 | 暴露 `window.BkOpenTelemetry` |
+| `src/core/config.ts` | 输入类型、校验、默认值、Endpoint 与 Hook 解析 | `BkOTOptions`、`resolveConfig()` |
+| `src/core/sdk.ts` | Provider、Exporter、生命周期、内置插件组合、公开实例 API | `BkOpenTelemetry` |
+| `src/core/runtime-context.ts` | User/Session/View/Action 属性快照与历史归属 | `RumRuntimeContext` |
+| `src/core/processor.ts` | Span/Metric/Log 的采样、上下文、自上报和 beforeSend 过滤 | 三个 Filtering 类 |
+| `src/core/plugin.ts` | 插件契约、启动、并行 flush、反向 shutdown、错误隔离 | `createPlugin()` |
+| `src/plugins/` | 浏览器采集与 RUM 语义 | 各 `create*Plugin()` |
+| `src/schema/` | 归一字段、Span 类型、结果和耗时分桶 | `RUM_ATTRIBUTES`、`buildRumSpanAttributes()` |
+
+文档描述与源码冲突时，以 `src/index.ts` 的公开导出和对应实现为准。`dist/` 是构建产物，不作为文档事实源。
+
+## 构造、启动与关闭
+
+### 构造阶段
+
+`new BkOpenTelemetry(options)` 同步完成：
+
+1. `resolveConfig()` 校验 `application.name`、Transport 和已启用信号的 Endpoint。
+2. 创建 Resource、TracerProvider、MeterProvider、LoggerProvider。
+3. 根据三类信号开关决定是否创建 exporter、processor 或 metric reader。
+4. 创建运行时上下文；初始状态尚无 Session/View，也未命中采样。
+5. `autoStart !== false` 时异步调用 `start()`。
+
+因此，需要在启动前注册扩展或立即创建手动 View 时，应显式设置 `autoStart: false`。
+
+### 启动阶段
+
+`start()` 幂等。获得 Consent 且 `enabled=true` 时，插件按以下顺序初始化：
+
+1. 上下文：Session → Device → Activity → View → Resource Observer。
+2. 请求：统一 Fetch/XHR patch。
+3. RUM：Error → Web Vitals → Blank Screen → Action → 按需 WebSocket / Long Task / CSP。
+4. 接入方 `extensions.plugins`。
+5. 接入方 OpenTelemetry instrumentations。
+
+单个插件 `init()` 抛错不会阻断其他插件；仅在 `debug: true` 时输出 warning。Consent 撤销后再授权会重新执行插件 `init()`，插件必须在 `shutdown()` 中完整释放监听和 patch。
+
+### flush 与 shutdown
+
+- `flush()`：并行刷新插件，再 force flush Trace、Metric、Log provider。
+- `shutdown()`：反向关闭插件，结束/刷新最终数据，移除页面生命周期监听，关闭三个 provider。
+- `shutdown()` 后同一实例不能重新启动；需要重新创建实例。
+- SDK 在 `pagehide` 和页面变为 hidden 时主动调用 `flush()`。
+
+## 从浏览器事件到 OTLP
+
+一次事件的公共路径是：
+
+1. 插件或公开 API 观察浏览器事件。
+2. 从 `RumRuntimeContext` 读取事件发生时对应的 User、Session、View、Action 属性。
+3. 构造原生 OpenTelemetry Span、Metric datapoint 或 LogRecord。
+4. 应用 URL/属性脱敏和事件级 Hook。
+5. Filtering processor/exporter 校验采样与上下文。
+6. 通过对应 OTLP HTTP exporter 上报。
+
+不同信号的最终过滤规则不同：
+
+| 信号 | 接受条件 | 最终 Hook |
+| --- | --- | --- |
+| Span | 已采样，且同时有有效 `session.id`、`view.id`；排除 SDK 上报请求和请求级丢弃标记 | `tracking.beforeSend` |
+| Log | 同 Span；`session.start/rotate` 允许只有有效 Session | `tracking.beforeSend` |
+| Metric | datapoint 带内部已采样标记；导出前移除该标记 | 无全局 beforeSend |
+
+这意味着手动模式首次 `startView()` 之前，普通 Span/Log 不会导出；只创建原生 meter 数据但没有使用 SDK 采样属性的自定义 Metric 也不会导出。
+
+## 运行时上下文与历史归属
+
+运行时上下文维护当前属性，也保留有限的变更时间线。PerformanceObserver 经常在事件结束后才回调，因此 `startSpan(..., { startTime, contextTime })` 可以按事件真实发生时间解析其所属 Session/View/Action，避免把旧页面资源归到新 View。
+
+### Span 与 Log
+
+Span/Log 可携带唯一关联字段：
+
+- `user.id`
+- `session.id`
+- `view.id`、`view.name`、`view.url`、`view.url_path_group`
+- 活动期间的 `action.id`
+
+### Metric
+
+Metric 只保留 `view.url_path_group` 等低基数属性，不携带 `session.id`、`view.id`、`action.id`。需要从聚合指标下钻到具体访问时，查询同名语义 Span 或 View Snapshot Log，或由后端使用 exemplar/派生数据建立关联。
+
+## Session、采样与 Consent
+
+三者是不同控制层：
+
+| 控制层 | 决定什么 | 运行期变化 |
+| --- | --- | --- |
+| `enabled` | 实例是否启动采集 | 构造后不提供 Setter |
+| Consent | 是否安装采集副作用、创建 Session/View | `setTrackingConsent()` 可授权/撤销 |
+| `session.sampleRate` | 有效 Session 的数据是否进入导出链路 | Session 轮换后用新 ID 重新计算 |
+| Signal 开关 | 是否存在对应 exporter/processor/reader | 构造时固定 |
+
+Session 采样由 `application.name + session.id` 稳定 hash 决定，同一 Session 的三类信号保持一致。插件仍可维护页面生命周期，但未采样数据会在创建或导出路径被丢弃。
+
+## 请求采集设计
+
+Fetch/XHR 由 `createCommonInstrumentationsPlugin()` 的单一生命周期直接 patch，不叠加官方 Fetch/XHR instrumentation：
+
+- `excludedUrls` 在最前面完全排除请求。
+- 开始请求时创建 `browser.resource` CLIENT Span，并登记 View/Action 活动。
+- 只有 `allowedTracingUrls` 命中且 Trace 开启时才调用全局 propagator 注入。SDK 成功注册默认 W3C propagator 时注入 `traceparent`/已有 `tracestate`；宿主已有全局 propagator 时，实际 Header 由宿主决定。
+- Resource Observer 把同一 URL/时间窗的 PerformanceResourceTiming 匹配回请求 Span。
+- `request.beforeSend` 可修改请求事件属性或标记丢弃该 Span。
+- 配置 Body 且 Log 开启时，异步生成关联 `trace.id` / `span.id` 的 `browser.request.body` Log。
+- SDK 自身所有已启用 OTLP Endpoint 始终排除，防止递归上报。
+
+静态资源复用同一个 Resource Observer，但 Fetch/XHR entry 只用于 timing 匹配，不再创建第二条资源 Span。
+
+## 脱敏与 Hook 顺序
+
+| 入口 | 作用范围 | 适合用途 |
+| --- | --- | --- |
+| `privacy.redactUrl` | SDK 写入的 URL 类属性 | 删除 query/hash、模板化路径 |
+| `privacy.redactAttributes` | 通过 SDK `startSpan()`、`emitLog()` 和内置插件显式应用的属性 | 删除敏感业务字段 |
+| `tracking.request.beforeSend` | 单个 Fetch/XHR，带原始 Request/Response/XHR 上下文 | 请求专属补充或丢弃 |
+| Request Body `redact` | 单个请求/响应 Body，必填 | 内容级脱敏；返回 `undefined` 跳过该 Body |
+| `tracking.beforeSend` | Span/Log 进入底层 processor 前 | 最终兜底修改或丢弃；不作用于 Metric |
+
+第三方 instrumentation 自己生成的属性不经过 SDK 的 `redactAttributes` 构造路径。若要统一约束第三方 Span，应在 `tracking.beforeSend` 中做最终清理。
+
+## 扩展边界
+
+- RUM 语义、Session/View 关联、Log 或活动总线：使用 `createPlugin()`。
+- 已有标准 OpenTelemetry instrumentation：通过 `extensions.instrumentations` 或 `useInstrumentation()` 注册。
+- 自定义 Log 使用 `context.emitLog()`，不要直接 `context.logger.emit()`，否则不会自动合并运行时上下文。
+- 自定义 Span 优先使用 `context.startSpan()`，它会应用运行时属性与脱敏。
+- 当前包没有导出稳定的自定义 Metric 采样属性/helper。直接使用 `context.meter` 创建的数据点默认无法通过 `FilteringMetricExporter`；不要依赖内部 `bk.rum.sampled` 字段，也不要把 `getRuntimeAttributes()` 中的唯一 Session/View/Action ID 整体复制到 labels。需要稳定扩展时优先使用 Span/Log，或先在 SDK 内补充公共 Metric API。
+
+完整契约与示例见[自定义插件](./custom-plugin.md)。

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

@@ -0,0 +1,100 @@
+<!-- 本文件由 packages/open-telemetry/scripts/gen-skill-references.mjs 从 wikis 自动生成，请勿手改。 -->
+
+# 能力矩阵
+
+本页回答四个问题：SDK 能采什么、默认是否启用、依赖哪个浏览器能力、最终上报什么。精确名称与属性请继续查[遥测参考](./telemetry-reference.md)。
+
+## 总览
+
+| 能力 | 配置入口 | 默认 | 浏览器入口 | Trace | Metric | Log |
+| --- | --- | --- | --- | --- | --- | --- |
+| Session | `session` | 必选基础能力 | `localStorage`、用户活动、页面可见性 | — | — | `session.start` / `session.rotate` |
+| View | `tracking.view` | 自动模式 | Navigation Timing、History、hash、BFCache、DOM Mutation | `browser.view` | `browser.view.loading_time` | `browser.view` Snapshot |
+| Fetch/XHR | `tracking.request` | 开 | `fetch`、`XMLHttpRequest`、Resource Timing | `browser.resource` | — | 可选 `browser.request.body` |
+| 静态资源 | `tracking.resource` | 开 | Resource PerformanceObserver | `browser.resource` | — | — |
+| JS / Promise / 资源错误 | `tracking.error` | 开 | `error`、`unhandledrejection` | 三类 `browser.*error` | — | — |
+| Web Vitals | `tracking.webVitals` | 开 | `web-vitals`、Layout Shift、Event Timing | `browser.web_vital` | 两个 Histogram | — |
+| Action | `tracking.action` | 开 | click、DOM、请求与活动总线 | `action.click` | — | — |
+| 手动 Action | `reportAction()` | 可调用 | 业务调用 | `action.custom` | — | — |
+| 自定义事件 | `reportCustomEvent()` | 可调用 | 业务调用 | `custom.<name>` | — | — |
+| 白屏 | `tracking.blankScreen` | 开 | DOM 命中测试、View 活动 | `browser.blank_screen` | `browser.blank_screen.count` | — |
+| 设备 | `tracking.device` | 开 | UA、UA-CH、Screen、Network Information | 作为公共属性 | — | 作为公共属性 |
+| Long Task | `tracking.longTask` | 关 | Long Animation Frames / Long Tasks | `browser.long_task` | 三个聚合指标 | — |
+| WebSocket | `tracking.websocket` | 关 | `WebSocket` Proxy | `websocket.connect` | 四个聚合指标 | error / close |
+| CSP | `tracking.cspViolation` | 关 | `securitypolicyviolation` | `csp.violation` | — | — |
+| 自定义插件 | `extensions.plugins` / `use()` | 无 | 由插件决定 | 支持 | 无稳定公共辅助 API | 推荐 `emitLog()` |
+| OTel instrumentation | `extensions.instrumentations` / `useInstrumentation()` | 无 | 由 instrumentation 决定 | 支持 | 无稳定支持 | 取决于实现 |
+
+“默认开”表示获得 Consent 且 SDK 已启动后启用。是否真正导出还受 `enabled`、Session 采样、Session/View 有效性和单信号开关控制。
+
+## 能力边界
+
+### SDK 直接负责
+
+- 创建和轮换 Session，划分初始加载、SPA、BFCache、手动和 Session 续期 View。
+- 统一 patch Fetch/XHR；请求 span、活动计数、Trace Header、Resource Timing 和 Body 采集共用同一生命周期。
+- 把浏览器事件归一为 `span_type`、`result`、`error_type`、`duration_bucket`、`target_*` 等字段。
+- 自动为 Span/Log 关联 `session.id`、`view.id`，为 Metric 保留低基数 `view.url_path_group`。
+- 在 exporter 前执行采样、有效上下文、自上报请求和 `tracking.beforeSend` 过滤。
+
+### SDK 不负责
+
+- 不聚合 `session.duration`、影响用户数、地理信息、Trace 关键路径等后端指标。
+- 不自动判断业务字段是否敏感，也不 hash `user.id`。
+- 不默认采集 HTTP 请求/响应 Body。
+- 不把唯一的 `session.id`、`view.id`、`action.id` 放入 Metric labels。
+- 不保证浏览器未暴露的数据，例如缺少 `Timing-Allow-Origin` 的跨域资源网络阶段。
+
+## 默认开启与关闭
+
+```ts
+new BkOpenTelemetry({
+  application: { name: 'capability-demo' },
+  transport: { endpoint: 'https://collector.example.com' },
+  tracking: {
+    request: true,
+    resource: true,
+    error: true,
+    webVitals: true,
+    action: true,
+    blankScreen: true,
+    device: true,
+    longTask: false,
+    websocket: false,
+    cspViolation: false,
+  },
+});
+```
+
+Session 与 View 是导出有效性边界，不提供关闭开关。`tracking.view` 只配置自动/手动模式、稳定耗时和路由分组。
+
+## 浏览器降级行为
+
+| 条件 | 行为 |
+| --- | --- |
+| 无 `PerformanceObserver` 或不支持 `resource` | 跳过静态资源观察和请求网络阶段匹配；Fetch/XHR 本身仍可采集 |
+| 不支持 Long Animation Frames | Long Task 插件尝试回退 Long Tasks API |
+| 两种 Long Task API 都不支持 | 跳过 Long Task，不抛出业务异常 |
+| 跨域资源无 `Timing-Allow-Origin` | 只保留浏览器可见的总耗时/体积，不伪造网络阶段 |
+| 无 Network Information / UA-CH | 只写入可获得的设备字段 |
+| 无 `localStorage` 或访问失败 | Session/Device 持久化退回内存 |
+| 插件初始化抛错 | 隔离该插件；`debug: true` 时输出 warning，其余插件继续启动 |
+
+## 成本与隐私提示
+
+| 能力 | 主要成本/风险 | 建议 |
+| --- | --- | --- |
+| `session.sampleRate` | 决定三类信号总体数据量 | 按应用容量设置；排障临时设为 `1` |
+| Metric 自定义维度 | 高基数会放大时序数量 | 只放应用、租户类别、路由模板等低基数字段 |
+| Request Body | 可能包含凭证、个人数据，且增加网络体积 | 默认关闭；开启时限制类型/大小并强制脱敏 |
+| Action 文本命名 | DOM 文本可能包含用户输入 | 保持 `nameCollection: 'explicit'`，关键元素使用 `data-bk-action-name` |
+| Device 持久 ID | 支持跨 Session 关联 | 默认不持久化；需取得合规依据后再开启 |
+| Long Task | 产生 Span 与脚本归因信息 | 仅性能分析场景开启，结合采样控制 |
+| WebSocket | Proxy 全局构造器并统计消息字节 | 同页面单实例；不采集消息内容 |
+
+## 下一步
+
+- 配置每项能力：[配置参考](./configuration.md)
+- 理解启动与上报链路：[架构与数据流](./architecture.md)
+- 查看单个插件实现行为：[插件总览](./plugins.md)
+- 查看精确遥测名称和属性：[遥测参考](./telemetry-reference.md)

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

@@ -10,7 +10,7 @@
 
 - Trace：用于描述一次有起止时间的行为，例如页面访问、接口请求、资源加载、用户点击、长任务。
 - Metric：用于描述可聚合的数值，例如 Web Vitals、长任务数量、WebSocket 消息大小、空白屏结果。
-- Log：用于描述离散事件或诊断信息，例如 CSP 违规、Session 生命周期和 WebSocket 状态。
+- Log：用于描述离散事件或诊断信息，例如 Session 生命周期、View Snapshot、请求 Body 和 WebSocket 状态。
 
 示例：手动创建一个业务 span。
 
@@ -49,6 +49,7 @@ bkOT.setUser({
 示例：手动模式由业务路由系统创建 View。
 
 ```ts
+// 前提：autoStart: false，且已经 await bkOT.start() 建立 Session。
 bkOT.startView({
   name: '商品详情',
   url: window.location.href,
@@ -60,10 +61,10 @@ bkOT.startView({
 
 SDK 将能力分为两类：
 
-1. 内置采集：`tracking.request` 使用统一的 Fetch/XHR 生命周期实现，负责 patch 浏览器 API、创建 CLIENT Span、Trace Header 和请求 Performance Timing 匹配。
+1. 内置采集：`tracking.request` 使用 SDK 自有的统一 Fetch/XHR 生命周期，负责 patch 浏览器 API、创建 `browser.resource` CLIENT Span、Trace Header 和请求 Performance Timing 匹配。
 2. RUM 插件：View、Session、`resource`、`error`、`webVitals`、`blankScreen`、`device` 等，负责主动产生 RUM 归一数据。
 
-用户交互统一由 SDK 的 `action` 插件采集，避免与官方 user-interaction instrumentation 重复上报。
+用户交互统一由 SDK 的 `action` 插件采集。接入额外 instrumentation 时，应避免再注册覆盖 Fetch/XHR 或用户交互的探针，以免重复上报。
 
 ```ts
 new BkOpenTelemetry({
@@ -80,7 +81,7 @@ new BkOpenTelemetry({
 
 ## 采样
 
-`session.sampleRate` 是会话级确定性采样。决定由 `application.name + session.id` 的稳定 hash 得出，同一 Session 的三类信号保持一致。插件会维护必要的页面生命周期，但未命中时 sampler/processor 不导出其数据，`reportAction()` 和 `reportCustomEvent()` 直接丢弃。
+`session.sampleRate` 是会话级确定性采样。决定由 `application.name + session.id` 的稳定 hash 得出，同一 Session 的三类信号保持一致。插件仍会维护必要的浏览器生命周期，但未命中时创建或导出路径会丢弃数据，`reportAction()` 和 `reportCustomEvent()` 直接返回。
 
 示例：生产环境按 10% 会话采样。
 
@@ -150,4 +151,6 @@ new BkOpenTelemetry({
 
 内置 Fetch/XHR 不再基于官方 instrumentation 叠加适配，而是由单一请求生命周期实现，避免重复 patch、重复活动计数及私有 `_addHeaders/_patchSend` 依赖。
 
+当前扩展 instrumentation 的稳定能力边界是 Trace：Filtering Span Processor 会在 Span 创建时补充有效 RUM 上下文。Metric exporter 要求 SDK 内部采样标记，而包未公开对应 helper，因此第三方 instrumentation 产生的 Metric 默认会被过滤，不应作为已支持的扩展能力。
+
 扩展必须在 `start()` 前注册；动态 Consent 重新授权时，插件可能再次执行 `init()`，所以插件的 `shutdown()` 应完整释放副作用。