@blueking/open-telemetry 0.0.13 → 0.0.15

package/skills/bk-rum-otele/references/getting-started.md

@@ -24,7 +24,7 @@
 import { BkOpenTelemetry } from '@blueking/open-telemetry';
 
 new BkOpenTelemetry({
-  app: {
+  application: {
     name: 'bk-rum-demo',
     environment: 'production',
     version: '1.0.0',
@@ -36,144 +36,84 @@ new BkOpenTelemetry({
 });
 ```
 
-默认情况下，SDK 会自动启动，并开启 documentLoad、fetch、xhr、userInteraction 以及 pageView、resource、error、webVitals、blankScreen、device、session 等基础 RUM 插件。
+默认情况下，SDK 会自动启动，建立 Session 和 View，并开启 request（内部组合 Fetch/XHR）、action、resource、error、webVitals、blankScreen、device 等基础采集能力。
 
 # 快速上手
 
-本页从最小接入开始，逐步打开常用配置。所有示例都可以直接放在前端应用入口文件中，例如 `main.ts`、`bootstrap.ts` 或独立的 `bk-ot.ts`。
-
-## 安装
+## 安装与初始化
 
 ```bash
 pnpm add @blueking/open-telemetry
 ```
 
-## 最小接入
-
-```ts
-import { BkOpenTelemetry } from '@blueking/open-telemetry';
-
-new BkOpenTelemetry({
-  transport: {
-    endpoint: 'https://rum-collector.example.com',
-    token: 'report-token',
-  },
-});
-```
-
-这段代码会使用默认应用名 `unknown_service`、默认环境 `production`，并自动启动 SDK。生产环境建议显式声明应用信息。
-
-## 推荐生产配置
-
 ```ts
 import { BkOpenTelemetry } from '@blueking/open-telemetry';
 
-const bkOT = new BkOpenTelemetry({
-  app: {
+export const bkOT = new BkOpenTelemetry({
+  application: {
     name: 'bk-monitor-web',
     environment: 'production',
     version: '1.4.2',
   },
-  user: {
-    id: window.__BK_USER__?.id,
-  },
   transport: {
     endpoint: 'https://rum-collector.example.com',
     token: window.__BK_RUM_TOKEN__,
   },
-  sampling: {
-    rate: 0.2,
-  },
-  route: {
-    getPathGroup: url => new URL(url).pathname.replace(/\/\d+/g, '/:id'),
+  session: {
+    sampleRate: 0.2,
   },
-  privacy: {
-    redactUrl: url => url.replace(/([?&]token=)[^&]+/g, '$1***'),
-    redactAttributes: attributes => {
-      const next = { ...attributes };
-      delete next['http.request.header.authorization'];
-      return next;
+  tracking: {
+    view: {
+      getPathGroup: url => new URL(url).pathname.replace(/\/\d+/g, '/:id'),
     },
   },
+  context: {
+    user: { id: window.__BK_USER__?.id },
+  },
 });
-
-export default bkOT;
 ```
 
-## 手动启动
+`application.name` 与 `transport` 必填。通常提供根 `transport.endpoint`；如果所有已开启信号都有独立 endpoint，则可省略根地址。SDK 默认自动启动。
 
-如果需要先注册自定义插件或 instrumentation，再启动 SDK，可以关闭 `autoStart`。
+## 手动启动与扩展
 
 ```ts
-import { BkOpenTelemetry, createPlugin } from '@blueking/open-telemetry';
-
 const bkOT = new BkOpenTelemetry({
+  application: { name: 'bk-rum-demo' },
   autoStart: false,
-  app: { name: 'bk-rum-demo' },
   transport: { endpoint: 'https://rum-collector.example.com' },
+  extensions: { plugins: [bizReadyPlugin] },
 });
 
-bkOT.use(
-  createPlugin({
-    name: 'biz-ready',
-    init(context) {
-      const span = context.startSpan('custom.biz_ready', {
-        'biz.stage': 'bootstrap',
-      });
-      span.end();
-    },
-  }),
-);
-
 await bkOT.start();
 ```
 
-`use()` 和 `useInstrumentation()` 必须在 `start()` 之前调用。如果使用默认 `autoStart: true`，构造实例后会立即启动，不再允许追加插件。
+`use()`、`useInstrumentation()` 和 `extensions` 注册都必须发生在 `start()` 前。
 
-## CDN 接入
-
-构建产物提供 `dist/bk-rum.global.js`，会在浏览器上暴露全局变量 `BkOpenTelemetry`。可通过 [unpkg](https://unpkg.com/@blueking/open-telemetry/) 或 [jsDelivr](https://cdn.jsdelivr.net/npm/@blueking/open-telemetry/) 直接引用，无需本地构建。
+## CDN
 
 ```html
-<!-- 最新版本 -->
 <script src="https://unpkg.com/@blueking/open-telemetry/dist/bk-rum.global.js"></script>
-<!-- 或锁定版本（推荐生产环境，将 <version> 替换为实际版本号，如 0.0.10） -->
-<!-- <script src="https://unpkg.com/@blueking/open-telemetry@<version>/dist/bk-rum.global.js"></script> -->
-<!-- jsDelivr 备选： -->
-<!-- <script src="https://cdn.jsdelivr.net/npm/@blueking/open-telemetry/dist/bk-rum.global.js"></script> -->
 <script>
-  new window.BkOpenTelemetry({
-    app: {
-      name: 'legacy-web',
-      environment: 'production',
-    },
-    transport: {
-      endpoint: 'https://rum-collector.example.com',
-      token: 'report-token',
-    },
+  window.bkOT = new window.BkOpenTelemetry({
+    application: { name: 'legacy-web', environment: 'production' },
+    transport: { endpoint: 'https://rum-collector.example.com', token: 'report-token' },
   });
 </script>
 ```
 
-## 手动上报业务事件
+## 手动事件
 
 ```ts
 bkOT.reportAction({
-  type: 'click',
-  targetTag: 'button',
-  targetText: '提交订单',
-  attributes: {
-    'biz.order_id': '202605270001',
-  },
+  name: '提交订单',
+  attributes: { 'biz.order_id': '202607160001' },
 });
 
 bkOT.reportCustomEvent({
   name: 'checkout_success',
-  attributes: {
-    'biz.amount': 99.9,
-    'biz.currency': 'CNY',
-  },
+  attributes: { 'biz.amount': 99.9 },
 });
 ```
 
-未命中采样时，`reportAction()` 和 `reportCustomEvent()` 会静默丢弃。调试阶段可以设置 `sampling.rate: 1` 和 `debug: true`。
+未命中 `session.sampleRate` 时，手动事件静默丢弃。