@blueking/open-telemetry 0.0.15 → 0.0.16

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

@@ -2,50 +2,26 @@
 
 # API 参考
 
-本页按使用频率列出公开 API。完整类型以 `src/index.ts` 导出为准。
+本页只描述 `src/index.ts` 公开导出的 API。深层路径文件属于实现细节，接入方不应直接 import。
 
-## BkOpenTelemetry
+## 创建实例
 
 ```ts
-import { BkOpenTelemetry } from '@blueking/open-telemetry';
+import { BkOpenTelemetry, type BkOTOptions } from '@blueking/open-telemetry';
 
-const bkOT = new BkOpenTelemetry({
+const options: BkOTOptions = {
   application: { name: 'bk-rum-demo' },
   transport: { endpoint: 'https://rum-collector.example.com' },
-});
+};
+
+const bkOT = new BkOpenTelemetry(options);
 ```
 
-### 实例成员总览
-
-`BkOpenTelemetry` 实例（`BkOTInstance`）提供以下成员，常用方法在下文展开：
-
-| 成员 | 类型 | 说明 |
-| --- | --- | --- |
-| `start()` | `() => Promise<void>` | 启动 SDK，注册 provider、instrumentation 和插件。 |
-| `shutdown()` | `() => Promise<void>` | 刷新数据、关闭 provider、清理插件；关闭后不可重启。 |
-| `flush()` | `() => Promise<void>` | 立即刷新插件、trace、metric、log。 |
-| `use(plugin)` | `(plugin) => this` | 注册自定义插件，须在 `start()` 前。 |
-| `useInstrumentation(instr)` | `(instr) => this` | 注册额外 OpenTelemetry instrumentation，须在 `start()` 前。 |
-| `setUser(user)` | `(user) => void` | 更新用户上下文（`user.id`）。 |
-| `setTrackingConsent(consent)` | `(consent) => Promise<void>` | 授予或撤销采集授权，并启动或停止采集。 |
-| `startView(options?)` | `(options?) => void` | 结束当前 View 并创建新 View。可在 SDK 启动前调用。 |
-| `setViewName(name)` | `(name) => void` | 更新当前 View 名称，不创建新 View。 |
-| `setViewLoadingTime()` | `() => void` | 使用当前时刻覆盖当前 View 的自动页面稳定耗时。 |
-| `reportAction(payload)` | `(payload) => void` | 手动上报用户动作（受采样控制）。 |
-| `reportCustomEvent(payload)` | `(payload) => void` | 手动上报自定义事件（受采样控制）。 |
-| `startSpan(name, attributes?, options?)` | `(...) => Span` | 创建并返回一个 span，自动带上运行时属性与脱敏。 |
-| `emitLog(record)` | `(record) => void` | 发送一条 log，自动合并运行时属性与脱敏。 |
-| `getRuntimeAttributes()` | `() => Attributes` | 读取当前运行时公共属性快照。 |
-| `setRuntimeAttributes(attributes)` | `(attributes) => void` | 写入运行时公共属性。 |
-| `applyRedact(attributes)` | `(attributes) => Attributes` | 对属性执行一次 `privacy.redactAttributes`。 |
-| `config` | `ResolvedBkOTConfig` | 解析后的只读配置。 |
-| `tracer` / `meter` / `logger` | OpenTelemetry 原生对象 | 用于直接操作三类信号 provider。 |
-
-> `startSpan` / `emitLog` / `getRuntimeAttributes` 等既是实例方法，也是自定义插件 `init(context)` 中 `context` 的能力，见[自定义插件](./custom-plugin.md)。
-
-### start
-
-启动 SDK，注册 provider、instrumentation 和插件。
+构造函数同步解析配置并创建三个 OpenTelemetry Provider；`autoStart: true` 时随后异步启动采集。完整配置见[配置参考](./configuration.md)。
+
+## 生命周期方法
+
+### start()
 
 ```ts
 const bkOT = new BkOpenTelemetry({
@@ -54,178 +30,250 @@ const bkOT = new BkOpenTelemetry({
   transport: { endpoint: 'https://rum-collector.example.com' },
 });
 
+bkOT.use(myPlugin);
 await bkOT.start();
 ```
 
-### shutdown
+启动 Session、View、内置插件、接入方插件和 instrumentations，并安装页面隐藏时的 flush 监听。重复调用 `start()` 不会重复启动。
 
-刷新数据、关闭 provider，并执行插件清理。关闭后不应再重启同一个实例。
+### flush()
 
 ```ts
-await bkOT.shutdown();
+await bkOT.flush();
 ```
 
-### flush
+先并行调用已启动插件的 `flush()`，再 force flush Trace、Metric、Log Provider。SDK 已在 `pagehide` 和页面变为 hidden 时触发 flush；业务只需在关键流程完成后按需主动调用。
 
-立即刷新插件、trace、metric、log。
+### shutdown()
 
 ```ts
-window.addEventListener('beforeunload', () => {
-  void bkOT.flush();
-});
+await bkOT.shutdown();
 ```
 
-### use
-
-注册自定义插件，必须在 `start()` 前调用。
-
-```ts
-bkOT.use(
-  createPlugin({
-    name: 'biz-plugin',
-    init(context) {
-      const span = context.startSpan('custom.biz_plugin_ready');
-      span.end();
-    },
-  }),
-);
-```
+反向关闭插件、结束待处理事件、刷新 Provider 并清理浏览器 patch/监听。该方法幂等；关闭后不能重新启动同一实例，再调用 `start()` 会抛错。
 
-### useInstrumentation
+## Consent
 
-注册额外 OpenTelemetry instrumentation，必须在 `start()` 前调用。
+### setTrackingConsent(consent)
 
 ```ts
-bkOT.useInstrumentation(new SomeWebInstrumentation());
-```
+const bkOT = new BkOpenTelemetry({
+  application: { name: 'consent-demo' },
+  privacy: { trackingConsent: 'not-granted' },
+  transport: { endpoint: 'https://rum-collector.example.com' },
+});
 
-### setUser
+await bkOT.setTrackingConsent('granted');
+await bkOT.setTrackingConsent('not-granted');
+```
 
-更新用户上下文。
+- 未授权：不创建 Session/View，不启动插件，不 patch 浏览器 API。
+- 授权：启动采集并建立新的 Session/View。
+- 撤销：关闭采集副作用并 flush 已允许的数据。
+- 再授权：插件会再次执行 `init()`。
 
-```ts
-bkOT.setUser({
-  id: 'user-12345',
-});
-```
+该方法在 `autoStart: false` 且尚未 `start()` 时只更新状态；随后 `start()` 使用最新 Consent。
 
-### setTrackingConsent
+## User 与 View
 
-运行期更新采集授权。撤销授权会停止插件与浏览器 API patch，并刷新已允许采集的数据；再次授权会重新建立 Session/View 和采集能力。
+### setUser(user)
 
 ```ts
-await bkOT.setTrackingConsent('granted');
-await bkOT.setTrackingConsent('not-granted');
+bkOT.setUser({ id: 'user-12345' });
+bkOT.setUser({ id: undefined });
 ```
 
-### startView
+更新后续事件的 `user.id`。SDK 不 hash、不脱敏、不改写该值。
 
-创建新的 View，并结束前一个 View。`view.id` 由 SDK 生成，业务侧不能覆盖。
+### startView(options?)
+
+结束当前 View 并创建新 View，`view.id` 始终由 SDK 生成。
 
 ```ts
+const bkOT = new BkOpenTelemetry({
+  application: { name: 'manual-view-demo' },
+  autoStart: false,
+  tracking: { view: { tracking: 'manual' } },
+  transport: { endpoint: 'https://rum-collector.example.com' },
+});
+
+await bkOT.start();
 bkOT.startView({
-  name: '首页',
-  url: window.location.href,
-  attributes: {
-    'biz.owner': 'portal-team',
-  },
+  name: '订单详情',
+  url: location.href,
+  attributes: { 'biz.owner': 'order-team' },
 });
 ```
 
-### setViewName
+`BkOTStartViewOptions` 包含 `name?`、`url?`、`attributes?`。调用时必须已有采样有效的 Session；例如 `autoStart: false` 且尚未 `await start()`、未授权或未采样时，调用会被忽略。自动启动过程中、Page View 插件尚未初始化时发出的有效命令会由运行时队列交给插件消费，但接入代码仍推荐显式等待 `start()`。`attributes` 不能覆盖 SDK 的 Session/View 保留字段。
 
-只修改当前 View 的 `view.name`，后续子事件使用新名称。
+### setViewName(name)
 
 ```ts
-bkOT.setViewName('首页-新版');
+bkOT.setViewName('订单详情-只读');
 ```
 
-### setViewLoadingTime
+更新当前 View 名称，不创建新 View。后续子事件使用新名称，View Snapshot 产生 update。
 
-当自动页面活动无法表达业务真正的渲染完成点时，手动覆盖当前 View 的 `view.loading_time`。每次调用都会替换前一次结果。
+### setViewLoadingTime()
 
 ```ts
 await renderAsyncPage();
 bkOT.setViewLoadingTime();
 ```
 
-### reportAction
+用“当前时刻 - View 开始时刻”覆盖自动 `view.loading_time`。每次调用替换前一次值；没有有效 View 时忽略。
 
-手动上报用户动作。
+## 手动事件
+
+### reportAction(payload)
 
 ```ts
 bkOT.reportAction({
   name: '保存',
-  attributes: {
-    'biz.form': 'alarm-strategy',
-  },
+  attributes: { 'biz.form': 'alarm-strategy' },
 });
 ```
 
-### reportCustomEvent
+创建并立即结束 `action.custom` Span，写入新的 `action.id`、`action.name` 和 `action.type=custom`。它不会触发自动点击的活动耗时、关联计数或挫败信号计算。
 
-手动上报自定义事件。
+### reportCustomEvent(payload)
 
 ```ts
 bkOT.reportCustomEvent({
   name: 'strategy_saved',
-  attributes: {
-    'biz.strategy_id': '10001',
-  },
+  attributes: { 'biz.strategy_id': '10001' },
 });
-```
-
-带错误的自定义事件：
 
-```ts
 bkOT.reportCustomEvent({
   name: 'strategy_save_failed',
   error: new Error('validation failed'),
-  attributes: {
-    'biz.strategy_id': '10001',
-  },
 });
 ```
 
-## createPlugin
+创建 `custom.<name>` Span，并合并 `context.attributes.page`、`context.attributes.custom` 与 payload attributes。传入 `error` 时记录 exception、设置 Span Status/`result=error`，但 `span_type` 仍为 `custom`。
+
+两类方法均受 Session 采样控制；未采样时直接返回。`debug: true` 仅对被丢弃的 Custom Event 输出 warning。
+
+## 自定义信号
+
+### startSpan(name, attributes?, options?)
+
+```ts
+const startedAt = Date.now();
+const span = bkOT.startSpan(
+  'custom.cache_warmup',
+  { 'biz.cache': 'homepage' },
+  { startTime: startedAt, contextTime: startedAt },
+);
+
+span.end();
+```
+
+自动合并事件发生时的运行时上下文，并应用 `privacy.redactAttributes`。第三个参数的内部形状名为 `BkOTStartSpanOptions`，但该类型没有从包根导出，接入方直接按下表传对象即可，不要生成对它的 import：
+
+| 字段 | 说明 |
+| --- | --- |
+| `startTime` | OpenTelemetry `TimeInput`；常用 epoch ms |
+| `contextTime` | 用该 epoch ms 从历史快照解析 Session/View/Action；数字型 `startTime` 默认同时作为该值 |
+| `kind` | OpenTelemetry `SpanKind`，默认 `INTERNAL` |
+
+只有已采样且同时带有效 `session.id`、`view.id` 的 Span 会导出。
+
+### emitLog(record)
+
+```ts
+bkOT.emitLog({
+  severityText: 'INFO',
+  body: 'biz.cache_ready',
+  attributes: { 'biz.cache': 'homepage' },
+});
+```
+
+自动合并运行时上下文与脱敏。自定义插件应使用 `emitLog()`，不要直接调用 `logger.emit()`。
+
+### tracer / meter / logger
+
+实例公开 SDK 私有 Provider 对应的原生 OpenTelemetry `Tracer`、`Meter`、`Logger`。优先使用 `startSpan()` 与 `emitLog()`。当前没有公开稳定的自定义 Metric 采样 helper，直接通过 `meter` 创建的数据点默认无法通过过滤器，不应作为接入方稳定能力；详见[架构与数据流](./architecture.md#扩展边界)。
+
+## 扩展注册
+
+### use(plugin)
+
+```ts
+bkOT.use(
+  createPlugin({
+    name: 'biz-plugin',
+    init(context) {
+      context.startSpan('custom.biz_plugin_ready').end();
+    },
+  }),
+);
+```
+
+### useInstrumentation(instrumentation)
+
+```ts
+bkOT.useInstrumentation(new SomeWebInstrumentation());
+```
+
+两者都必须在 `start()` 前调用；使用默认自动启动时没有可靠的动态注册窗口，推荐配置 `autoStart: false`。完整插件契约见[自定义插件](./custom-plugin.md)。
+
+额外 instrumentation 的稳定扩展边界是 Trace。第三方 Metric 不会自动获得 SDK 内部采样标记，默认无法通过 Metric 过滤器。
+
+## 运行时与诊断成员
+
+| 成员 | 返回/作用 |
+| --- | --- |
+| `config` | `resolveConfig()` 解析后的 `ResolvedBkOTConfig` |
+| `applyRedact(attributes)` | 执行 `privacy.redactAttributes` |
+| `getRuntimeAttributes()` | 当前公共属性快照 |
+| `getRuntimeAttributesAt(timestamp)` | 指定 epoch ms 的历史公共属性快照 |
+| `setRuntimeAttributes(attributes, changedAt?)` | 写入公共属性；高级扩展 API，谨慎避免覆盖 SDK 字段 |
+| `isSampled()` | 当前 Session 是否命中采样 |
+| `isSessionActive()` | 是否存在有效 Session |
+| `isViewActive()` | 是否存在有效 View |
+| `onSessionLifecycle(listener)` | 订阅 Session renewed/expired，返回取消函数 |
+| `notifySessionLifecycle(event)` | 向运行时分发生命周期事件；主要供高级插件使用 |
+
+## createPlugin(plugin)
+
+`createPlugin()` 是保留完整类型推导的恒等构造器。
 
 ```ts
 import { createPlugin } from '@blueking/open-telemetry';
 
-export const plugin = createPlugin({
+const plugin = createPlugin({
   name: 'page-visible',
-  init(context) {
-    context.emitLog({
-      severityText: 'INFO',
-      body: 'plugin init',
-      attributes: {
-        'document.visibility_state': document.visibilityState,
-      },
-    });
-  },
+  enabled: config => config.enabled,
+  init(context) {},
+  flush() {},
+  shutdown() {},
 });
 ```
 
-## RUM_ATTRIBUTES
+`BkOTPlugin` 的 `enabled` 可为布尔值或接收 `ResolvedBkOTConfig` 的函数。Plugin Manager 顺序启动、并行 flush、反向 shutdown，并隔离单个插件的初始化错误。
 
-`RUM_ATTRIBUTES` 提供字段 key 常量，避免手写字符串。
+## Schema 辅助 API
 
-```ts
-import { RUM_ATTRIBUTES } from '@blueking/open-telemetry';
+### RUM_ATTRIBUTES
+
+归一字段 key 常量。
 
+```ts
 bkOT.reportCustomEvent({
   name: 'biz_event',
-  attributes: {
-    [RUM_ATTRIBUTES.targetLabel]: 'submit-order',
-  },
+  attributes: { [RUM_ATTRIBUTES.targetLabel]: 'submit-order' },
 });
 ```
 
-## RUM_SPAN_TYPE 与 buildRumSpanAttributes
+### RUM_SPAN_TYPE / RUM_SPAN_RESULT
 
-```ts
-import { RUM_SPAN_TYPE, buildRumSpanAttributes } from '@blueking/open-telemetry';
+分别提供标准 `span_type` 与 `result` 值。
+
+### buildRumSpanAttributes(classification)
 
+```ts
 const span = bkOT.startSpan('custom.cache_hit', {
   ...buildRumSpanAttributes({
     spanType: RUM_SPAN_TYPE.custom,
@@ -235,26 +283,79 @@ const span = bkOT.startSpan('custom.cache_hit', {
     targetValue: true,
   }),
 });
-
 span.end();
 ```
 
-## resolveConfig
+### getDurationBucket(duration)
+
+返回 `<100ms`、`100~500ms`、`500ms~2s`、`>2s` 之一。
+
+### buildRumSpanAttributes 相关类型
 
-`resolveConfig()` 可用于预览 SDK 核心配置解析结果。插件配置不会在这里展开默认值；内置插件会在各自创建时处理开关、默认值和参数兜底。
+公开 `RumSpanClassification`、`RumSpanType`、`RumSpanResult`，用于扩展插件保持同一归一模型。
+
+## resolveConfig(options)
 
 ```ts
 import { resolveConfig } from '@blueking/open-telemetry';
 
 const config = resolveConfig({
-  application: {
-    name: 'bk-rum-demo',
-  },
-  transport: {
-    endpoint: 'https://rum-collector.example.com',
-  },
+  application: { name: 'bk-rum-demo' },
+  transport: { endpoint: 'https://rum-collector.example.com' },
 });
 
-console.log(config.application.name);
-console.log(config.transport.traces.endpoint);
+console.log(config.transport.traces && config.transport.traces.endpoint);
 ```
+
+用于预览核心解析结果和测试配置。插件自己的参数默认值在插件工厂执行时解析，不会全部展开到 `ResolvedBkOTConfig`。
+
+## 内置插件工厂
+
+公共入口导出以下工厂，便于自定义组合或测试：
+
+| 工厂 | 选项类型 |
+| --- | --- |
+| `createSessionPlugin` | `BkOTSessionConfig` |
+| `createDevicePlugin` | `BkOTDevicePluginOptions` |
+| `createCommonInstrumentationsPlugin` | `BkOTRequestConfig \| boolean` |
+| `createResourcePlugin` | 直接传 `boolean`，控制是否为静态资源创建 Span；默认 `true` |
+| `createErrorPlugin` | `BkOTErrorPluginOptions` |
+| `createWebVitalsPlugin` | 无 |
+| `createBlankScreenPlugin` | `BkOTBlankScreenPluginOptions` |
+| `createActionPlugin` | `BkOTActionPluginOptions` |
+| `createLongTaskPlugin` | `BkOTLongTaskPluginOptions` |
+| `createWebSocketPlugin` | 无 |
+| `createCspViolationPlugin` | 无 |
+
+`createCommonInstrumentationsPlugin` 名称保留，但当前实现是 SDK 自有 Fetch/XHR patch，不注册官方 Fetch/XHR instrumentation。
+
+## 其他公共导出
+
+`src/index.ts` 还导出以下高级能力：
+
+- `RumRuntimeContext` 及 Session/View/User 相关类型。
+- `PluginManager`。
+- `FilteringSpanProcessor`、`FilteringMetricExporter`、`FilteringLogRecordProcessor`。
+- `EXCLUDED_ACTIVITY_MUTATIONS_ATTRIBUTE`，用于标记不应延长 View Loading/Action 的 DOM 子树。
+- 配置输入、解析结果、Transport、Hook、请求上下文等 TypeScript 类型。
+
+这些主要服务 SDK 维护和高级扩展；常规接入只需 `BkOpenTelemetry`、`BkOTOptions` 和手动事件类型。
+
+`BkOpenTelemetry` 具体类上还能看到 `registerInstrumentations()`，它用于 SDK 向插件运行时提供批量注册能力，但被刻意排除在 `BkOTInstance` 契约之外，也会绕过 `useInstrumentation()` 的启动阶段检查。接入方不要直接调用；使用 `extensions.instrumentations` 或 `useInstrumentation()`。
+
+## 公共类型索引
+
+以下名称都可以从包根路径执行 `import type`：
+
+| 分类 | 类型 |
+| --- | --- |
+| 顶层配置 | `BkOTOptions`、`BkOTApplicationConfig`、`BkOTTransportConfig`、`BkOTTrackingConfig`、`BkOTTrackingConsent`、`BkOTContextConfig`、`BkOTPrivacyConfig`、`BkOTExtensionsConfig` |
+| Transport | `BkOTBatchConfig`、`SignalExporterConfig`、`SignalExporterInputConfig`、`SignalExportersInputConfig`、`TraceExporterInputConfig`、`MetricExporterInputConfig` |
+| View/Session/User | `BkOTViewConfig`、`BkOTSessionConfig`、`BkOTStartViewOptions`、`BkOTViewContext`、`BkOTSessionLifecycleEvent`、`BkOTUserContext` |
+| Request | `BkOTRequestConfig`、`BkOTRequestEvent`、`BkOTRequestContext`、`BkOTRequestBodyConfig`、`BkOTRequestBodyRedactPayload`、`BkOTUrlMatcher` |
+| 事件与 Hook | `BkOTActionEventPayload`、`BkOTCustomEventPayload`、`BkOTBeforeSendEvent`、`BkOTAttributesConfig`、`BkOTAttributeValue` |
+| 插件 | `BkOTPlugin`、`BkOTRuntimeContext`、`BkOTActionPluginOptions`、`BkOTBlankScreenPluginOptions`、`BkOTDevicePluginOptions`、`BkOTErrorPluginOptions`、`BkOTLongTaskPluginOptions` |
+| 实例与解析结果 | `BkOTInstance`、`PluginManager`、`ResolvedBkOTConfig`、`ResolvedApplicationConfig`、`ResolvedTransportConfig`、`ResolvedViewConfig`、`ResolvedConfigHooks` |
+| Schema | `RumAttributeKey`、`RumSpanClassification`、`RumSpanType`、`RumSpanResult` |
+
+如某个源码类型没有出现在本表，也没有从 `src/index.ts` 导出，则它不是包的公共契约。

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)。