@blueking/open-telemetry 0.0.11 → 0.0.13

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blueking/open-telemetry",
-  "version": "0.0.11",
+  "version": "0.0.13",
   "description": "OpenTelemetry browser SDK for BK RUM",
   "author": "TencentCloud Real User Monitoring",
   "main": "dist/index.js",
@@ -8,7 +8,8 @@
   "jsdelivr": "dist/bk-rum.global.js",
   "license": "MIT",
   "files": [
-    "dist"
+    "dist",
+    "skills"
   ],
   "scripts": {
     "prepublishOnly": "pnpm build && pnpm dts && pnpm skill:refs",

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

@@ -0,0 +1,108 @@
+---
+name: bk-rum-otele
+description: 帮助业务方在前端应用里接入、使用和配置蓝鲸 RUM 浏览器上报 SDK（npm 包 @blueking/open-telemetry，核心类 BkOpenTelemetry）。只要用户提到蓝鲸 RUM 接入、前端监控上报、页面访问/接口/资源/JS 错误/Web Vitals/白屏/会话采集、BkOpenTelemetry 配置、OTLP 上报、采样、脱敏、自定义插件或手动上报业务事件（reportCustomEvent / reportAction），即使没有点名 SDK 名称，也应使用本 skill。
+---
+
+# 蓝鲸 RUM OpenTelemetry SDK 接入助手
+
+`@blueking/open-telemetry` 是蓝鲸 RUM 的浏览器上报 SDK，基于 OpenTelemetry Web SDK，把页面访问、接口请求、静态资源、JS 错误、Web Vitals、白屏、设备、会话、用户动作等浏览器事件统一转成 Trace / Metric / Log 三类信号，通过 OTLP HTTP 上报到 collector。
+
+本 skill 面向**集成使用方**：帮助把 SDK 接入到自己的前端应用，包括安装、配置、按需开关采集能力、框架集成、隐私脱敏、排障和手动上报。不覆盖 SDK 源码本身的开发维护。
+
+## 怎么用本 skill
+
+1. 先读下面的「核心心智模型」，它是理解一切配置的前提，尤其是 Instrumentation 与 Plugin 在采样上的差异——这是最容易踩坑的地方。
+2. 再按「任务路由」跳到对应的 `references/*.md` 拿完整细节和可复制的代码示例。不要凭记忆写配置，`references` 是权威来源。
+3. 给出配置时，默认从最小接入起步，再按用户实际诉求逐项打开能力，避免一次性堆满所有插件。
+
+## 任务路由
+
+根据用户诉求，读取对应参考文件（都在本 skill 的 `references/` 下）：
+
+| 用户想做的事 | 读取 |
+| --- | --- |
+| 第一次接入、安装、最小示例、CDN、生产推荐配置 | `references/getting-started.md` |
+| 搞懂三类信号、Instrumentation vs Plugin、采样、数据归一、运行时上下文 | `references/concepts.md` |
+| 查配置项、默认值、transport/endpoint、采样、批量上报、traceparent 透传 | `references/configuration.md` |
+| 开关某个采集能力、看插件清单和各插件参数（error/blankScreen/httpBody/longTask/websocket 等） | `references/plugins.md` |
+| 写自定义插件、接入第三方 OpenTelemetry instrumentation | `references/custom-plugin.md` |
+| 查公开 API（start/flush/shutdown/setUser/setView/reportAction/reportCustomEvent 等） | `references/api.md` |
+| Vue / React / Vue Router / 微前端 集成 | `references/framework-integration.md` |
+| URL 脱敏、属性脱敏、公共属性、低基数路由、user.id 处理 | `references/privacy.md` |
+| 了解上报字段、span_type/result/duration_bucket、哪些字段是后端派生 | `references/data-model.md` |
+| 查具体的 span 名 / metric 名 / log 事件名、完整属性字典 | `references/telemetry-reference.md` |
+| 本地看不到数据、手动事件没上报、白屏误报、接口 span 太多等排障 | `references/troubleshooting.md` |
+
+> `references/` 由 `packages/open-telemetry/scripts/gen-skill-references.mjs` 从 SDK 的 `wikis/` 自动生成，请勿手改。如内容过期，让维护者重新执行 `pnpm --filter @blueking/open-telemetry skill:refs`。
+
+## 核心心智模型
+
+### 三类信号
+
+- **Trace**：有起止时间的行为——页面访问、接口请求、资源加载、用户点击、长任务。
+- **Metric**：可聚合的数值——Web Vitals、长任务数、WebSocket 消息大小、白屏结果。
+- **Log**：离散事件——错误、CSP 违规、会话生命周期、HTTP body 错误路径。
+
+### Instrumentation 与 Plugin（最关键区别）
+
+SDK 把采集能力拆成两类，配置分别挂在顶层 `instrumentations` 和 `plugins` 下：
+
+- **Instrumentation**：OpenTelemetry 官方探针（`documentLoad`、`fetch`、`xhr`、`userInteraction`），负责 patch 浏览器原生 API。**只要 `enabled !== false` 就装载，不受采样影响。**
+- **Plugin**：bk-ot 自研的 RUM 能力单元（`pageView`、`resource`、`error`、`webVitals` 等），基于运行时上下文主动产生 RUM 归一数据。**产生 RUM 数据的插件只在会话命中采样时才启动。**
+
+### 会话级 sticky 采样
+
+`sampling.rate`（0–1，默认 1）是**会话级** sticky 采样，不是 trace 级。一次会话命中后 RUM 插件和手动事件都会上报；未命中时主动产生数据的插件不启动，`reportAction()`、`reportCustomEvent()` 会被静默丢弃。调试时临时设 `rate: 1` 和 `debug: true`。
+
+### 运行时上下文
+
+SDK 维护公共上下文并自动挂到后续 span/log/metric 上：`user.id`（业务方提供，SDK 原样透传、不 hash 不脱敏）、`session.id`（session 插件生成/轮换）、`view.*`（pageView 插件维护）。运行中可用 `setUser()` / `setView()` 更新。
+
+### 数据归一
+
+SDK 为 span 补充归一字段便于统一检索：`span_type`（document/http/resource/vital/error/longtask/action/route/custom）、`result`（success/warning/error/timeout/abort）、`duration_bucket`、`target_label` 等。
+
+## 最小接入速查
+
+npm：
+
+```javascript
+import { BkOpenTelemetry } from '@blueking/open-telemetry';
+
+const bkOT = new BkOpenTelemetry({
+  app: { name: 'demo-app', environment: 'production', version: '1.0.0' },
+  transport: { endpoint: 'https://your-otlp-collector', token: 'your-report-token' },
+  user: { id: window.USER_ID },
+});
+```
+
+CDN：
+
+```html
+<script src="https://unpkg.com/@blueking/open-telemetry/dist/bk-rum.global.js"></script>
+<script>
+  new window.BkOpenTelemetry({
+    app: { name: 'demo-app', environment: 'production' },
+    transport: { endpoint: 'https://your-otlp-collector', token: 'your-report-token' },
+  });
+</script>
+```
+
+`transport.endpoint` 填上报根地址（通常包含 `/v1` 路径前缀），SDK 自动拼 `/rum`、`/metrics`、`/logs`；`token` 作为 `Authorization: Bearer <token>` 默认头。构造后默认 `autoStart: true` 自动启动，无需手动 `start()`。
+
+## 默认采集能力清单
+
+只配 `app` + `transport` 即默认开启：
+
+- Instrumentation：`documentLoad`、`fetch`、`xhr`、`userInteraction`
+- Plugin：`pageView`、`resource`、`error`、`webVitals`、`blankScreen`、`device`、`session`
+
+默认关闭、按需打开：`action`、`httpBody`、`longTask`、`routeTiming`、`cspViolation`、`websocket`。关闭默认能力时显式设为 `false`。各插件参数见 `references/plugins.md`。
+
+## 关键易错点
+
+- **单实例**：`fetch`/`xhr`/`userInteraction`/`websocket` 会 patch 全局 API，同页面只应初始化一个 SDK 实例，微前端只在主应用初始化一次。
+- **`use()` / `useInstrumentation()` 必须在 `start()` 之前**：要注册自定义插件或 instrumentation，请设 `autoStart: false` 再手动 `start()`。
+- **采样影响手动上报**：未命中采样时 `reportAction()` / `reportCustomEvent()` 静默丢弃，排查时先确认采样。
+- **隐私要业务显式配置**：SDK 不猜哪些字段敏感，URL、属性、HTTP body 脱敏都需通过 `privacy` / `httpBody.redact` 显式处理；`user.id` 需 hash 的话要在传入前处理。
+- **低基数路由**：用 `route.getPathGroup` 把 `/user/123` 归类成 `/user/:id`，避免高基数 URL 污染指标维度。

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

@@ -0,0 +1,29 @@
+{
+  "skill_name": "bk-rum-otele",
+  "evals": [
+    {
+      "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 实际一致。",
+      "files": [],
+      "assertions": []
+    },
+    {
+      "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 是否正确。",
+      "files": [],
+      "assertions": []
+    },
+    {
+      "id": 2,
+      "name": "instrumentation-vs-plugin-httpbody",
+      "prompt": "配置里有 instrumentations 和 plugins 两块，fetch、error 这些好像两边都能配？它们到底有什么区别？另外我想采集接口报错时的请求/响应 body 来排查问题，该怎么配、要注意什么？",
+      "expected_output": "正确区分 Instrumentation(官方探针，patch 原生 API，不受采样影响)与 Plugin(自研 RUM 数据，受会话级采样影响)；指出 fetch/xhr 属 instrumentations、error 属 plugins；httpBody 默认关闭、只在错误路径(>=400/抛错)采集 body，需配 maxBodySize 与 redact 脱敏，提醒敏感信息处理。",
+      "files": [],
+      "assertions": []
+    }
+  ]
+}

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

@@ -0,0 +1,228 @@
+<!-- 本文件由 packages/open-telemetry/scripts/gen-skill-references.mjs 从 wikis 自动生成，请勿手改。 -->
+
+# API 参考
+
+本页按使用频率列出公开 API。完整类型以 `src/index.ts` 导出为准。
+
+## BkOpenTelemetry
+
+```ts
+import { BkOpenTelemetry } from '@blueking/open-telemetry';
+
+const bkOT = new BkOpenTelemetry({
+  app: { name: 'bk-rum-demo' },
+  transport: { endpoint: 'https://rum-collector.example.com' },
+});
+```
+
+### 实例成员总览
+
+`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`）。 |
+| `setView(view)` | `(view) => 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 和插件。
+
+```ts
+const bkOT = new BkOpenTelemetry({
+  autoStart: false,
+  transport: { endpoint: 'https://rum-collector.example.com' },
+});
+
+await bkOT.start();
+```
+
+### shutdown
+
+刷新数据、关闭 provider，并执行插件清理。关闭后不应再重启同一个实例。
+
+```ts
+await bkOT.shutdown();
+```
+
+### flush
+
+立即刷新插件、trace、metric、log。
+
+```ts
+window.addEventListener('beforeunload', () => {
+  void bkOT.flush();
+});
+```
+
+### use
+
+注册自定义插件，必须在 `start()` 前调用。
+
+```ts
+bkOT.use(
+  createPlugin({
+    name: 'biz-plugin',
+    init(context) {
+      const span = context.startSpan('custom.biz_plugin_ready');
+      span.end();
+    },
+  }),
+);
+```
+
+### useInstrumentation
+
+注册额外 OpenTelemetry instrumentation，必须在 `start()` 前调用。
+
+```ts
+bkOT.useInstrumentation(new SomeWebInstrumentation());
+```
+
+### setUser
+
+更新用户上下文。
+
+```ts
+bkOT.setUser({
+  id: 'user-12345',
+});
+```
+
+### setView
+
+更新当前 view 上下文。
+
+```ts
+bkOT.setView({
+  id: 'view-home',
+  url: window.location.href,
+  urlPathGroup: '/home',
+  loadingType: 'initial_load',
+});
+```
+
+### reportAction
+
+手动上报用户动作。
+
+```ts
+bkOT.reportAction({
+  type: 'click',
+  targetTag: 'button',
+  targetText: '保存',
+  attributes: {
+    'biz.form': 'alarm-strategy',
+  },
+});
+```
+
+### reportCustomEvent
+
+手动上报自定义事件。
+
+```ts
+bkOT.reportCustomEvent({
+  name: 'strategy_saved',
+  attributes: {
+    'biz.strategy_id': '10001',
+  },
+});
+```
+
+带错误的自定义事件：
+
+```ts
+bkOT.reportCustomEvent({
+  name: 'strategy_save_failed',
+  error: new Error('validation failed'),
+  attributes: {
+    'biz.strategy_id': '10001',
+  },
+});
+```
+
+## createPlugin
+
+```ts
+import { createPlugin } from '@blueking/open-telemetry';
+
+export const plugin = createPlugin({
+  name: 'page-visible',
+  init(context) {
+    context.emitLog({
+      severityText: 'INFO',
+      body: 'plugin init',
+      attributes: {
+        'document.visibility_state': document.visibilityState,
+      },
+    });
+  },
+});
+```
+
+## RUM_ATTRIBUTES
+
+`RUM_ATTRIBUTES` 提供字段 key 常量，避免手写字符串。
+
+```ts
+import { RUM_ATTRIBUTES } from '@blueking/open-telemetry';
+
+bkOT.reportCustomEvent({
+  name: 'biz_event',
+  attributes: {
+    [RUM_ATTRIBUTES.targetLabel]: 'submit-order',
+  },
+});
+```
+
+## RUM_SPAN_TYPE 与 buildRumSpanAttributes
+
+```ts
+import { RUM_SPAN_TYPE, buildRumSpanAttributes } from '@blueking/open-telemetry';
+
+const span = bkOT.startSpan('custom.cache_hit', {
+  ...buildRumSpanAttributes({
+    spanType: RUM_SPAN_TYPE.custom,
+    spanSubtype: 'cache',
+    eventLabel: '业务缓存',
+    targetLabel: 'homepage',
+    targetValue: true,
+  }),
+});
+
+span.end();
+```
+
+## resolveConfig
+
+`resolveConfig()` 可用于预览 SDK 核心配置解析结果。插件配置不会在这里展开默认值；内置插件会在各自创建时处理开关、默认值和参数兜底。
+
+```ts
+import { resolveConfig } from '@blueking/open-telemetry';
+
+const config = resolveConfig({
+  app: {
+    name: 'bk-rum-demo',
+  },
+});
+
+console.log(config.app.name);
+console.log(config.transport.traces.endpoint);
+```

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

@@ -0,0 +1,227 @@
+<!-- 本文件由 packages/open-telemetry/scripts/gen-skill-references.mjs 从 wikis 自动生成，请勿手改。 -->
+
+# 核心概念
+
+理解这些概念后，再看配置和插件会更顺畅。
+
+## 三类信号
+
+`@blueking/open-telemetry` 同时使用 OpenTelemetry 的三类信号：
+
+- Trace：用于描述一次有起止时间的行为，例如页面访问、接口请求、资源加载、用户点击、长任务。
+- Metric：用于描述可聚合的数值，例如 Web Vitals、长任务数量、WebSocket 消息大小、空白屏结果。
+- Log：用于描述离散事件或诊断信息，例如错误、CSP 违规、Session 生命周期、HTTP body 错误路径。
+
+示例：手动创建一个业务 span。
+
+```ts
+import { BkOpenTelemetry } from '@blueking/open-telemetry';
+
+const bkOT = new BkOpenTelemetry({
+  app: { name: 'checkout-web' },
+  transport: { endpoint: 'https://rum-collector.example.com' },
+});
+
+const span = bkOT.startSpan('custom.checkout_submit', {
+  'biz.order_id': '202605270001',
+  'biz.channel': 'pc',
+});
+
+span.end();
+```
+
+## Session、View、User
+
+SDK 会维护运行时公共上下文，并自动挂到后续 span/log 上：
+
+- `user.id`：由接入方提供，SDK 原样透传，不 hash、不脱敏、不改写。
+- `session.id`：由 session 插件生成和轮换，用于关联同一次访问会话。
+- `view.id` / `view.url` / `view.url_path_group`：由 pageView 插件维护，用于关联同一个页面或路由实例。
+
+示例：登录后更新用户上下文。
+
+```ts
+bkOT.setUser({
+  id: 'user-12345',
+});
+```
+
+示例：业务路由系统主动设置 view 上下文。
+
+```ts
+bkOT.setView({
+  id: 'view-product-detail',
+  url: window.location.href,
+  urlPathGroup: '/product/:id',
+  loadingType: 'route_change',
+});
+```
+
+## Instrumentation 与插件
+
+SDK 将能力分为两类：
+
+1. 官方 instrumentation：`documentLoad`、`fetch`、`xhr`、`userInteraction`，主要负责 patch 浏览器 API 或读取标准浏览器性能数据。
+2. RUM 插件：`pageView`、`resource`、`error`、`webVitals`、`blankScreen`、`device`、`session` 等，负责主动产生 RUM 归一数据。
+
+示例：关闭官方用户交互 instrumentation，仅使用 SDK 的 `action` 插件。
+
+```ts
+new BkOpenTelemetry({
+  instrumentations: {
+    userInteraction: false,
+  },
+  plugins: {
+    action: {
+      eventNames: ['click', 'submit', 'keydown'],
+    },
+  },
+});
+```
+
+## 采样
+
+`sampling.rate` 是会话级 sticky 采样。一次会话命中后，RUM 插件和手动事件都会上报；未命中时，主动产生数据的插件不会启动，`reportAction()` 和 `reportCustomEvent()` 会丢弃。
+
+示例：生产环境按 10% 会话采样。
+
+```ts
+new BkOpenTelemetry({
+  sampling: {
+    rate: 0.1,
+  },
+  transport: {
+    endpoint: 'https://rum-collector.example.com',
+  },
+});
+```
+
+## 数据归一
+
+SDK 会为 span 补充 RUM 归一字段，例如：
+
+- `span_type`：`document`、`http`、`resource`、`vital`、`error`、`longtask`、`action`、`route`、`custom`
+- `result`：`success`、`warning`、`error`、`timeout`、`abort`
+- `duration_bucket`：`<100ms`、`100~500ms`、`500ms~2s`、`>2s`
+- `target_label`：跨类型的主标签，用于统一检索
+
+示例：自定义 span 也可以复用归一字段构造器。
+
+```ts
+import { RUM_SPAN_TYPE, buildRumSpanAttributes } from '@blueking/open-telemetry';
+
+const span = bkOT.startSpan('custom.cache_warmup', {
+  ...buildRumSpanAttributes({
+    spanType: RUM_SPAN_TYPE.custom,
+    spanSubtype: 'cache_warmup',
+    eventLabel: '缓存预热',
+    targetLabel: 'homepage',
+  }),
+});
+
+span.end();
+```
+
+# Plugin 与 Instrumentation 的区别
+
+`@blueking/open-telemetry` 把采集能力拆成两类：**官方 Instrumentation** 和 **RUM 插件（Plugin）**。两者在配置入口、数据来源、生命周期和采样行为上都不同，理解差异有助于按需裁剪采集能力。
+
+## 一句话区分
+
+- **Instrumentation**：OpenTelemetry 官方/第三方探针，负责 patch 浏览器原生 API 或读取标准性能数据，是「数据从哪来」的底层来源。
+- **Plugin**：bk-ot 自研的能力单元，基于 runtime context 主动产生 RUM 归一数据，是「我们要采什么、怎么归一」的业务层。
+
+## 配置入口
+
+两类能力在配置上完全对称，分别挂在顶层的 `instrumentations` 和 `plugins` 下：
+
+```ts
+new BkOpenTelemetry({
+  // 官方探针：开关 + 自定义实例
+  instrumentations: {
+    documentLoad: true,
+    fetch: true,
+    xhr: true,
+    userInteraction: true,
+    custom: [new MyCustomInstrumentation()],
+  },
+  // bk-ot 自研插件：开关 + 自定义插件
+  plugins: {
+    pageView: true,
+    error: true,
+    webVitals: true,
+    custom: [myBizPlugin],
+  },
+});
+```
+
+## 内置能力清单
+
+| 类型            | 内置项                                                                                                                       |
+| --------------- | ---------------------------------------------------------------------------------------------------------------------------- |
+| Instrumentation | `documentLoad`、`fetch`、`xhr`、`userInteraction`                                                                            |
+| Plugin          | `pageView`、`resource`、`error`、`webVitals`、`blankScreen`、`device`、`session`、`action`、`httpBody`、`longTask`、`routeTiming`、`cspViolation`、`websocket` |
+
+## 核心差异对比
+
+| 维度         | Instrumentation                                  | Plugin                                              |
+| ------------ | ------------------------------------------------ | --------------------------------------------------- |
+| 来源         | OpenTelemetry 官方包 / 第三方                    | bk-ot 自研                                          |
+| 职责         | patch 原生 API、读取标准性能数据                 | 基于 runtime context 主动产生 RUM 归一数据          |
+| 配置位置     | `instrumentations: {}`                           | `plugins: {}`                                       |
+| 自定义扩展   | `instrumentations.custom` / `useInstrumentation()` | `plugins.custom` / `use()` / `createPlugin()`     |
+| 启动条件     | **SDK 启用（`enabled`）即装载**                  | 官方探针适配插件随 SDK 启用；产生 RUM 数据的插件**仅采样命中时启动** |
+| 受采样影响   | 否                                               | 是（RUM 数据插件未命中采样时不启动）                |
+
+## 生命周期与采样
+
+这是两者最容易混淆、也最关键的差异：
+
+- **Instrumentation 不受采样影响**。只要 `enabled !== false`，官方探针与 `instrumentations.custom` 中的实例都会在 `start()` 时注册。它们 patch 的是底层 API，需要在采样判定之前就位。
+
+  > 注意：这里的"不受采样影响"指的是**是否装载/patch**。未命中采样的会话，trace sampler 的比例为 `0`，探针产生的 span 仍会在采样阶段被丢弃、不会上报。也就是说 patch 照做，但数据最终不落库。
+- **RUM 插件受采样影响**。`sampling.rate` 是会话级 sticky 采样，未命中的会话不会启动主动产生数据的插件，`reportAction()`、`reportCustomEvent()` 也会丢弃。
+
+> 说明：SDK 内部把官方 instrumentation 封装成一个核心适配插件（`official-instrumentations`），它与自研 RUM 插件走同一套插件生命周期，但归属于「SDK 启用即装载」的核心插件，不参与采样开关。
+
+## 如何扩展
+
+### 接入第三方 Instrumentation
+
+两种等价写法，都必须在 `start()` 之前：
+
+```ts
+// 写法一：配置式
+new BkOpenTelemetry({
+  autoStart: false,
+  instrumentations: {
+    custom: [new MyCustomInstrumentation()],
+  },
+});
+
+// 写法二：链式（适合运行时动态追加）
+bkOT.useInstrumentation(new MyCustomInstrumentation());
+await bkOT.start();
+```
+
+### 编写自研 Plugin
+
+通过 `createPlugin()` 访问 `tracer`、`meter`、`logger`、`startSpan()`、`emitLog()` 等 runtime context 能力，详见[自定义插件](./custom-plugin.md)。
+
+```ts
+import { createPlugin } from '@blueking/open-telemetry';
+
+const bizPlugin = createPlugin({
+  name: 'biz-plugin',
+  init(context) {
+    const span = context.startSpan('custom.biz_ready');
+    span.end();
+  },
+});
+```
+
+## 选择建议
+
+- 只想 patch 一个浏览器/网络 API、拿标准遥测数据 → 用 **Instrumentation**（优先看官方是否已有现成包）。
+- 想产生带 RUM 归一字段（`span_type`、`result`、`target_label` 等）的业务事件、需要访问运行时上下文 → 用 **Plugin**。
+- 想让能力跟随采样开关、只对命中会话生效 → 必须做成 **Plugin**（RUM 数据类）。