@blueking/open-telemetry 0.0.10 → 0.0.12

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

@@ -0,0 +1,149 @@
+<!-- 本文件由 packages/open-telemetry/scripts/gen-skill-references.mjs 从 wikis 自动生成，请勿手改。 -->
+
+# 框架集成
+
+SDK 不绑定具体框架。接入重点是：在应用入口初始化、提供低基数路由模板、为 blank screen 指定根节点、在登录态变化时更新用户上下文。
+
+## Vue 3
+
+```ts
+// bk-ot.ts
+import { BkOpenTelemetry } from '@blueking/open-telemetry';
+
+export const bkOT = new BkOpenTelemetry({
+  autoStart: false,
+  app: {
+    name: 'vue-rum-demo',
+    environment: import.meta.env.MODE,
+  },
+  transport: {
+    endpoint: 'https://rum-collector.example.com',
+  },
+  plugins: {
+    blankScreen: {
+      rootSelector: '#app',
+    },
+  },
+});
+```
+
+```ts
+// main.ts
+import { createApp } from 'vue';
+import { bkOT } from './bk-ot';
+import App from './App.vue';
+import router from './router';
+
+router.afterEach(to => {
+  bkOT.setView({
+    url: window.location.href,
+    urlPathGroup: to.matched.at(-1)?.path || to.path,
+    loadingType: 'route_change',
+  });
+});
+
+await bkOT.start();
+
+createApp(App).use(router).mount('#app');
+```
+
+## Vue Router 路由模板
+
+如果不想在 `afterEach` 中主动 `setView()`，可以通过 `route.getPathGroup` 统一处理。
+
+```ts
+const routeGroups = [
+  { group: '/alarm/:id', pattern: /^\/alarm\/[^/]+$/ },
+  { group: '/strategy/:id/edit', pattern: /^\/strategy\/[^/]+\/edit$/ },
+];
+
+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');
+    },
+  },
+});
+```
+
+## React Router
+
+```tsx
+import { BkOpenTelemetry } from '@blueking/open-telemetry';
+import { useEffect } from 'react';
+import { useLocation, useMatches } from 'react-router-dom';
+
+export const bkOT = new BkOpenTelemetry({
+  app: { name: 'react-rum-demo' },
+  transport: { endpoint: 'https://rum-collector.example.com' },
+  plugins: {
+    blankScreen: {
+      rootSelector: '#root',
+    },
+  },
+});
+
+export const RumRouteSync = () => {
+  const location = useLocation();
+  const matches = useMatches();
+
+  useEffect(() => {
+    bkOT.setView({
+      url: window.location.href,
+      urlPathGroup: matches.at(-1)?.pathname || location.pathname,
+      loadingType: 'route_change',
+    });
+  }, [location.pathname, matches]);
+
+  return null;
+};
+```
+
+## 登录态变化
+
+```ts
+import { bkOT } from './bk-ot';
+
+export const onLoginSuccess = (user: { id: string }) => {
+  bkOT.setUser({
+    id: user.id,
+  });
+};
+
+export const onLogout = () => {
+  bkOT.setUser({
+    id: undefined,
+  });
+};
+```
+
+## 微前端
+
+微前端场景建议只在主应用初始化一次 SDK，子应用通过主应用暴露的方法上报业务事件，避免多个 SDK 实例重复 patch fetch/xhr/WebSocket。
+
+```ts
+// 主应用
+import { BkOpenTelemetry } from '@blueking/open-telemetry';
+
+const bkOT = new BkOpenTelemetry({
+  app: { name: 'micro-frontend-host' },
+  transport: { endpoint: 'https://rum-collector.example.com' },
+});
+
+window.__BK_RUM__ = {
+  reportAction: bkOT.reportAction,
+  reportCustomEvent: bkOT.reportCustomEvent,
+  setView: bkOT.setView,
+};
+```
+
+```ts
+// 子应用
+window.__BK_RUM__?.reportCustomEvent({
+  name: 'sub_app_mounted',
+  attributes: {
+    'biz.sub_app': 'alarm',
+  },
+});
+```

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

@@ -0,0 +1,179 @@
+<!-- 本文件由 packages/open-telemetry/scripts/gen-skill-references.mjs 从 wikis 自动生成，请勿手改。 -->
+
+# 简介
+
+`@blueking/open-telemetry` 是面向浏览器真实用户监控（RUM）的 OpenTelemetry 封装 SDK。它基于 OpenTelemetry Web SDK，将页面访问、资源加载、接口请求、JavaScript 错误、Web Vitals、空白屏、会话、用户动作等浏览器事件统一转成 trace、metric、log 三类信号，并通过 OTLP HTTP 协议上报。
+
+## 适合解决什么问题
+
+- 统一采集前端页面性能、错误、接口请求、资源加载和用户行为。
+- 使用 OpenTelemetry 标准协议接入已有 Collector 或蓝鲸 RUM 后端。
+- 将浏览器事件与后端 trace 关联，定位一次访问中的慢请求、资源异常和前端错误。
+- 通过插件逐步打开高级采集能力，控制数据量、隐私和性能成本。
+
+## SDK 能力分层
+
+1. `core`：负责配置解析、provider/exporter 初始化、采样、插件生命周期和运行时上下文。
+2. `plugins`：负责浏览器 RUM 事件采集，包括页面、资源、错误、性能、会话、动作等能力。
+3. `schema`：负责 RUM 字段、span 类型、结果、耗时分桶等归一化模型。
+4. `browser` / `index`：分别提供 CDN 全局入口（`https://unpkg.com/@blueking/open-telemetry/dist/bk-rum.global.js`）和 ESM 模块入口（`@blueking/open-telemetry`）。
+
+## 最小示例
+
+```ts
+import { BkOpenTelemetry } from '@blueking/open-telemetry';
+
+new BkOpenTelemetry({
+  app: {
+    name: 'bk-rum-demo',
+    environment: 'production',
+    version: '1.0.0',
+  },
+  transport: {
+    endpoint: 'https://rum-collector.example.com',
+    token: 'report-token',
+  },
+});
+```
+
+默认情况下，SDK 会自动启动，并开启 documentLoad、fetch、xhr、userInteraction 以及 pageView、resource、error、webVitals、blankScreen、device、session 等基础 RUM 插件。
+
+# 快速上手
+
+本页从最小接入开始，逐步打开常用配置。所有示例都可以直接放在前端应用入口文件中，例如 `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: {
+    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'),
+  },
+  privacy: {
+    redactUrl: url => url.replace(/([?&]token=)[^&]+/g, '$1***'),
+    redactAttributes: attributes => {
+      const next = { ...attributes };
+      delete next['http.request.header.authorization'];
+      return next;
+    },
+  },
+});
+
+export default bkOT;
+```
+
+## 手动启动
+
+如果需要先注册自定义插件或 instrumentation，再启动 SDK，可以关闭 `autoStart`。
+
+```ts
+import { BkOpenTelemetry, createPlugin } from '@blueking/open-telemetry';
+
+const bkOT = new BkOpenTelemetry({
+  autoStart: false,
+  app: { name: 'bk-rum-demo' },
+  transport: { endpoint: 'https://rum-collector.example.com' },
+});
+
+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`，构造实例后会立即启动，不再允许追加插件。
+
+## CDN 接入
+
+构建产物提供 `dist/bk-rum.global.js`，会在浏览器上暴露全局变量 `BkOpenTelemetry`。可通过 [unpkg](https://unpkg.com/@blueking/open-telemetry/) 或 [jsDelivr](https://cdn.jsdelivr.net/npm/@blueking/open-telemetry/) 直接引用，无需本地构建。
+
+```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',
+    },
+  });
+</script>
+```
+
+## 手动上报业务事件
+
+```ts
+bkOT.reportAction({
+  type: 'click',
+  targetTag: 'button',
+  targetText: '提交订单',
+  attributes: {
+    'biz.order_id': '202605270001',
+  },
+});
+
+bkOT.reportCustomEvent({
+  name: 'checkout_success',
+  attributes: {
+    'biz.amount': 99.9,
+    'biz.currency': 'CNY',
+  },
+});
+```
+
+未命中采样时，`reportAction()` 和 `reportCustomEvent()` 会静默丢弃。调试阶段可以设置 `sampling.rate: 1` 和 `debug: true`。