@blueking/open-telemetry 0.0.22 → 0.0.23

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

@@ -1,31 +1,109 @@
 <!-- 本文件由 packages/open-telemetry/scripts/gen-skill-references.mjs 从 wikis 自动生成，请勿手改。 -->
 
-# 框架集成
+# 框架与路由集成
 
-SDK 不绑定具体框架。接入重点是：在应用入口初始化、提供低基数路由模板、为 blank screen 指定根节点、在登录态变化时更新用户上下文。
+SDK 不绑定 Vue、React 或具体 Router。框架集成主要解决四件事：单例初始化、View 边界、低基数路由模板、登录/卸载生命周期。
 
-## Vue 3
+## 先选择 View 模式
+
+### 自动模式
+
+适合大多数 History/hash SPA：
+
+```ts
+tracking: {
+  view: {
+    tracking: 'auto',
+    getPathGroup: groupRoute,
+  },
+}
+```
+
+SDK 监听 `history.pushState/replaceState`、`popstate` 和 `hashchange`。pathname/hash 变化创建新 View，query-only 变化不会创建。优点是接入少、能较早观测；缺点是无法直接读取 Router 的 route record 模板。
+
+### 手动模式
+
+适合 Router route record 是唯一可信边界、非 URL 页面状态或微前端统一路由：
+
+```ts
+tracking: {
+  view: { tracking: 'manual' },
+}
+```
+
+每次路由确认后调用 `startView()`。必须先 `await rum.start()` 让 Session 建立；不要同时使用自动模式，否则会重复 View。
+
+## 通用单例模块
 
 ```ts
-// bk-ot.ts
+// rum.ts
 import { BkOpenTelemetry } from '@blueking/open-telemetry';
 
-export const bkOT = new BkOpenTelemetry({
-  autoStart: false,
+export const rum = new BkOpenTelemetry({
   application: {
-    name: 'vue-rum-demo',
+    name: 'frontend-app',
     environment: import.meta.env.MODE,
+    version: __APP_VERSION__,
   },
   transport: {
-    endpoint: 'https://rum-collector.example.com',
+    endpoint: window.__RUM_ENDPOINT__,
+    token: window.__RUM_TOKEN__,
   },
+  tracking: {
+    blankScreen: { rootSelector: '#app' },
+  },
+});
+```
+
+模块必须只在应用入口导入一次。组件 render/setup 中不要创建实例；热更新时也要避免重复执行构造逻辑。
+
+## Vue 3：自动模式
+
+```ts
+// rum.ts
+import { BkOpenTelemetry } from '@blueking/open-telemetry';
+
+const routeGroups = [
+  { pattern: /^\/orders\/[^/]+$/, group: '/orders/:id' },
+  { pattern: /^\/users\/[^/]+\/edit$/, group: '/users/:id/edit' },
+];
+
+export const rum = new BkOpenTelemetry({
+  application: { name: 'vue-order-center' },
+  transport: { endpoint: window.__RUM_ENDPOINT__ },
   tracking: {
     view: {
-      tracking: 'manual',
+      getPathGroup(rawUrl) {
+        const path = new URL(rawUrl, location.href).pathname;
+        return routeGroups.find(item => item.pattern.test(path))?.group ?? path;
+      },
     },
-    blankScreen: {
-      rootSelector: '#app',
+    blankScreen: { rootSelector: '#app' },
+  },
+});
+```
+
+Vue Router 不需要额外 `afterEach`。如果业务使用 query 代表独立页面，自动模式不会划界，应改用手动模式。
+
+## Vue Router：手动模式
+
+```ts
+// rum.ts
+import { BkOpenTelemetry } from '@blueking/open-telemetry';
+
+export const rum = new BkOpenTelemetry({
+  application: { name: 'vue-order-center' },
+  transport: { endpoint: window.__RUM_ENDPOINT__ },
+  autoStart: false,
+  tracking: {
+    view: {
+      tracking: 'manual',
+      getPathGroup(rawUrl) {
+        const path = new URL(rawUrl, location.href).pathname;
+        return path.replace(/\/orders\/[^/]+/, '/orders/:id');
+      },
     },
+    blankScreen: { rootSelector: '#app' },
   },
 });
 ```
@@ -33,125 +111,290 @@ export const bkOT = new BkOpenTelemetry({
 ```ts
 // main.ts
 import { createApp } from 'vue';
-import { bkOT } from './bk-ot';
 import App from './App.vue';
 import router from './router';
+import { rum } from './rum';
+
+const app = createApp(App).use(router);
 
-router.afterEach(to => {
-  bkOT.startView({
-    name: to.matched.at(-1)?.path || to.path,
-    url: window.location.href,
+const syncView = (route: typeof router.currentRoute.value) => {
+  const record = route.matched.at(-1);
+  rum.startView({
+    name: String(record?.name ?? record?.path ?? route.path),
+    url: location.href,
+    attributes: {
+      'app.route.name': String(record?.name ?? ''),
+    },
   });
-});
+};
+
+async function bootstrap() {
+  await router.isReady();
+  await rum.start();
 
-await bkOT.start();
+  syncView(router.currentRoute.value);
+  router.afterEach(to => syncView(to));
+  app.mount('#app');
+}
 
-createApp(App).use(router).mount('#app');
+void bootstrap().catch(error => console.error('application bootstrap failed', error));
 ```
 
-## Vue Router 路由模板
+这里先同步一次当前 route，再注册后续导航，避免依赖 Router 初始导航 hook 的时序。`route.fullPath` 可能包含 query，不应直接作为 View name。
 
-自动模式不需要 `afterEach`，通过 `tracking.view.getPathGroup` 统一生成低基数路径。
+如果 blank screen 首检发生在应用 mount 之前，确保 HTML 已有 `#app` 根元素；否则应在初始化顺序或 `checkDelay` 上校准。
 
-```ts
-const routeGroups = [
-  { group: '/alarm/:id', pattern: /^\/alarm\/[^/]+$/ },
-  { group: '/strategy/:id/edit', pattern: /^\/strategy\/[^/]+\/edit$/ },
-];
+## React Router：自动模式
+
+如果 Router 使用浏览器 History，通常只需初始化 SDK：
 
-new BkOpenTelemetry({
-  application: { name: 'vue-rum-demo' },
-  transport: { endpoint: 'https://rum-collector.example.com' },
+```ts
+export const rum = new BkOpenTelemetry({
+  application: { name: 'react-order-center' },
+  transport: { endpoint: window.__RUM_ENDPOINT__ },
   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');
+      getPathGroup(rawUrl) {
+        return new URL(rawUrl, location.href).pathname.replace(/\/orders\/[^/]+/, '/orders/:id');
       },
     },
+    blankScreen: { rootSelector: '#root' },
   },
 });
 ```
 
-## React Router
+不要再用 `useLocation()` 调 `startView()`。
+
+## React Router：手动模式
+
+先在 render 前完成启动：
 
 ```tsx
-import { BkOpenTelemetry } from '@blueking/open-telemetry';
-import { useEffect } from 'react';
-import { useLocation, useMatches } from 'react-router-dom';
+// main.tsx
+import { createRoot } from 'react-dom/client';
+import { RouterProvider } from 'react-router-dom';
+import { rum } from './rum';
+import { router } from './router';
+
+async function bootstrap() {
+  await rum.start();
+
+  createRoot(document.getElementById('root')!).render(
+    <RouterProvider router={router} />,
+  );
+}
+
+void bootstrap().catch(error => console.error('application bootstrap failed', error));
+```
 
-export const bkOT = new BkOpenTelemetry({
-  application: { name: 'react-rum-demo' },
-  transport: { endpoint: 'https://rum-collector.example.com' },
+```ts
+// rum.ts
+export const rum = new BkOpenTelemetry({
+  application: { name: 'react-order-center' },
+  transport: { endpoint: window.__RUM_ENDPOINT__ },
+  autoStart: false,
   tracking: {
-    view: { tracking: 'manual' },
-    blankScreen: {
-      rootSelector: '#root',
+    view: {
+      tracking: 'manual',
+      getPathGroup: rawUrl =>
+        new URL(rawUrl, location.href).pathname.replace(/\/orders\/[^/]+/, '/orders/:id'),
     },
+    blankScreen: { rootSelector: '#root' },
   },
 });
+```
+
+在 Router context 内放置同步组件：
+
+```tsx
+import { useEffect, useRef } from 'react';
+import { useLocation, useMatches } from 'react-router-dom';
+import { rum } from './rum';
 
-export const RumRouteSync = () => {
+export function RumRouteSync() {
   const location = useLocation();
   const matches = useMatches();
+  const lastBoundary = useRef<string | undefined>(undefined);
+
+  const route = matches.at(-1);
+  const routeHandle = route?.handle as { rumViewName?: string } | undefined;
+  const routeTemplate = routeHandle?.rumViewName ?? route?.id ?? location.pathname;
+  const boundary = `${location.key}:${routeTemplate}`;
 
   useEffect(() => {
-    bkOT.startView({
-      name: matches.at(-1)?.pathname || location.pathname,
+    if (lastBoundary.current === boundary) return;
+    lastBoundary.current = boundary;
+
+    rum.startView({
+      name: routeTemplate,
       url: window.location.href,
+      attributes: {
+        'app.route.template': routeTemplate,
+      },
     });
-  }, [location.pathname, matches]);
+  }, [boundary, routeTemplate]);
 
   return null;
-};
+}
 ```
 
-## 登录态变化
+在 Data Router 的根 Layout 中挂载同步组件，确保它处于 Router Context 内，并先于页面 Outlet 渲染：
+
+```tsx
+// router.tsx
+import { Outlet, createBrowserRouter } from 'react-router-dom';
+import { RumRouteSync } from './RumRouteSync';
+
+function RootLayout() {
+  return (
+    <>
+      <RumRouteSync />
+      <Outlet />
+    </>
+  );
+}
+
+export const router = createBrowserRouter([
+  {
+    id: 'root',
+    element: <RootLayout />,
+    children: [
+      { id: 'home', path: '/', lazy: () => import('./routes/home') },
+      {
+        id: 'order-detail',
+        path: '/orders/:id',
+        handle: { rumViewName: '/orders/:id' },
+        lazy: () => import('./routes/order-detail'),
+      },
+    ],
+  },
+]);
+```
+
+可在 route `handle.rumViewName` 中提供稳定模板名；缺省时使用 route id。开发环境 React Strict Mode 可能重复运行 effect，示例用 ref 对同一 boundary 去重。是否将 query/search 视作新 boundary 由业务决定；上例使用 React Router 的 `location.key`，浏览器 history entry 变化会创建新 View。
+
+## Hash Router
+
+自动模式会观察 hash。默认 URL 清洗会移除 hash，所以 `view.url` 看不到 hash 内容，但 `getPathGroup(rawUrl)` 仍可在清洗前解析它：
 
 ```ts
-import { bkOT } from './bk-ot';
+getPathGroup(rawUrl) {
+  const url = new URL(rawUrl, location.href);
+  const hashPath = url.hash.replace(/^#/, '').split('?')[0] || '/';
+  return hashPath.replace(/\/orders\/[^/]+/, '/orders/:id');
+}
+```
 
-export const onLoginSuccess = (user: { id: string }) => {
-  bkOT.setUser({
-    id: user.id,
-  });
-};
+纯页面锚点如 `#section-a` 可能被自动模式视为 View 变化。大量锚点页面更适合 manual，或在路由层明确过滤。
+
+## Next.js / SSR
+
+SDK 是浏览器 SDK，必须只在客户端构造。不要在 Node SSR 阶段创建：
+
+```ts
+let rum: BkOpenTelemetry | undefined;
+
+export async function getRum() {
+  if (typeof window === 'undefined') return undefined;
+  if (rum) return rum;
 
-export const onLogout = () => {
-  bkOT.setUser({
-    id: undefined,
+  const { BkOpenTelemetry } = await import('@blueking/open-telemetry');
+  rum = new BkOpenTelemetry({
+    application: { name: 'next-portal' },
+    transport: { endpoint: window.__RUM_ENDPOINT__ },
+    tracking: { blankScreen: { rootSelector: '#__next' } },
   });
-};
+  return rum;
+}
 ```
 
-## 微前端
+这只是环境隔离模式，不绑定某个 Next.js 版本。App Router/Pages Router 的手动 View 边界应使用对应 Router 的官方客户端导航 API，并确保每次确认导航只调用一次。能被 History API 正确识别时优先 auto。
 
-微前端场景建议只在主应用初始化一次 SDK，子应用通过主应用暴露的方法上报业务事件，避免多个 SDK 实例重复 patch fetch/xhr/WebSocket。
+## 登录态同步
 
 ```ts
-// 主应用
-import { BkOpenTelemetry } from '@blueking/open-telemetry';
+export function onLogin(user: { rumId: string }) {
+  rum.setUser({ id: user.rumId });
+}
+
+export function onLogout() {
+  rum.setUser({ id: undefined });
+}
+```
+
+更新只影响后续 Span。应用首屏已经知道用户时，应放进 `context.user`，减少初始事件缺失用户关联。ID 需要业务预先脱敏。
+
+## Consent 异步初始化
+
+```ts
+const rum = new BkOpenTelemetry({
+  application: { name: 'consent-app' },
+  transport: { endpoint: window.__RUM_ENDPOINT__ },
+  privacy: { trackingConsent: 'not-granted' },
+});
 
-const bkOT = new BkOpenTelemetry({
-  application: { name: 'micro-frontend-host' },
-  transport: { endpoint: 'https://rum-collector.example.com' },
+consentManager.onChange(async allowed => {
+  await rum.setTrackingConsent(allowed ? 'granted' : 'not-granted');
 });
+```
+
+如果使用 manual View，授权后需要确认新的 Session 已创建，再按当前 Router 状态调用 `startView()`。自动模式会由 View 插件建立当前 View。
+
+这个示例适用于“授权前可以构造、但不能采集和发送”的策略。若合规要求授权前连 UA/UA-CH、内存等 Device Resource 快照都不能读取，应把 `new BkOpenTelemetry()` 本身也延迟到首次授权后；只设置 `trackingConsent: 'not-granted'` 不会推迟构造阶段的 Device Resource 读取。
+
+## 微前端
+
+推荐主应用持有唯一实例：
 
-window.__BK_RUM__ = {
-  reportAction: bkOT.reportAction,
-  reportCustomEvent: bkOT.reportCustomEvent,
-  setViewName: bkOT.setViewName,
-  setViewLoadingTime: bkOT.setViewLoadingTime,
-  startView: bkOT.startView,
+```ts
+// host
+const rumBridge = {
+  reportAction: rum.reportAction,
+  reportCustomEvent: rum.reportCustomEvent,
+  setUser: rum.setUser,
+  startView: rum.startView,
+  setViewName: rum.setViewName,
 };
+
+window.__BK_RUM__ = rumBridge;
 ```
 
+子应用只调用受控桥接：
+
 ```ts
-// 子应用
 window.__BK_RUM__?.reportCustomEvent({
   name: 'sub_app_mounted',
-  attributes: {
-    'biz.sub_app': 'alarm',
-  },
+  attributes: { 'app.sub_app': 'alarm' },
 });
 ```
+
+路由边界由一个责任方维护：
+
+- 主应用知道所有 route：主应用 manual `startView()`；
+- 子应用拥有内部 route：通过桥接请求主应用创建 View；
+- 不要主应用 auto、子应用 manual 同时工作。
+
+不要向子应用暴露 `setRuntimeAttributes` 或原始 tracer，避免破坏 Session/View 语义。
+
+## 应用卸载与重新挂载
+
+普通 SPA 生命周期不需要 `shutdown()`。只有整个应用永久卸载、测试清理或容器销毁时调用：
+
+```ts
+await rum.shutdown();
+```
+
+实例 shutdown 后不可 restart。微前端子应用卸载时不应关闭主应用实例。
+
+## 框架接入验收
+
+1. 同一页面只有一个 `BkOpenTelemetry`；
+2. auto/manual 只选一种路由边界；
+3. 首个 View 与每次导航各一组生命周期，不重复；
+4. route name/path group 不含动态 ID 和 query；
+5. blank root 对应真实挂载节点；
+6. 登录/登出正确更新或清除 user；
+7. SSR 不在服务端构造浏览器 SDK；
+8. React Strict Mode/HMR 不重复初始化或创建 View；
+9. 微前端只有一个责任方管理 View；
+10. 页面退出前不依赖 `shutdown()`，SDK 自身会在 hidden/pagehide 尽力 flush。