@blueking/open-telemetry 0.0.19 → 0.0.20

package/dist/plugins/device.d.ts

@@ -1,16 +1,17 @@
 import type { BkOTPlugin } from '../core/plugin';
+import type { Attributes } from '@opentelemetry/api';
 export interface BkOTDevicePluginOptions {
     /** 是否跨页面持久化匿名设备 ID，默认 false。 */
     persistentId?: boolean;
     storageKey?: string;
 }
+export declare const getDeviceResourceAttributes: () => Attributes;
 /**
- * 设备元数据采集插件，把"设备级"信息写入 SDK 的 runtimeAttributes，
- * 让所有 log/span 都自动带上这些维度。
+ * 设备元数据采集插件。稳定的设备能力由 SDK 写入 Resource；这里只维护设备 ID 和运行期动态属性。
  *
  * 上报字段：
  * - `device.id`：设备级永久标识，存于 localStorage（默认 key 复用旧 session 插件以保留现网用户）。
- * - `device.memory` / `device.cpu_cores` / `device.platform` / `device.mobile`：硬件能力快照（运行期不变）。
+ * - `device.memory_gib` / `device.logical_processor_count`：硬件能力快照，写入 Resource。
  * - `browser.viewport.*` / `browser.screen.*`：视口与屏幕尺寸。
  * - `network.effective_type` / `network.connection_type` / `network.downlink` / `network.rtt` / `network.save_data`：
  *   网络信息。

package/dist/schema/attributes.d.ts

@@ -19,6 +19,8 @@ export declare const RUM_ATTRIBUTES: {
     readonly browserName: "browser.name";
     readonly browserVersion: "browser.version";
     readonly cacheHit: "resource.cache.hit";
+    readonly deviceLogicalProcessorCount: "device.logical_processor_count";
+    readonly deviceMemoryGib: "device.memory_gib";
     readonly deviceType: "device.type";
     readonly errorType: "error_type";
     readonly exceptionFingerprint: "exception.fingerprint";
@@ -35,6 +37,7 @@ export declare const RUM_ATTRIBUTES: {
     readonly networkEffectiveType: "network.effective_type";
     readonly nextHopProtocol: "resource.protocol";
     readonly result: "result";
+    readonly rumSchemaVersion: "rum.schema.version";
     readonly serviceName: "service.name";
     readonly serviceVersion: "service.version";
     readonly osName: "os.name";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blueking/open-telemetry",
-  "version": "0.0.19",
+  "version": "0.0.20",
   "description": "OpenTelemetry browser SDK for BK RUM",
   "author": "TencentCloud Real User Monitoring",
   "main": "dist/index.js",

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

@@ -123,7 +123,7 @@ Fetch/XHR 由 `createCommonInstrumentationsPlugin()` 的单一生命周期直接
 | 入口 | 作用范围 | 适合用途 |
 | --- | --- | --- |
 | `privacy.redactUrl` | SDK 写入的 URL 类属性 | 删除 query/hash、模板化路径 |
-| `privacy.redactAttributes` | 通过 SDK `startSpan()`、`emitLog()` 和内置插件显式应用的属性 | 删除敏感业务字段 |
+| `privacy.redactAttributes` | Resource、通过 SDK `startSpan()`、`emitLog()` 和内置插件显式应用的属性 | 删除敏感业务字段 |
 | `tracking.request.beforeSend` | 单个 Fetch/XHR，带原始 Request/Response/XHR 上下文 | 请求专属补充或丢弃 |
 | Request Body `redact` | 单个请求/响应 Body，必填 | 内容级脱敏；返回 `undefined` 跳过该 Body |
 | `tracking.beforeSend` | Span/Log 进入底层 processor 前 | 最终兜底修改或丢弃；不作用于 Metric |

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

@@ -18,7 +18,7 @@
 | 手动 Action | `reportAction()` | 可调用 | 业务调用 | `action.custom` | — | — |
 | 自定义事件 | `reportCustomEvent()` | 可调用 | 业务调用 | `custom.<name>` | — | — |
 | 白屏 | `tracking.blankScreen` | 开 | DOM 命中测试、View 活动 | `browser.blank_screen` | `browser.blank_screen.count` | — |
-| 设备 | `tracking.device` | 开 | UA、UA-CH、Screen、Network Information | 作为公共属性 | — | 作为公共属性 |
+| 设备 | `tracking.device` | 开 | UA、UA-CH、Screen、Network Information | Resource 与运行时公共属性 | — | Resource 与运行时公共属性 |
 | Long Task | `tracking.longTask` | 关 | Long Animation Frames / Long Tasks | `browser.long_task` | 三个聚合指标 | — |
 | WebSocket | `tracking.websocket` | 关 | `WebSocket` Proxy | `websocket.connect` | 四个聚合指标 | error / close |
 | CSP | `tracking.cspViolation` | 关 | `securitypolicyviolation` | `csp.violation` | — | — |

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

@@ -38,7 +38,7 @@ const bkOT = new BkOpenTelemetry(options);
 | `environment` | `string` | `production` | `deployment.environment.name` |
 | `version` | `string` | 无 | `service.version` |
 
-SDK 还会固定写入 `rum.provider=blueking`、`rum.schema.version=1`、`telemetry.sdk.name=@blueking/open-telemetry` 和 `telemetry.sdk.language=webjs`。
+SDK 还会固定写入 `rum.schema.version=2`、`telemetry.sdk.name=@blueking/open-telemetry`、`telemetry.sdk.language=webjs` 和当前包版本 `telemetry.sdk.version`。默认启用 `tracking.device` 时，浏览器、OS 和稳定的硬件能力也会写入 Resource。
 
 ## transport
 
@@ -216,7 +216,7 @@ tracking: {
 | --- | --- | --- | --- |
 | `trackingConsent` | `'granted' \| 'not-granted'` | `granted` | 初始化授权状态 |
 | `redactUrl` | `(url) => string` | 删除 username/password/query/hash | SDK URL 属性脱敏 |
-| `redactAttributes` | `(attributes) => Attributes` | 原样返回 | SDK 创建 Span/Log 和内置插件属性脱敏 |
+| `redactAttributes` | `(attributes) => Attributes` | 原样返回 | Resource、SDK 创建的 Span/Log 和内置插件属性脱敏 |
 
 第三方 instrumentation 的自有 Span 属性不保证经过 `redactAttributes`；需要在 `tracking.beforeSend` 做最终兜底。详见[隐私与公共属性](./privacy.md)。
 

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

@@ -93,7 +93,7 @@ new BkOpenTelemetry({
 
 ## device
 
-`device` 插件写入设备、浏览器、系统、视口、网络等运行时属性。默认开启。
+`device` 插件采集设备、浏览器、系统、视口和网络信息。默认开启。
 
 ```ts
 new BkOpenTelemetry({
@@ -106,11 +106,11 @@ new BkOpenTelemetry({
 });
 ```
 
-后续 span/log 会自动带上这些属性，便于按浏览器、系统、网络类型下钻。
+稳定的浏览器、系统和硬件能力写入三类信号共享的 Resource；设备 ID、视口和网络信息保留为运行时属性，后续 span/log 会自动携带，便于按浏览器、系统、网络类型下钻。
 
 `device.id` 默认只在当前 SDK 实例内稳定；只有显式设置 `persistentId: true` 才写入 localStorage，并按应用名隔离默认 storage key。
 
-**产出遥测**：只写入运行时属性（如 `device.id`、`browser.name`、`os.name`、`device.type`、`network.effective_type`），本身不单独产生 span/metric/log。
+**产出遥测**：写入 Resource 属性（如 `browser.name`、`os.name`、`device.type`、`device.memory_gib`）和运行时属性（如 `device.id`、`browser.viewport.*`、`network.effective_type`），本身不单独产生 span/metric/log。
 
 ## View
 

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

@@ -24,7 +24,7 @@ new BkOpenTelemetry({
 
 ## 属性脱敏
 
-`privacy.redactAttributes` 会处理通过 SDK `startSpan()`、`emitLog()` 以及内置插件显式应用的属性，适合删除 authorization、手机号、邮箱等字段。
+`privacy.redactAttributes` 会处理 Resource、通过 SDK `startSpan()`、`emitLog()` 以及内置插件显式应用的属性，适合删除 authorization、手机号、邮箱等字段。Resource 在 SDK 构造时处理一次，后续不会动态更新。
 
 ```ts
 new BkOpenTelemetry({

package/skills/bk-rum-otele/references/telemetry-reference.md

@@ -9,31 +9,34 @@
 ## 命名规则
 
 - **信号名**：`browser.*` 表示内置浏览器事件（如 `browser.web_vital`）；`action.<type>`、`custom.<name>` 是运行期动态拼接；`csp.violation`、`websocket.*` 使用领域前缀。
-- **属性 key**：沿用 OpenTelemetry 语义约定的字段用点号（如 `http.request.method`、`exception.type`、`view.id`、`session.id`、`browser.name`）；跨类型检索字段使用下划线（如 `span_type`、`span_subtype`、`result`）。字段常量集中定义在 `src/schema/attributes.ts`。
+- **属性 key**：标准字段与 RUM 领域字段均使用点号命名空间（如 `http.request.method`、`exception.type`、`view.id`、`session.id`、`browser.name`）；跨类型检索字段使用下划线（如 `span_type`、`span_subtype`、`result`）。字段常量集中定义在 `src/schema/attributes.ts`。
 
-## 公共上下文属性
+## 公共 Resource 与运行时上下文属性
 
-以下属性由运行时上下文自动挂到**几乎所有** span / log 上（metric 视插件而定），后续各清单不再重复列出：
+Resource 属性由三类信号共享；运行时上下文属性自动挂到**几乎所有** span / log 上（metric 视插件而定）。后续各清单不再重复列出：
 
-| key | 类型 | 说明 | 低基数 |
-| --- | --- | --- | --- |
-| `service.name` | string | 应用名（`application.name`） | 是 |
-| `service.version` | string | 应用版本（`application.version`，可选） | 是 |
-| `deployment.environment.name` | string | 环境（`application.environment`） | 是 |
-| `rum.provider` | string | 固定 `blueking` | 是 |
-| `telemetry.sdk.language` | string | 固定 `webjs` | 是 |
-| `user.id` | string | 接入方提供，原样透传 | 否 |
-| `session.id` | string | session 插件生成/轮换 | 否 |
-| `session.has_replay` | boolean | 当前固定 `false` | 是 |
-| `view.id` | string | View 管理器生成的实例 ID | 否 |
-| `view.name` | string | 自动模式默认使用路由分组；手动模式可指定 | 是 |
-| `view.url` | string | 当前 view URL（已脱敏） | 否 |
-| `view.url_path_group` | string | 低基数路由模板 | 是 |
-| `view.loading_type` | string | `initial_load` / `route_change` / `session_renewal` / `bf_cache` | 是 |
-| `device.type` | string | `mobile` / `desktop` | 是 |
-| `browser.name` / `browser.version` | string | 浏览器信息 | 是 |
-| `os.name` | string | 操作系统 | 是 |
-| `network.effective_type` | string | 网络质量（`4g` 等） | 是 |
+| key | 归属 | 类型 | 说明 | 低基数 |
+| --- | --- | --- | --- | --- |
+| `service.name` | Resource | string | 应用名（`application.name`） | 是 |
+| `service.version` | Resource | string | 应用版本（`application.version`，可选） | 是 |
+| `deployment.environment.name` | Resource | string | 环境（`application.environment`） | 是 |
+| `rum.schema.version` | Resource | string | 当前固定 `2` | 是 |
+| `telemetry.sdk.name` / `telemetry.sdk.language` / `telemetry.sdk.version` | Resource | string | SDK 名、语言和包版本 | 是 |
+| `device.type` | Resource | string | `mobile` / `desktop` | 是 |
+| `browser.name` / `browser.version` | Resource | string | 归一化浏览器信息 | 是 |
+| `os.name` | Resource | string | 操作系统 | 是 |
+| `device.memory_gib` | Resource | number | 浏览器暴露的近似设备内存（GiB） | 是 |
+| `device.logical_processor_count` | Resource | number | 浏览器暴露的逻辑处理器数量 | 是 |
+| `user.id` | Runtime | string | 接入方提供，原样透传 | 否 |
+| `session.id` | Runtime | string | session 插件生成/轮换 | 否 |
+| `session.has_replay` | Runtime | boolean | 当前固定 `false` | 是 |
+| `view.id` | Runtime | string | View 管理器生成的实例 ID | 否 |
+| `view.name` | Runtime | string | 自动模式默认使用路由分组；手动模式可指定 | 是 |
+| `view.url` | Runtime | string | 当前 view URL（已脱敏） | 否 |
+| `view.url_path_group` | Runtime | string | 低基数路由模板 | 是 |
+| `view.loading_type` | Runtime | string | `initial_load` / `route_change` / `session_renewal` / `bf_cache` | 是 |
+| `device.id` | Runtime | string | 当前实例或持久化匿名设备 ID | 否 |
+| `network.effective_type` | Runtime | string | 网络质量（`4g` 等） | 是 |
 
 > span 还会带上 `span_type` / `span_subtype` / `result` / `error_type` 等归一字段（见下方[归一字段](#归一字段)）。接入方可通过 `context.attributes.page` 注入额外的页面属性。
 
@@ -162,13 +165,13 @@
 | key | 类型 | 说明 |
 | --- | --- | --- |
 | `device.id` | string | 匿名设备标识；默认仅当前 SDK 实例稳定，`tracking.device.persistentId=true` 时持久化 |
-| `device.memory` / `device.cpu_cores` | number | 硬件能力 |
-| `device.platform` / `device.mobile` | string/bool | UA-CH 平台信息 |
+| `device.memory_gib` | number | Resource 中的近似设备内存（GiB） |
+| `device.logical_processor_count` | number | Resource 中的逻辑处理器数量 |
 | `browser.viewport.width` / `browser.viewport.height` | number | 视口尺寸 |
 | `browser.screen.width` / `browser.screen.height` | number | 屏幕尺寸 |
 | `network.connection_type` / `network.downlink` / `network.rtt` / `network.save_data` | mixed | 网络信息 |
-| `browser.name` / `browser.version` / `os.name` | string | UA 解析结果 |
-| `device.type` | string | `mobile` / `desktop` |
+| `browser.name` / `browser.version` / `os.name` | string | Resource 中的 UA 解析结果 |
+| `device.type` | string | Resource 中的 `mobile` / `desktop` |
 
 ### 用户动作 / 会话