@blueking/open-telemetry 0.0.14 → 0.0.16

package/skills/bk-rum-otele/references/framework-integration.md

@@ -12,14 +12,17 @@ import { BkOpenTelemetry } from '@blueking/open-telemetry';
 
 export const bkOT = new BkOpenTelemetry({
   autoStart: false,
-  app: {
+  application: {
     name: 'vue-rum-demo',
     environment: import.meta.env.MODE,
   },
   transport: {
     endpoint: 'https://rum-collector.example.com',
   },
-  plugins: {
+  tracking: {
+    view: {
+      tracking: 'manual',
+    },
     blankScreen: {
       rootSelector: '#app',
     },
@@ -35,10 +38,9 @@ import App from './App.vue';
 import router from './router';
 
 router.afterEach(to => {
-  bkOT.setView({
+  bkOT.startView({
+    name: to.matched.at(-1)?.path || to.path,
     url: window.location.href,
-    urlPathGroup: to.matched.at(-1)?.path || to.path,
-    loadingType: 'route_change',
   });
 });
 
@@ -49,7 +51,7 @@ createApp(App).use(router).mount('#app');
 
 ## Vue Router 路由模板
 
-如果不想在 `afterEach` 中主动 `setView()`，可以通过 `route.getPathGroup` 统一处理。
+自动模式不需要 `afterEach`，通过 `tracking.view.getPathGroup` 统一生成低基数路径。
 
 ```ts
 const routeGroups = [
@@ -58,10 +60,14 @@ const routeGroups = [
 ];
 
 new BkOpenTelemetry({
-  route: {
-    getPathGroup: url => {
-      const pathname = new URL(url, window.location.href).pathname;
-      return routeGroups.find(route => route.pattern.test(pathname))?.group || pathname.replace(/\/\d+/g, '/:id');
+  application: { name: 'vue-rum-demo' },
+  transport: { endpoint: 'https://rum-collector.example.com' },
+  tracking: {
+    view: {
+      getPathGroup: url => {
+        const pathname = new URL(url, window.location.href).pathname;
+        return routeGroups.find(route => route.pattern.test(pathname))?.group || pathname.replace(/\/\d+/g, '/:id');
+      },
     },
   },
 });
@@ -75,9 +81,10 @@ import { useEffect } from 'react';
 import { useLocation, useMatches } from 'react-router-dom';
 
 export const bkOT = new BkOpenTelemetry({
-  app: { name: 'react-rum-demo' },
+  application: { name: 'react-rum-demo' },
   transport: { endpoint: 'https://rum-collector.example.com' },
-  plugins: {
+  tracking: {
+    view: { tracking: 'manual' },
     blankScreen: {
       rootSelector: '#root',
     },
@@ -89,10 +96,9 @@ export const RumRouteSync = () => {
   const matches = useMatches();
 
   useEffect(() => {
-    bkOT.setView({
+    bkOT.startView({
+      name: matches.at(-1)?.pathname || location.pathname,
       url: window.location.href,
-      urlPathGroup: matches.at(-1)?.pathname || location.pathname,
-      loadingType: 'route_change',
     });
   }, [location.pathname, matches]);
 
@@ -127,14 +133,16 @@ export const onLogout = () => {
 import { BkOpenTelemetry } from '@blueking/open-telemetry';
 
 const bkOT = new BkOpenTelemetry({
-  app: { name: 'micro-frontend-host' },
+  application: { name: 'micro-frontend-host' },
   transport: { endpoint: 'https://rum-collector.example.com' },
 });
 
 window.__BK_RUM__ = {
   reportAction: bkOT.reportAction,
   reportCustomEvent: bkOT.reportCustomEvent,
-  setView: bkOT.setView,
+  setViewName: bkOT.setViewName,
+  setViewLoadingTime: bkOT.setViewLoadingTime,
+  startView: bkOT.startView,
 };
 ```
 

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

@@ -18,13 +18,15 @@
 3. `schema`：负责 RUM 字段、span 类型、结果、耗时分桶等归一化模型。
 4. `browser` / `index`：分别提供 CDN 全局入口（`https://unpkg.com/@blueking/open-telemetry/dist/bk-rum.global.js`）和 ESM 模块入口（`@blueking/open-telemetry`）。
 
+完整能力、默认开关与信号产出见[能力矩阵](./capabilities.md)，初始化顺序、上下文和导出过滤见[架构与数据流](./architecture.md)。
+
 ## 最小示例
 
 ```ts
 import { BkOpenTelemetry } from '@blueking/open-telemetry';
 
 new BkOpenTelemetry({
-  app: {
+  application: {
     name: 'bk-rum-demo',
     environment: 'production',
     version: '1.0.0',
@@ -36,144 +38,98 @@ 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()` 前。
+
+手动 View 也应在 `await start()` 建立 Session 后创建：
+
+```ts
+const bkOT = new BkOpenTelemetry({
+  application: { name: 'manual-view-demo' },
+  autoStart: false,
+  transport: { endpoint: 'https://rum-collector.example.com' },
+  tracking: { view: { tracking: 'manual' } },
+});
 
-## CDN 接入
+await bkOT.start();
+bkOT.startView({ name: '订单详情', url: location.href });
+```
 
-构建产物提供 `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` 时，手动事件静默丢弃。