@blueking/open-telemetry 0.0.15 → 0.0.17

package/dist/plugins/blank-screen.d.ts

@@ -1,4 +1,8 @@
 import type { BkOTPlugin } from '../core/plugin';
+/**
+ * 通过视口九宫格采样估算空白比例，并在页面稳定后连续确认两次。每个 View 最多上报一次，
+ * 避免首屏渲染、路由切换和 loading 状态造成瞬时误报。
+ */
 export interface BkOTBlankScreenPluginOptions {
     /** 页面活动稳定后首次检查的延迟，默认 1000ms。 */
     checkDelay?: number;

package/dist/plugins/common.d.ts

@@ -4,6 +4,7 @@ import type { BkOTPlugin, BkOTRuntimeContext } from '../core/plugin';
 import type { Span } from '@opentelemetry/api';
 interface RequestDetails {
     method?: string;
+    startedAt?: number;
     url?: string;
 }
 export { REQUEST_DISCARD_ATTRIBUTE };

package/dist/plugins/csp-violation.d.ts

@@ -6,7 +6,7 @@ import type { BkOTPlugin } from '../core/plugin';
  * 节流策略：
  * - 同 fingerprint（`violatedDirective + blockedURI + sourceFile + lineNumber`）
  *   在 60s 窗口内最多上报 5 条，避免风暴打爆 collector（如某段被拦截的 inline 脚本被反复渲染）。
- * - 每条 attribute 带 `csp.window_count`，反映当前窗口内同 fingerprint 的总触发次数（含被丢弃的）。
+ * - `browser.csp_violation.count` counter 在节流前累计所有违规，span 只保留窗口触发序号。
  *
  * 体积优化：
  * - `csp.original_policy`（完整 CSP 策略，可能数 KB）仅在窗口首条上报，后续同 fingerprint 不再重复携带。

package/dist/plugins/long-task.d.ts

@@ -1,4 +1,8 @@
 import type { BkOTPlugin } from '../core/plugin';
+/**
+ * 主线程阻塞优先使用 Long Animation Frame API 获取脚本归因，不支持时回退到 Long Tasks API；
+ * span 保留单次诊断详情，metric 只保留低基数维度用于聚合分布。
+ */
 export interface BkOTLongTaskPluginOptions {
     /** 采集阈值，默认 50ms。Performance API 本身通常只产生大于 50ms 的条目。 */
     threshold?: number;

package/dist/plugins/request-body.d.ts

@@ -6,9 +6,10 @@ interface CaptureRequestBodyLogOptions {
     domainContext: BkOTRequestContext;
     event: BkOTRequestEvent;
     fetchRequest?: Request | RequestInit;
+    occurredAt?: number;
     runtimeContext: Pick<BkOTRuntimeContext, 'emitLog'>;
     span: Span;
 }
 export declare const prepareFetchRequestBodySource: (request: Request | RequestInit) => Request | RequestInit | undefined;
-export declare const captureRequestBodyLog: ({ bodyConfig, domainContext, event, fetchRequest, runtimeContext, span, }: CaptureRequestBodyLogOptions) => Promise<void>;
+export declare const captureRequestBodyLog: ({ bodyConfig, domainContext, event, fetchRequest, occurredAt, runtimeContext, span, }: CaptureRequestBodyLogOptions) => Promise<void>;
 export {};

package/dist/plugins/resource.d.ts

@@ -1,4 +1,8 @@
 import type { BkOTPlugin } from '../core/plugin';
+/**
+ * Resource Timing 的统一消费端：静态资源按配置生成 span；Fetch/XHR timing 转交 request 插件，
+ * 与其已创建的请求 span 合并，避免同一次网络请求重复计数。
+ */
 type ResourceTimingWithStatus = PerformanceResourceTiming & {
     deliveryType?: string;
     renderBlockingStatus?: string;

package/dist/plugins/web-vitals.d.ts

@@ -55,6 +55,7 @@ interface ViewVitalState {
     interactionIdMax: number;
     interactionIdMin: number;
     inpCandidates: InpCandidate[];
+    id: string;
     largestShiftTarget?: string;
     largestShiftValue: number;
     runtimeAttributes: Attributes;
@@ -69,6 +70,7 @@ interface InpCandidate {
     presentationDelay: number;
     processingDuration: number;
 }
+export declare const isSameViewId: (currentViewId: string | undefined, nextViewId: string | undefined) => boolean;
 export declare const updateViewCls: (view: ViewVitalState, entry: LayoutShiftEntry) => void;
 export declare const updateViewInp: (view: ViewVitalState, entry: EventTimingEntry) => void;
 export declare const getViewInp: (view: ViewVitalState) => InpCandidate | undefined;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blueking/open-telemetry",
-  "version": "0.0.15",
+  "version": "0.0.17",
   "description": "OpenTelemetry browser SDK for BK RUM",
   "author": "TencentCloud Real User Monitoring",
   "main": "dist/index.js",

package/skills/bk-rum-otele/SKILL.md

@@ -22,8 +22,11 @@ description: 帮助业务方在前端应用里接入、使用和配置蓝鲸 RUM
 | 用户想做的事                                                                                | 读取                                  |
 | ------------------------------------------------------------------------------------------- | ------------------------------------- |
 | 第一次接入、安装、最小示例、CDN、生产推荐配置                                               | `references/getting-started.md`       |
+| 评估 SDK 能力边界、默认开关、浏览器 API、信号产出和降级行为                               | `references/capabilities.md`          |
+| 理解源码模块、初始化顺序、运行时上下文、过滤链路和 Hook 时机                              | `references/architecture.md`          |
 | 搞懂三类信号、Instrumentation vs Plugin、采样、数据归一、运行时上下文                       | `references/concepts.md`              |
-| 查配置项、默认值、transport/endpoint、采样、批量上报、traceparent 透传                      | `references/configuration.md`         |
+| 查配置项、默认值、Endpoint、插件参数和 Hook                                                | `references/configuration.md`         |
+| 查 Transport、单信号开关、批量上报、Session 采样和 traceparent 透传                       | `references/transport-sampling.md`    |
 | 开关某个采集能力、看请求配置和各插件参数（request/error/blankScreen/longTask/websocket 等） | `references/plugins.md`               |
 | 写自定义插件、接入第三方 OpenTelemetry instrumentation                                      | `references/custom-plugin.md`         |
 | 查公开 API（start/flush/shutdown/setUser/setView/reportAction/reportCustomEvent 等）        | `references/api.md`                   |
@@ -47,12 +50,12 @@ description: 帮助业务方在前端应用里接入、使用和配置蓝鲸 RUM
 
 SDK 把能力拆成两类：
 
-- **内置采集**：统一放在 `tracking`，包括 View、请求、资源、错误、Web Vitals、Action 等；其中 Fetch/XHR 由单一请求生命周期实现。
+- **内置采集**：统一放在 `tracking`，包括 View、请求、资源、错误、Web Vitals、Action 等；其中 Fetch/XHR 由 SDK 自有的单一请求生命周期直接 patch，统一创建 `browser.resource` CLIENT Span。
 - **扩展**：接入方的 RUM 插件放在 `extensions.plugins`，标准 OpenTelemetry instrumentation 放在 `extensions.instrumentations`。它们都使用 SDK 私有 provider，并遵循 Consent 生命周期。
 
 ### 会话级确定性采样
 
-`session.sampleRate`（0–1，默认 1）是**会话级确定性采样**，不是 trace 级。决定由 `application.name + session.id` 的稳定 hash 得出，同一 Session 的 span/log/metric 决定一致。未命中时数据不会导出，`reportAction()`、`reportCustomEvent()` 会被静默丢弃。调试时临时设 `sampleRate: 1` 和 `debug: true`。
+`session.sampleRate`（0–1，默认 1）是**会话级确定性采样**，不是 trace 级。决定由 `application.name + session.id` 的稳定 hash 得出，同一 Session 的 span/log/metric 决定一致。插件仍维护必要的浏览器生命周期，但未命中时数据不会导出，`reportAction()`、`reportCustomEvent()` 会被静默丢弃。调试时临时设 `sampleRate: 1` 和 `debug: true`。
 
 ### 运行时上下文
 
@@ -107,3 +110,5 @@ View Loading Time 默认开启；默认关闭、按需打开：`longTask`、`csp
 - **Consent**：未授权初始化时配置 `privacy.trackingConsent: 'not-granted'`，用户授权后调用 `setTrackingConsent('granted')`；撤销授权会停止采集并解除 patch。
 - **信号开关**：`transport.signals.traces/metrics/logs` 设为 `false` 可关闭对应导出链路；关闭 Trace 后不会注入 `traceparent`。只开 Metric 时没有精确 View 下钻。
 - **低基数路由**：用 `tracking.view.getPathGroup` 把 `/user/123` 归类成 `/user/:id`，避免高基数 URL 污染指标维度。
+- **手动 View 的时机**：使用 `autoStart: false`，先 `await start()` 建立 Session，再调用 `startView()`；启动前调用会因没有有效采样 Session 而被忽略。
+- **Action 命名隐私**：默认 `nameCollection: 'explicit'` 只读取 `data-bk-action-name`，否则退回标签名；只有显式设为 `text` 才读取可访问名称和 DOM 文本。

package/skills/bk-rum-otele/evals/evals.json

@@ -5,7 +5,7 @@
       "id": 0,
       "name": "vue3-integration",
       "prompt": "我们是一个 Vue3 + vue-router 的后台管理系统，想接入蓝鲸 RUM 做前端监控。collector 地址是 https://rum.example.com，token 放在 window.__RUM_TOKEN__。帮我写接入代码：要能追踪 SPA 路由切换、检测白屏（挂载点 #app），生产环境按 20% 采样，并且把 URL 里的 token 参数脱敏。",
-      "expected_output": "给出使用 @blueking/open-telemetry 的 BkOpenTelemetry 接入代码：app/transport(endpoint+token)、sampling.rate=0.2、blankScreen.rootSelector='#app'、privacy.redactUrl 脱敏 token、通过 route.getPathGroup 或 vue-router afterEach + setView 追踪 SPA 路由。API/配置项名称需与 SDK 实际一致。",
+      "expected_output": "给出使用 @blueking/open-telemetry 的 BkOpenTelemetry 接入代码：application/transport(endpoint+token)、session.sampleRate=0.2、tracking.blankScreen.rootSelector='#app'、privacy.redactUrl 脱敏 token、通过 tracking.view.getPathGroup 自动追踪或 manual + await start() + startView() 对接 vue-router。API/配置项名称需与 SDK 实际一致。",
       "files": [],
       "assertions": []
     },
@@ -13,7 +13,7 @@
       "id": 1,
       "name": "local-no-data-troubleshoot",
       "prompt": "我按文档接了 bk-rum，本地起了 collector 在 4318，但 Network 里没看到 /rum 请求，reportCustomEvent 也没上报，debug 我也开了。可能是什么问题？怎么排查？",
-      "expected_output": "排障应覆盖：sampling.rate 是会话级 sticky 采样、未命中时插件不启动且手动事件静默丢弃(建议调试设 rate:1)；enabled 是否为 false；建议 spanProcessor:'simple' 便于本地看数据；检查 collector 是否监听 4318、endpoint 是否正确。",
+      "expected_output": "排障应覆盖：session.sampleRate 是会话级确定性采样，未命中时手动事件静默丢弃（建议调试设 sampleRate:1）；enabled/Consent/有效 View 是否正常；建议 transport.signals.traces.processor:'simple'；检查 collector、endpoint 与 Network 中 /v1/rum、/v1/metrics、/v1/logs。",
       "files": [],
       "assertions": []
     },
@@ -21,7 +21,7 @@
       "id": 2,
       "name": "instrumentation-vs-plugin-httpbody",
       "prompt": "配置里有 instrumentations 和 plugins 两块，fetch、error 这些好像两边都能配？它们到底有什么区别？另外我想采集接口报错时的请求/响应 body 来排查问题，该怎么配、要注意什么？",
-      "expected_output": "正确区分 Instrumentation(官方探针，patch 原生 API，不受采样影响)与 Plugin(自研 RUM 数据，受会话级采样影响)；指出 request 内部使用官方 fetch/xhr instrumentation、error 属 plugins；说明请求统一为 resource span，通过 excludedUrls 过滤、allowedTracingUrls 控制 traceparent、beforeSend 增补或丢弃；HTTP body 默认关闭，显式配置 request.body 后默认只采集错误请求，必须配置 redact，并限制 Content-Type 和大小。",
+      "expected_output": "正确区分内置 tracking、RUM Plugin 与额外 OTel Instrumentation；指出当前 request 是 SDK 自有 Fetch/XHR patch，生成 browser.resource CLIENT Span，不使用官方 Fetch/XHR instrumentation；说明 excludedUrls、allowedTracingUrls、request.beforeSend；HTTP body 默认关闭，显式配置 tracking.request.body 后默认只采集错误请求，必须配置 redact，并限制 Content-Type 和大小。",
       "files": [],
       "assertions": []
     }

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` 导出，则它不是包的公共契约。