@blueking/open-telemetry 0.0.21 → 0.0.22

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

@@ -8,7 +8,7 @@
 
 ## session
 
-`session` 维护 `session.id`，并在会话开始和轮换时写入 log。它是所有 RUM 信号的关联边界，获得 Consent 后始终开启，不能关闭；是否导出由 Session 采样决定。
+`session` 维护 `session.id`，并在会话开始、轮换和结束时写入 `browser.session` 生命周期 Span。它是所有 RUM 事件的关联边界，获得 Consent 后始终开启，不能关闭；是否导出由 Session 采样决定。
 
 默认规则：
 
@@ -26,9 +26,9 @@ new BkOpenTelemetry({
 });
 ```
 
-超时固定为 15 分钟无活动、4 小时最长生命周期，不开放配置。过期会结束当前 View、刷新旧 session 的待发送数据，并丢弃此后所有不带有效 `session.id` 的 span/log/metric；下一次用户交互续期时，同时创建新的 Session 和 View。Metric 使用 DELTA temporality，避免累计值跨 session 重复上报。
+超时固定为 15 分钟无活动、4 小时最长生命周期，不开放配置。过期会结束当前 View、刷新旧 Session 的待发送数据，并丢弃此后所有不带有效 `session.id` 的 Span；下一次用户交互续期时，同时创建新的 Session 和 View。
 
-**产出遥测**：log `session.start` / `session.rotate`，并维护运行时属性 `session.id`。
+**产出遥测**：`browser.session` start/rotate/end Span，并维护 `session.id`、`session.start_time`、`session.type`。
 
 ## device
 
@@ -45,11 +45,11 @@ new BkOpenTelemetry({
 });
 ```
 
-稳定的浏览器、系统和硬件能力写入三类信号共享的 Resource；设备 ID、视口和网络信息保留为运行时属性，后续 span/log 会自动携带，便于按浏览器、系统、网络类型下钻。
+稳定的浏览器、系统和硬件能力写入 Resource；设备 ID、视口和网络信息保留为运行时属性，后续 Span 会自动携带。
 
 `device.id` 默认只在当前 SDK 实例内稳定；只有显式设置 `persistentId: true` 才写入 localStorage，并按应用名隔离默认 storage key。
 
-**产出遥测**：写入 Resource 属性（如 `browser.name`、`os.name`、`device.type`、`device.memory_gib`）和运行时属性（如 `device.id`、`browser.viewport.*`、`network.effective_type`），本身不单独产生 span/metric/log。
+**产出遥测**：写入 Resource 属性（如 `browser.name`、`os.name`、`device.type`、`device.memory_gib`）和运行时属性（如 `device.id`、`browser.viewport.*`、`network.effective_type`），本身不单独产生 Span。
 
 ## View
 
@@ -97,11 +97,11 @@ bkOT.startView({
 bkOT.setViewName('订单详情-只读');
 ```
 
-`view.id` 始终由 SDK 生成，`attributes` 不能覆盖 Session/View 等保留字段。普通 span/log 必须同时带有 `session.id` 和 `view.id` 才会进入导出链路；metric 只保留 `view.url_path_group` 等低基数维度，不携带唯一 `view.id`。手动模式在首次 `startView()` 前不会导出普通 RUM 数据。
+`view.id` 始终由 SDK 生成，`attributes` 不能覆盖 Session/View 等保留字段。普通 Span 必须同时带有 `session.id` 和 `view.id` 才会进入导出链路。手动模式在首次 `startView()` 前不会导出普通 RUM 数据。
 
 View Loading Time 默认开启：初始加载取 `loadEventEnd` 与页面活动结束时间的较大值，SPA 路由取 View 创建到页面活动结束的耗时。请求、静态资源和 DOM 变更都属于页面活动，连续 100ms 无活动视为稳定。长轮询或埋点请求应配置到 `view.excludedActivityUrls`；业务也可在真正渲染完成时调用 `setViewLoadingTime()` 覆盖自动结果。
 
-**产出遥测**：长 span `browser.view`（包含 `view.loading_time`）与 body 为 `browser.view` 的 create/update/final Snapshot Log，metric `browser.view.loading_time`，并维护 `view.*` 运行时属性。
+**产出遥测**：`browser.view` start/update/end 原始生命周期 Span。每次事件携带 `view.version`，Loading Time 就绪或 View 名称变化时产生 update。
 
 ## action
 

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

@@ -14,17 +14,14 @@
 - `unhandledrejection`
 - 资源加载错误
 
-插件会生成 error span，并使用 fingerprint 做窗口内节流，避免相同错误在短时间内刷屏。
+插件对每条原始错误生成 error Span，不在浏览器做错误指纹、计数或节流。
 
-**产出遥测**：span `browser.error`（JS 错误）、`browser.unhandledrejection`（Promise 异常）、`browser.resource_error`（资源加载失败），均为 `span_type=error`，带异常摘要、`error.source`、`error.window_occurrence_index`；精确总量由 `browser.error.count` 记录。
+**产出遥测**：Span `browser.error`（JS 错误）、`browser.unhandledrejection`（Promise 异常）、`browser.resource_error`（资源加载失败），均为 `span_type=error`，带原始 `error.message`、`error.source` 和标准 exception event。
 
 ```ts
 new BkOpenTelemetry({
   tracking: {
-    error: {
-      maxPerWindow: 5,
-      windowMs: 60_000,
-    },
+    error: true,
   },
 });
 ```
@@ -51,7 +48,7 @@ try {
 
 `cspViolation` 插件默认关闭。开启后监听浏览器 `securitypolicyviolation` 事件，并写入 error span。
 
-**产出遥测**：span `csp.violation`（`span_type=error`），带 `csp.*` 字段；完整策略 `csp.original_policy` 仅在节流窗口首条携带。
+**产出遥测**：Span `csp.violation`（`span_type=error`），每条都携带浏览器提供的 `csp.*` 字段和 `csp.original_policy`。
 
 ```ts
 new BkOpenTelemetry({

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

@@ -30,21 +30,21 @@ new BkOpenTelemetry({
 
 ## action 与挫败信号
 
-`action` 默认开启。它观察点击后的请求、DOM 变更、静态资源、错误和长任务，在活动稳定后计算 `action.loading_time` 和子事件数量。
+`action` 默认开启。它观察点击后的请求、DOM 变更、静态资源、错误和长任务，在活动稳定后计算 `action.loading_time`，不在浏览器统计子事件数量。
 
 自动点击还会判断三类挫败信号：
 
-- `rage_click`：1 秒内在同一元素 100px 范围内连续点击至少三次；滚动或文本选择会中断判定。三次点击合并为一条 action。
+- `rage_click`：1 秒内在同一元素 100px 范围内连续点击至少三次；滚动或文本选择会中断判定。每次原始点击都保留独立 Action Span，并附加 rage 语义。
 - `dead_click`：点击后没有页面活动、输入、滚动或文本选择；文本输入、链接、select、textarea、canvas、contenteditable 等无法可靠判断的元素会排除。
 - `error_click`：点击活动窗口内产生前端错误。
 
-信号写入 `action.frustration.type`（string[]）和 `action.frustration.count`。为了完成连续点击判断，action span 最多延迟 1 秒创建；`action.id` 只在真实页面活动窗口内挂到关联事件上，不会因为这个上报等待期延长。
+信号写入 `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，而不是简单最大值。它会同时产生 metric 和 span：metric 用于低基数聚合，span 用于通过 `session.id`、`view.id` 定位具体页面和归因信息。
+`webVitals` 插件默认开启，采集 CLS、FCP、INP、LCP、TTFB。FCP/LCP/TTFB 按指标发生时刻归属 View，CLS 使用每个 View 独立的 1 秒间隔/5 秒窗口，INP 使用候选交互的近似 p98，而不是简单最大值。它只产生带 `session.id`、`view.id` 和 attribution 的原始 Span，聚合由服务端完成。
 
-**产出遥测**：metric `browser.web_vital.cls`（unit `1`）、`browser.web_vital.duration`（unit `ms`，FCP/INP/LCP/TTFB 共用）+ span `browser.web_vital`（`span_type=vital`，含 attribution 归因）。
+**产出遥测**：span `browser.web_vital`（`span_type=vital`，含 attribution 归因）。
 
 ```ts
 new BkOpenTelemetry({
@@ -74,7 +74,7 @@ new BkOpenTelemetry({
 
 SPA 应用建议配置 `rootSelector`。根节点在确认阶段仍不存在时会以 `missing_root` 原因上报；loading 和骨架屏样本不进入空白比例分母。
 
-**产出遥测**（仅判定为白屏时）：metric `browser.blank_screen.count` + error span `browser.blank_screen`（`span_type=error`）。
+**产出遥测**（仅判定为白屏时）：error span `browser.blank_screen`（`span_type=error`）。
 
 ## longTask
 
@@ -85,15 +85,14 @@ new BkOpenTelemetry({
   tracking: {
     longTask: {
       threshold: 50,
-      warningThreshold: 100,
     },
   },
 });
 ```
 
-LoAF 会补充 blocking duration、render/style/layout 阶段、最重脚本归因，并把每个脚本作为 `long_task.script` Span Event。初始化阶段的 buffered entries 延迟到后续宏任务批量处理，避免 SDK 启动自身制造阻塞。不支持 LoAF 和 Long Tasks API 的浏览器会跳过插件。
+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 的浏览器会跳过插件。
 
-**产出遥测**：metric `browser.long_task.count` / `browser.long_task.duration` / `browser.long_task.blocking_duration`（unit `ms`）+ span `browser.long_task`（`span_type=longtask`）。
+**产出遥测**：span `browser.long_task`（`span_type=longtask`），计数与耗时分布由服务端派生。
 
 ## View Loading Time
 

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

@@ -1,141 +1,32 @@
 <!-- 本文件由 packages/open-telemetry/scripts/gen-skill-references.mjs 从 wikis 自动生成，请勿手改。 -->
 
-# 网络与扩展插件
+# 网络扩展
 
-网络能力覆盖 Fetch/XHR 与 WebSocket。两者都会 patch 浏览器全局 API，同一页面只应运行一个 SDK 实例。
+## Fetch/XHR
 
-以下片段聚焦 `tracking`，实际初始化仍需提供 `application.name` 和有效 Transport。
+`tracking.request` 默认开启。SDK 使用单层 patch 创建 `browser.resource` CLIENT Span：
 
-## Fetch/XHR request
+1. `excludedUrls` 命中时完全跳过。
+2. 创建带 `event.id/event.timestamp/event.type=resource` 的请求 Span。
+3. `allowedTracingUrls` 命中时注入 W3C Trace Context。
+4. 请求完成后补充状态、错误和 Resource Timing。
+5. `request.beforeSend` 可修改属性或返回 `false` 丢弃 Span。
 
-`tracking.request` 默认开启。当前实现由 SDK 自己统一 patch `window.fetch` 与 `XMLHttpRequest.prototype.open/send`，不使用官方 Fetch/XHR instrumentation，也不会为同一请求叠加两套生命周期。
+SDK 不读取或上报请求/响应 Body。
 
-### 请求生命周期
+## 静态资源
 
-一次请求按以下顺序处理：
+`tracking.resource` 默认开启，使用 Resource PerformanceObserver 创建 `browser.resource` Span。Fetch/XHR 的 PerformanceEntry 只回填已有请求 Span，不重复上报。
 
-1. 转成绝对 URL，检查 SDK 自身 OTLP Endpoint 与 `excludedUrls`。
-2. 创建名为 `browser.resource`、kind 为 `CLIENT` 的 Span。
-3. 记录 View/Action 页面活动；`view.excludedActivityUrls` 可只排除活动等待，不丢弃 Span。
-4. `allowedTracingUrls` 命中且 Trace 开启时进入传播 Header 注入分支；默认 W3C propagator 注入 `traceparent`，宿主已有全局 propagator 时以实际实现为准。
-5. 请求完成后写入状态、结果、错误和 `request.beforeSend` 属性。
-6. 等待最多 200ms 匹配 Resource Timing，把网络阶段补回同一 Span。
-7. 如已配置 Body 且 Log 开启，异步生成关联原 `trace.id` / `span.id` 的诊断 Log。
+## WebSocket
 
-**产出遥测**：Span `browser.resource`，`span_type=resource`、`resource.type=fetch|xhr`，常用属性包括 `http.request.method`、`http.response.status_code`、`url.full`、`server.address`、网络阶段与响应体积。
+`tracking.websocket` 默认关闭。启用后通过 Proxy 保持原生静态常量、`instanceof` 和子类行为，只监听连接生命周期：
 
-```ts
-new BkOpenTelemetry({
-  application: { name: 'request-demo' },
-  transport: { endpoint: 'https://collector.example.com' },
-  tracking: {
-    request: {
-      excludedUrls: [/\/health(?:\?|$)/],
-      beforeSend(event, context) {
-        event.attributes['request.transport'] = context.type;
-        return event.resource.statusCode !== 404;
-      },
-    },
-  },
-});
-```
+- `browser.websocket` `event.phase=connect`
+- `browser.websocket` `event.phase=open`
+- `browser.websocket` `event.phase=error`
+- `browser.websocket` `event.phase=close`
 
-`request.beforeSend` 在请求完成后执行，可修改 Span attributes；返回 `false` 会标记该 Span 在最终 processor 中丢弃，并立即跳过该请求的 Body Log。Hook 抛错不会中断业务请求，`debug: true` 时输出 warning。
+同一连接通过 `websocket.connection.id` 关联。SDK 不包裹 `send()`，不采集消息内容、数量或字节数，也不在客户端聚合建连时长。
 
-### excludedUrls 与 excludedActivityUrls
-
-| 配置 | 是否创建 Span | 是否计入 View/Action 活动 | 适用场景 |
-| --- | --- | --- | --- |
-| `tracking.request.excludedUrls` | 否 | 否 | 探活、埋点、无需采集的请求 |
-| `tracking.view.excludedActivityUrls` | 是 | 否 | 长轮询、SSE、流式接口，不应阻塞页面稳定 |
-
-两者都支持字符串包含、RegExp 和函数 matcher。
-
-### traceparent 注入条件
-
-只有 `allowedTracingUrls` 命中且 Trace 信号开启时才进入传播 Header 注入分支；默认 W3C propagator 会注入 `traceparent`，同源请求也不隐式放行。
-
-```ts
-tracking: {
-  request: {
-    allowedTracingUrls: [
-      url => new URL(url).origin === 'https://api.example.com',
-      /^https:\/\/[^/]+\.internal\.example\.com\//,
-    ],
-  },
-}
-```
-
-字符串 matcher 使用包含匹配，例如 `'https://api.example.com'` 也会命中 `https://api.example.com.evil/`，不适合作为安全 origin 边界。需要精确控制时使用上面的 URL-aware 函数或带 `/` 边界的正则。
-
-跨域注入会触发 CORS 预检，目标服务必须在 `Access-Control-Allow-Headers` 放行实际使用的 Trace Header。SDK 成功注册自己的默认 W3C propagator 时通常注入 `traceparent`，并可能透传已有 `tracestate`；如果宿主已注册全局 propagator，实际 Header 由该 propagator 决定，可能还包含其他传播字段。
-
-### Resource Timing
-
-Fetch/XHR 与静态资源共用一个 Resource PerformanceObserver：
-
-- `initiatorType=fetch|xmlhttprequest` 的 entry 只用于匹配请求 Span，不再创建静态资源 Span。
-- 通过 URL 与时间窗口匹配；找不到 entry 时请求 Span 仍正常结束。
-- 跨域接口缺少 `Timing-Allow-Origin` 时，浏览器不会提供完整阶段字段。
-- Trace 关闭时跳过 timing 等待，因为不存在可导出的请求 Span。
-
-### 请求/响应 Body
-
-Body 默认关闭。开启时必须提供 `redact`，默认只采集状态未知、0 或 `>=400` 的请求：
-
-```ts
-tracking: {
-  request: {
-    body: {
-      capture: 'errors',
-      maxSize: 10 * 1024,
-      allowedContentTypes: ['application/json', /^text\//],
-      redact({ body, kind }) {
-        if (kind === 'request') {
-          return body.replace(/("(?:password|token)"\s*:\s*)"[^"]*"/g, '$1"***"');
-        }
-        return body;
-      },
-    },
-  },
-}
-```
-
-**产出遥测**：Log `browser.request.body`，错误请求为 ERROR，`capture: 'all'` 下成功请求为 INFO。
-
-- Fetch 的 Request/Response 通过 clone 限量读取，不消费业务原始流。
-- XHR 支持文本与 JSON 响应。
-- string、URLSearchParams、Blob 等可文本化请求可读取；FormData、ArrayBuffer 和二进制响应跳过。
-- 默认 Content-Type：`text/*`、包含 `json`、`application/x-www-form-urlencoded`、`application/graphql`。
-- `redact` 返回 `undefined` 时只跳过当前 request 或 response Body。
-- Log 信号关闭时 Body 配置不生效。
-
-## websocket
-
-`tracking.websocket` 默认关闭。开启后用 Proxy 包装 `window.WebSocket`，保留静态常量、`instanceof` 与子类化行为。
-
-```ts
-new BkOpenTelemetry({
-  application: { name: 'realtime-demo' },
-  transport: { endpoint: 'https://collector.example.com' },
-  tracking: { websocket: true },
-});
-```
-
-**产出遥测**：
-
-- Span `websocket.connect`：只覆盖建连阶段，成功/失败后结束，不用长 Span 覆盖整个连接。
-- Metric `browser.websocket.message.count`、`browser.websocket.message.bytes`：按 `in/out` 分组。
-- Metric `browser.websocket.error.count`：按 `connect/runtime` 分组。
-- Metric `browser.websocket.connect.duration`：只记录成功建连耗时。
-- Log `websocket.error`、`websocket.close`：记录错误阶段和关闭详情。
-
-插件不读取消息内容，只计算数量和字节数。超过 64KB 的字符串使用 `string.length` 近似字节数，避免编码开销；CJK/emoji 会低估。相同 URL 的错误 Log 在 60 秒内最多 5 条，Error Counter 不受节流影响。
-
-SDK shutdown 后新建连接不再采集；已存在连接上的包装会保留，但回调立即返回。若其他库后来替换了 `window.WebSocket`，shutdown 不会强行覆盖后来者。
-
-## 与额外 instrumentation 的关系
-
-`extensions.instrumentations` 适合已有标准 OpenTelemetry instrumentation。不要再注册覆盖 Fetch/XHR 或用户交互的 instrumentation，否则可能与内置 request/action 重复 patch、重复 Span。
-
-需要 Session/View、`emitLog()`、页面活动或 RUM 归一字段时，优先写自定义插件，见[内置采集与扩展](./concepts.md)与[自定义插件](./custom-plugin.md)。
+需要 Session/View 关联或活动总线时使用自定义 RUM 插件和 `context.startSpan()`；标准第三方采集可通过 OpenTelemetry instrumentation 扩展。

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

@@ -28,10 +28,10 @@ new BkOpenTelemetry({
 
 | 分类       | 插件                                                              | 主要信号                      |
 | ---------- | ----------------------------------------------------------------- | ----------------------------- |
-| 基础上下文 | Session、View、`device`                                           | log、span、runtime attributes |
-| 性能体验   | View Loading Time、`resource`、`webVitals`、`blankScreen`、`longTask` | span、metric、log          |
+| 基础上下文 | Session、View、`device`                                           | span、runtime attributes |
+| 性能体验   | View Loading Time、`resource`、`webVitals`、`blankScreen`、`longTask` | span          |
 | 错误安全   | `error`、`cspViolation`                                           | span                          |
-| 网络扩展   | Fetch/XHR request patch、`websocket`                              | span、metric、log             |
+| 网络扩展   | Fetch/XHR request patch、`websocket`                              | span             |
 | 用户行为   | `action`、`reportAction()`                                        | span                          |
 
 ## 插件启用规则

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

@@ -24,7 +24,7 @@ new BkOpenTelemetry({
 
 ## 属性脱敏
 
-`privacy.redactAttributes` 会处理 Resource、通过 SDK `startSpan()`、`emitLog()` 以及内置插件显式应用的属性，适合删除 authorization、手机号、邮箱等字段。Resource 在 SDK 构造时处理一次，后续不会动态更新。
+`privacy.redactAttributes` 会处理 Resource、通过 SDK `startSpan()` 以及内置插件显式应用的属性，适合删除 authorization、手机号、邮箱等字段。Resource 在 SDK 构造时处理一次，后续不会动态更新。
 
 ```ts
 new BkOpenTelemetry({
@@ -40,16 +40,15 @@ new BkOpenTelemetry({
 });
 ```
 
-第三方 OpenTelemetry instrumentation 自己生成的 Span 属性不保证经过这一构造路径。需要统一清理第三方 Span 时，在 `tracking.beforeSend` 做最终兜底；该 Hook 作用于 Span/Log，不作用于 Metric。
+第三方 OpenTelemetry instrumentation 自己生成的 Span 属性不保证经过这一构造路径。需要统一清理第三方 Span 时，在 `tracking.beforeSend` 做最终兜底。
 
 `redactAttributes` 应返回完整可用的属性对象，不要只返回被修改的单个字段。
 
 ## 公共属性
 
-`context.attributes` 提供四类 hook：
+`context.attributes` 提供三类 hook：
 
 - `page`：页面、动作、错误等需要页面上下文的事件。
-- `metric`：metric 维度，必须避免高基数字段。
 - `error`：错误事件补充属性。
 - `custom`：手动自定义事件补充属性。
 
@@ -61,9 +60,6 @@ new BkOpenTelemetry({
         'biz.space_id': window.__BK_SPACE_ID__,
         'biz.project_id': window.__BK_PROJECT_ID__,
       }),
-      metric: () => ({
-        'biz.app_code': 'bk-monitor',
-      }),
       error: () => ({
         'biz.release_channel': window.__BK_RELEASE_CHANNEL__,
       }),
@@ -91,24 +87,7 @@ new BkOpenTelemetry({
 
 ## 请求数据边界
 
-SDK 默认不采集请求/响应 body。显式开启 `request.body` 时必须提供 `redact`，建议保持默认的 `capture: 'errors'`，并限制 Content-Type 和最大长度。
-
-```ts
-new BkOpenTelemetry({
-  tracking: {
-    request: {
-      body: {
-        capture: 'errors',
-        maxSize: 4096,
-        allowedContentTypes: ['application/json'],
-        redact: ({ body }) => {
-          return body.replace(/"password"\s*:\s*"[^"]+"/g, '"password":"***"');
-        },
-      },
-    },
-  },
-});
-```
+SDK 不读取或上报请求/响应 Body。
 
 ## 低基数路由