@blueking/open-telemetry 0.0.22 → 0.0.24

package/skills/bk-rum-otele/references/plugins-experience.md

@@ -1,124 +0,0 @@
-<!-- 本文件由 packages/open-telemetry/scripts/gen-skill-references.mjs 从 wikis 自动生成，请勿手改。 -->
-
-# 体验与性能插件
-
-体验类插件关注页面加载、资源、核心 Web 指标、空白屏、主线程阻塞和 SPA 路由切换。
-
-以下片段聚焦 `tracking` 配置，实际初始化仍需提供必填的 `application.name` 和有效的 `transport` endpoint 配置。
-
-## resource
-
-`resource` 插件默认开启，基于 PerformanceObserver 采集静态资源加载 span。
-
-```ts
-new BkOpenTelemetry({
-  tracking: {
-    resource: true,
-  },
-});
-```
-
-常见字段包括 `resource.type`、`resource.size`、`resource.protocol`、`url.full`、`server.address`。当 Resource Timing 数据可用时，还会上报：
-
-- `resource.redirect.*`、`resource.dns.*`、`resource.connect.*`、`resource.ssl.*`
-- `resource.first_byte.*`、`resource.download.*`、`resource.worker.*`
-- `resource.delivery_type`、`resource.render_blocking_status`
-
-每个网络阶段同时包含相对资源开始时刻的 `start` 与阶段 `duration`，单位均为 ms。跨域资源没有返回 `Timing-Allow-Origin` 时，浏览器不会暴露完整阶段数据，SDK 会保留资源总耗时，但不生成不可信的阶段字段。
-
-**产出遥测**：span `browser.resource`（`span_type=resource`）。
-
-## action 与挫败信号
-
-`action` 默认开启。它观察点击后的请求、DOM 变更、静态资源、错误和长任务，在活动稳定后计算 `action.loading_time`，不在浏览器统计子事件数量。
-
-自动点击还会判断三类挫败信号：
-
-- `rage_click`：1 秒内在同一元素 100px 范围内连续点击至少三次；滚动或文本选择会中断判定。每次原始点击都保留独立 Action Span，并附加 rage 语义。
-- `dead_click`：点击后没有页面活动、输入、滚动或文本选择；文本输入、链接、select、textarea、canvas、contenteditable 等无法可靠判断的元素会排除。
-- `error_click`：点击活动窗口内产生前端错误。
-
-信号写入 `action.frustration.type`（string[]），不生成挫败计数。为了完成连续点击判断，Action Span 最多延迟 1 秒创建；`action.id` 只在真实页面活动窗口内挂到关联事件上，不会因为这个上报等待期延长。
-
-## webVitals
-
-`webVitals` 插件默认开启，采集 CLS、FCP、INP、LCP、TTFB。FCP/LCP/TTFB 按指标发生时刻归属 View，CLS 使用每个 View 独立的 1 秒间隔/5 秒窗口，INP 使用候选交互的近似 p98，而不是简单最大值。它只产生带 `session.id`、`view.id` 和 attribution 的原始 Span，聚合由服务端完成。
-
-**产出遥测**：span `browser.web_vital`（`span_type=vital`，含 attribution 归因）。
-
-```ts
-new BkOpenTelemetry({
-  tracking: {
-    webVitals: true,
-  },
-});
-```
-
-## blankScreen
-
-`blankScreen` 插件默认开启。它会针对每个 View 等待页面活动稳定后执行九点分层采样；只有两次连续检测都超过阈值才上报。View 切换或页面隐藏会取消旧检测，恢复可见后重新调度。
-
-```ts
-new BkOpenTelemetry({
-  tracking: {
-    blankScreen: {
-      rootSelector: '#app',
-      checkDelay: 1000,
-      confirmationDelay: 200,
-      threshold: 0.8,
-      ignoreSelectors: ['.global-loading', '.skeleton'],
-    },
-  },
-});
-```
-
-SPA 应用建议配置 `rootSelector`。根节点在确认阶段仍不存在时会以 `missing_root` 原因上报；loading 和骨架屏样本不进入空白比例分母。
-
-**产出遥测**（仅判定为白屏时）：error span `browser.blank_screen`（`span_type=error`）。
-
-## longTask
-
-`longTask` 插件默认关闭。开启后优先通过 Long Animation Frames API 采集主线程阻塞；浏览器不支持时自动回退到 Long Tasks API，两种入口不会重复观察。
-
-```ts
-new BkOpenTelemetry({
-  tracking: {
-    longTask: {
-      threshold: 50,
-    },
-  },
-});
-```
-
-LoAF 会补充浏览器原生的 blocking duration、render/style/layout 阶段、最重脚本归因，并把每个脚本作为 `long_task.script` Span Event。回退到 Long Tasks API 时不伪造 blocking duration，每条浏览器 attribution 都作为 `long_task.attribution` Span Event 保留。初始化阶段的 buffered entries 延迟到后续宏任务批量处理，避免 SDK 启动自身制造阻塞。不支持 LoAF 和 Long Tasks API 的浏览器会跳过插件。
-
-**产出遥测**：span `browser.long_task`（`span_type=longtask`），计数与耗时分布由服务端派生。
-
-## View Loading Time
-
-View Loading Time 属于 View 管理器，默认启用，基于页面活动结束时间计算。
-
-自动计算规则：
-
-- 初始加载：取 `navigationStart → loadEventEnd` 与 `navigationStart → 页面活动结束` 的较大值。
-- SPA 路由：取 View 创建到页面活动结束的耗时。
-- Fetch/XHR 进行中、静态资源完成和 DOM Mutation 都属于活动；连续 100ms 无活动视为稳定。
-- SDK 自身上报、`view.excludedActivityUrls` 命中的请求，以及 `data-bk-excluded-activity-mutations` 节点下的 DOM 变更不参与计算。
-
-```ts
-new BkOpenTelemetry({
-  tracking: {
-    view: {
-      loadingTime: true,
-      excludedActivityUrls: [/\/events\/stream$/, '/analytics'],
-    },
-  },
-});
-```
-
-如果业务有明确的异步渲染完成点，可覆盖自动结果：
-
-```ts
-await loadAlarmDetail();
-bkOT.setViewLoadingTime();
-```

package/skills/bk-rum-otele/references/plugins-network.md

@@ -1,32 +0,0 @@
-<!-- 本文件由 packages/open-telemetry/scripts/gen-skill-references.mjs 从 wikis 自动生成，请勿手改。 -->
-
-# 网络扩展
-
-## Fetch/XHR
-
-`tracking.request` 默认开启。SDK 使用单层 patch 创建 `browser.resource` CLIENT Span：
-
-1. `excludedUrls` 命中时完全跳过。
-2. 创建带 `event.id/event.timestamp/event.type=resource` 的请求 Span。
-3. `allowedTracingUrls` 命中时注入 W3C Trace Context。
-4. 请求完成后补充状态、错误和 Resource Timing。
-5. `request.beforeSend` 可修改属性或返回 `false` 丢弃 Span。
-
-SDK 不读取或上报请求/响应 Body。
-
-## 静态资源
-
-`tracking.resource` 默认开启，使用 Resource PerformanceObserver 创建 `browser.resource` Span。Fetch/XHR 的 PerformanceEntry 只回填已有请求 Span，不重复上报。
-
-## WebSocket
-
-`tracking.websocket` 默认关闭。启用后通过 Proxy 保持原生静态常量、`instanceof` 和子类行为，只监听连接生命周期：
-
-- `browser.websocket` `event.phase=connect`
-- `browser.websocket` `event.phase=open`
-- `browser.websocket` `event.phase=error`
-- `browser.websocket` `event.phase=close`
-
-同一连接通过 `websocket.connection.id` 关联。SDK 不包裹 `send()`，不采集消息内容、数量或字节数，也不在客户端聚合建连时长。
-
-需要 Session/View 关联或活动总线时使用自定义 RUM 插件和 `context.startSpan()`；标准第三方采集可通过 OpenTelemetry instrumentation 扩展。

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

@@ -1,62 +0,0 @@
-<!-- 本文件由 packages/open-telemetry/scripts/gen-skill-references.mjs 从 wikis 自动生成，请勿手改。 -->
-
-# 插件总览
-
-插件是 `@blueking/open-telemetry` 的能力边界。获得采集授权后，SDK 先建立 Session、Device、View 上下文，再启动请求采集和其他 RUM 插件。
-
-## 默认插件组合
-
-```ts
-new BkOpenTelemetry({
-  application: { name: 'demo' },
-  transport: { endpoint: 'https://collector.example.com' },
-  tracking: {
-    request: true,
-    resource: true,
-    error: true,
-    webVitals: true,
-    blankScreen: true,
-    device: true,
-    action: true,
-  },
-});
-```
-
-`session` 和 View 生命周期是不可关闭的 RUM 基础能力；`tracking.view` 只切换自动/手动策略及 loading time。
-
-## 能力分类
-
-| 分类       | 插件                                                              | 主要信号                      |
-| ---------- | ----------------------------------------------------------------- | ----------------------------- |
-| 基础上下文 | Session、View、`device`                                           | span、runtime attributes |
-| 性能体验   | View Loading Time、`resource`、`webVitals`、`blankScreen`、`longTask` | span          |
-| 错误安全   | `error`、`cspViolation`                                           | span                          |
-| 网络扩展   | Fetch/XHR request patch、`websocket`                              | span             |
-| 用户行为   | `action`、`reportAction()`                                        | span                          |
-
-## 插件启用规则
-
-获得采集授权后，已启用插件会启动并维护页面生命周期；Session 级确定性 sampler 与 exporter processor 统一决定数据是否导出。未授权时不会 patch 浏览器 API、创建 Session 或启动插件；运行期可通过 `setTrackingConsent()` 切换。
-
-```ts
-new BkOpenTelemetry({
-  application: { name: 'demo' },
-  transport: { endpoint: 'https://collector.example.com' },
-  session: {
-    sampleRate: 0.1,
-  },
-  tracking: {
-    error: true,
-    webVitals: true,
-    action: true,
-  },
-});
-```
-
-## 选择建议
-
-- 首次接入：使用默认插件即可。
-- 需要分析慢页面：View Loading Time 默认开启；再开启 `longTask` 获取主线程与脚本归因。
-- 需要为请求增加业务字段或过滤请求：配置 `request.beforeSend` / `request.excludedUrls`。
-- 需要分析 CSP：开启 `cspViolation`。
-- 需要分析实时通信：开启 `websocket`，注意避免多个 SDK 实例重复 patch。