@blueking/open-telemetry 0.0.29 → 0.0.31

package/dist/plugins/blank-screen.d.ts

@@ -16,11 +16,9 @@ export interface BkOTBlankScreenPluginOptions {
     threshold?: number;
 }
 interface DetectionResult {
-    centerElement: string;
     emptyCount: number;
     ignoredCount: number;
     reason: 'empty_viewport' | 'missing_root';
-    rootFound: boolean;
     score: number;
     validCount: number;
 }

package/dist/plugins/device.d.ts

@@ -11,7 +11,6 @@ export declare const getDeviceResourceAttributes: () => Attributes;
  *
  * 上报字段：
  * - `device.id`：设备级永久标识，存于 localStorage（默认 key 复用旧 session 插件以保留现网用户）。
- * - `device.memory_gib`：硬件能力快照，写入 Resource。
  * - `user_agent.name` / `user_agent.version` / `user_agent.os.name`：User Agent 信息，写入 Resource。
  * - `browser.viewport.*` / `browser.screen.*`：视口与屏幕尺寸。
  * - `network.status` / `network.effective_type` / `network.connection.type`：网络信息。

package/dist/plugins/web-vitals.d.ts

@@ -38,16 +38,11 @@ interface InpCandidate {
 }
 interface LayoutShiftEntry extends PerformanceEntry {
     hadRecentInput?: boolean;
-    sources?: Array<{
-        node?: Node | null;
-    }>;
     value?: number;
 }
 interface ViewVitalState {
     cls: number;
     clsWindowEnd?: number;
-    clsWindowLargestShiftTarget?: string;
-    clsWindowLargestShiftValue: number;
     clsWindowStart?: number;
     clsWindowValue: number;
     id: string;
@@ -55,8 +50,6 @@ interface ViewVitalState {
     interactionCountAtStart?: number;
     interactionIdMax: number;
     interactionIdMin: number;
-    largestShiftTarget?: string;
-    largestShiftValue: number;
     runtimeAttributes: Attributes;
     startedAt: number;
 }

package/dist/schema/attributes.d.ts

@@ -6,24 +6,18 @@
 export declare const RUM_ATTRIBUTES: {
     readonly actionFrustrationType: "action.frustration.type";
     readonly actionId: "action.id";
-    readonly actionLoadingTime: "action.loading_time";
-    readonly actionName: "action.name";
     readonly actionTargetName: "action.target.name";
     readonly actionTargetTag: "action.target.tag";
     readonly actionType: "action.type";
     readonly deploymentEnvironmentName: "deployment.environment.name";
     readonly cacheHit: "resource.cache.hit";
-    readonly deviceMemoryGib: "device.memory_gib";
     readonly deviceType: "device.type";
     readonly longTaskBlockingDuration: "long_task.blocking_duration";
-    readonly longTaskDuration: "long_task.duration";
     readonly longTaskEntryType: "long_task.entry_type";
     readonly longTaskId: "long_task.id";
-    readonly longTaskStartTime: "long_task.start_time";
     readonly networkEffectiveType: "network.effective_type";
     readonly networkStatus: "network.status";
     readonly nextHopProtocol: "resource.protocol";
-    readonly outcomeReason: "outcome.reason";
     readonly outcomeType: "outcome.type";
     readonly serviceName: "service.name";
     readonly serviceVersion: "service.version";
@@ -31,7 +25,6 @@ export declare const RUM_ATTRIBUTES: {
     readonly sessionId: "session.id";
     readonly sessionSampleRate: "session.sample_rate";
     readonly sessionPhase: "session.phase";
-    readonly sessionStartTime: "session.start_time";
     readonly sessionType: "session.type";
     readonly spanType: "span_type";
     readonly userId: "user.id";
@@ -39,7 +32,6 @@ export declare const RUM_ATTRIBUTES: {
     readonly userAgentOsName: "user_agent.os.name";
     readonly userAgentVersion: "user_agent.version";
     readonly vitalMetric: "vital.metric";
-    readonly vitalRating: "vital.rating";
     readonly vitalValue: "vital.value";
     readonly viewDomComplete: "view.dom_complete";
     readonly viewDomContentLoaded: "view.dom_content_loaded";
@@ -52,6 +44,9 @@ export declare const RUM_ATTRIBUTES: {
     readonly viewLoadingType: "view.loading_type";
     readonly viewName: "view.name";
     readonly viewPhase: "view.phase";
+    readonly viewPrevious: "view.previous";
+    readonly viewPreviousUrlTemplate: "view.previous_url_template";
+    readonly viewReferrer: "view.referrer";
     readonly viewStartedAt: "view.started_at";
     readonly viewUrl: "view.url";
     readonly viewUrlTemplate: "view.url_template";

package/dist/schema/span.d.ts

@@ -37,7 +37,6 @@ export interface RumResourceSpanInput {
 }
 export interface RumSpanClassification {
     outcome?: RumSpanOutcome;
-    outcomeReason?: string;
     spanType: RumSpanType;
 }
 export type RumSpanOutcome = (typeof RUM_SPAN_OUTCOME)[keyof typeof RUM_SPAN_OUTCOME];
@@ -47,8 +46,7 @@ export interface RumUrlTarget {
     serverPort?: number;
 }
 export declare const getHttpOutcome: (statusCode: number | undefined) => RumSpanOutcome;
-export declare const getHttpOutcomeReason: (statusCode: number | undefined) => "network_timeout" | "http_5xx" | "http_4xx" | undefined;
 export declare const getVitalOutcome: (rating: string | undefined) => RumSpanOutcome;
 export declare const getUrlTarget: (url: string | undefined) => RumUrlTarget;
-export declare const buildRumSpanAttributes: ({ outcome, outcomeReason, spanType, }: RumSpanClassification) => Attributes;
+export declare const buildRumSpanAttributes: ({ outcome, spanType, }: RumSpanClassification) => Attributes;
 export declare const buildRumResourceSpanAttributes: ({ initiatorType, method, outcome, url, }: RumResourceSpanInput) => Attributes;

package/package.json

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

package/skills/bk-rum-otele/SKILL.md

@@ -39,7 +39,8 @@ description: 帮助业务方在前端应用里接入、使用和配置蓝鲸 RUM
 | Vue / React / Router / SSR / 微前端集成                                                     | `references/framework-integration.md` |
 | URL/属性脱敏、Consent、低基数路由、user.id 和服务端隐私责任                                  | `references/privacy.md`               |
 | 查 Transport、OTLP JSON、批量队列、重试、keepalive、Session 采样和 CORS                    | `references/transport-sampling.md`    |
-| 查具体 Span 名、OTLP Envelope、Resource/Span/Event 完整字段字典                             | `references/telemetry-reference.md`   |
+| 查前后端 RUM 语义约定、字段状态和协议映射                                                   | `references/span-protocol.md`         |
+| 查当前 SDK 实际发出的 Span、OTLP Envelope、Resource/Span/Event 完整字段字典                 | `references/telemetry-reference.md`   |
 | 没有数据、手动事件没上报、白屏误报、接口 Span 太多、字段缺失等排障                          | `references/troubleshooting.md`       |
 
 > `references/` 由 `packages/open-telemetry/scripts/gen-skill-references.mjs` 从 SDK 的 `wikis/` 自动生成，请勿手改。如内容过期，让维护者重新执行 `pnpm --filter @blueking/open-telemetry skill:refs`。

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

@@ -10,7 +10,7 @@ Action 表示一次用户操作以及操作后引发的页面活动。SDK 默认
 
 1. 从 Event 取得真实发生时间和 composed target。
 2. 生成 `action.id`，保存当时的 Session/View 上下文。
-3. 把活动中的 Action ID 写入运行时上下文，后续请求、资源、错误和 Long Task 自动关联。
+3. 把当前活动的 `action.id` 字符串写入运行时上下文，后续请求、资源、错误和 Long Task 自动关联。多个点击窗口重叠时取最近一次。
 4. 观察请求、DOM Mutation、Resource、Long Task、Error 和部分用户行为。
 5. 发生过页面活动后，等待所有请求完成并连续 100ms 无活动。
 6. 最长等待 `maxDuration`，默认 10 秒。

package/skills/bk-rum-otele/references/data-model.md

@@ -69,7 +69,9 @@ User（业务提供，可变）
 - `user.id`：业务方传入，可在 Session 内变化。
 - `session.id`：Session 插件生成，是采样和访问会话边界。
 - `view.id`：每个 View 新生成，是普通 RUM Span 的必要关联字段。
-- `action.id`：自动 Action 活动窗口内为数组，Action 自身 Span 上为当前 Action ID；手动 Action 生成独立 ID。
+- `action.id`：始终是字符串。
+  自动 Action 活动窗口内写入当前活动 Action ID，多个点击窗口重叠时取最近一次。
+  Action 自身 Span 和手动 Action 各自写入当前 Action ID。
 
 普通 Span 没有有效 Session 和 View 时不会导出。Session 生命周期 Span允许没有 View。
 

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

@@ -43,7 +43,9 @@ Fetch 和 XHR 都生成 `browser.resource`：
 | `http.response.status_code` | 获得真实 Response status 时                    | `load` 且 `xhr.status>0` 时 |
 | Span Kind                   | CLIENT                                         | CLIENT                      |
 
-`url.template` 是给后端按 API 路由聚合用的低基数维度（semconv `url.template`，当前仍是 Development 阶段）。默认取 pathname 并把数字 ID、UUID、长十六进制段折叠为 `:id`，`/api/orders/1001` 与 `/api/orders/1002` 都归到 `/api/orders/:id`。两点已知代价：纯数字段无法与语义段区分，`/reports/2024/summary` 会变成 `/reports/:id/summary`；模板按 semconv 定义不含 host，跨域同路径会聚到一起，需要区分来源时配合 `server.address`。需要精确模板时用 `tracking.request.getUrlTemplate` 覆盖，它拿到的是未脱敏 URL（便于按 query 判断路由），返回空值或抛错都回退到默认规则。
+`url.template` 是给后端按路径聚合用的低基数维度（semconv `url.template`，当前仍是 Development 阶段）。Fetch/XHR 和静态资源 Span 都取 pathname，并把数字 ID、UUID、长十六进制段折叠为 `:id`。例如，`/api/orders/1001` 与 `/api/orders/1002` 都归到 `/api/orders/:id`。
+
+需要精确模板时用 `tracking.request.getUrlTemplate` 覆盖。Fetch/XHR 会传入未脱敏 URL，便于按 query 判断路由；静态资源先通过 `redactUrl` 脱敏，再把结果传给该 Hook。返回空值或抛错都回退到默认规则。两点已知代价：纯数字段无法与语义段区分，`/reports/2024/summary` 会变成 `/reports/:id/summary`；模板按 semconv 定义不含 host，跨域同路径会聚到一起，需要区分来源时配合 `server.address`。
 
 这套折叠规则与 View 的 `view.url_template` 共用，但入口独立：页面路由和 API 路径的模板规则通常不同，所以 `tracking.view.getUrlTemplate` 与 `tracking.request.getUrlTemplate` 互不影响。
 
@@ -226,6 +228,8 @@ Fetch resolve/reject 和 XHR 终止事件往往早于 Resource Timing Observer
 
 | 字段                              | 说明                                                       |
 | --------------------------------- | ---------------------------------------------------------- |
+| `url.full`                        | 绝对 URL，经 `redactUrl` 脱敏                              |
+| `url.template`                    | 脱敏后的低基数 pathname；默认折叠数字 ID、UUID 和长十六进制段 |
 | `resource.type`                   | initiator type                                             |
 | `resource.size`                   | `decodedBodySize`（解压后 Body Size）                      |
 | `resource.encoded_body_size`      | 编码后 Body Size                                           |
@@ -306,4 +310,4 @@ Span 名统一为 `browser.websocket`，通过 `websocket.phase` 区分，不使
 
 检查 URL 是否真正命中 `allowedTracingUrls`、浏览器预检是否成功、服务端是否允许 `traceparent`，以及代理是否删除该 Header。
 
-完整字段见[遥测字段字典](./telemetry-reference.md#请求与静态资源字段)。
+完整字段见[遥测字段字典](./telemetry-reference.md#请求与静态资源字段)。产品阶段图见[RUM 语义约定 · 资源加载时序](./span-protocol.md#0x04-资源加载时序)。

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

@@ -102,7 +102,7 @@ tracking: {
 - `redactUrl`：隐私和敏感数据边界；
 - `getUrlTemplate`：聚合维度和查询基数。
 
-请求侧的 `tracking.request.getUrlTemplate` 同理，只生成 `url.template`，不影响 `url.full` 的脱敏。注意它收到的是**未脱敏**的请求 URL，因此自定义实现不要把 query 里的原值拼进返回的模板。
+请求侧的 `tracking.request.getUrlTemplate` 同理，只生成 `url.template`，不影响 `url.full` 的脱敏。Fetch/XHR 会传入**未脱敏**的请求 URL，因此自定义实现不要把 query 里的原值拼进返回的模板。静态资源先通过 `redactUrl` 脱敏，再把结果传给该 Hook，避免模板重新暴露已从 `url.full` 移除的路径信息。
 
 未配置 `context.attributes.page` 时默认返回空对象，不存在独立的默认页面属性路径。页面地址统一由经过 `redactUrl` 的 `view.url` 表达，聚合维度使用 `view.url_template`；业务通过该 Hook 添加的属性仍需自行确保不包含敏感信息。