@blueking/open-telemetry 0.0.16 → 0.0.18

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (21) hide show
  1. package/dist/bk-rum.global.js +2 -2
  2. package/dist/bk-rum.global.js.map +1 -1
  3. package/dist/core/config.d.ts +2 -0
  4. package/dist/core/metric.d.ts +2 -0
  5. package/dist/core/sdk.d.ts +4 -0
  6. package/dist/core/signal.d.ts +3 -0
  7. package/dist/core/telemetry-attributes.d.ts +1 -0
  8. package/dist/core/throttle.d.ts +2 -2
  9. package/dist/index.js +525 -456
  10. package/dist/index.js.map +1 -1
  11. package/dist/plugins/blank-screen.d.ts +4 -0
  12. package/dist/plugins/common.d.ts +1 -0
  13. package/dist/plugins/csp-violation.d.ts +1 -1
  14. package/dist/plugins/long-task.d.ts +4 -0
  15. package/dist/plugins/request-body.d.ts +2 -1
  16. package/dist/plugins/resource.d.ts +4 -0
  17. package/dist/plugins/web-vitals.d.ts +2 -0
  18. package/package.json +1 -1
  19. package/skills/bk-rum-otele/references/data-model.md +1 -1
  20. package/skills/bk-rum-otele/references/plugins.md +1 -1
  21. package/skills/bk-rum-otele/references/telemetry-reference.md +12 -10
package/dist/plugins/blank-screen.d.ts CHANGED
@@ -1,4 +1,8 @@
1
1
  import type { BkOTPlugin } from '../core/plugin';
2
+ /**
3
+ * 通过视口九宫格采样估算空白比例，并在页面稳定后连续确认两次。每个 View 最多上报一次，
4
+ * 避免首屏渲染、路由切换和 loading 状态造成瞬时误报。
5
+ */
2
6
  export interface BkOTBlankScreenPluginOptions {
3
7
  /** 页面活动稳定后首次检查的延迟，默认 1000ms。 */
4
8
  checkDelay?: number;
package/dist/plugins/common.d.ts CHANGED
@@ -4,6 +4,7 @@ import type { BkOTPlugin, BkOTRuntimeContext } from '../core/plugin';
4
4
  import type { Span } from '@opentelemetry/api';
5
5
  interface RequestDetails {
6
6
  method?: string;
7
+ startedAt?: number;
7
8
  url?: string;
8
9
  }
9
10
  export { REQUEST_DISCARD_ATTRIBUTE };
package/dist/plugins/csp-violation.d.ts CHANGED
@@ -6,7 +6,7 @@ import type { BkOTPlugin } from '../core/plugin';
6
6
  * 节流策略：
7
7
  * - 同 fingerprint（`violatedDirective + blockedURI + sourceFile + lineNumber`）
8
8
  * 在 60s 窗口内最多上报 5 条，避免风暴打爆 collector（如某段被拦截的 inline 脚本被反复渲染）。
9
- * - 每条 attribute 带 `csp.window_count`，反映当前窗口内同 fingerprint 的总触发次数（含被丢弃的）。
9
+ * - `browser.csp_violation.count` counter 在节流前累计所有违规，span 只保留窗口触发序号。
10
10
  *
11
11
  * 体积优化：
12
12
  * - `csp.original_policy`（完整 CSP 策略，可能数 KB）仅在窗口首条上报，后续同 fingerprint 不再重复携带。
package/dist/plugins/long-task.d.ts CHANGED
@@ -1,4 +1,8 @@
1
1
  import type { BkOTPlugin } from '../core/plugin';
2
+ /**
3
+ * 主线程阻塞优先使用 Long Animation Frame API 获取脚本归因，不支持时回退到 Long Tasks API；
4
+ * span 保留单次诊断详情，metric 只保留低基数维度用于聚合分布。
5
+ */
2
6
  export interface BkOTLongTaskPluginOptions {
3
7
  /** 采集阈值，默认 50ms。Performance API 本身通常只产生大于 50ms 的条目。 */
4
8
  threshold?: number;
package/dist/plugins/request-body.d.ts CHANGED
@@ -6,9 +6,10 @@ interface CaptureRequestBodyLogOptions {
6
6
  domainContext: BkOTRequestContext;
7
7
  event: BkOTRequestEvent;
8
8
  fetchRequest?: Request | RequestInit;
9
+ occurredAt?: number;
9
10
  runtimeContext: Pick<BkOTRuntimeContext, 'emitLog'>;
10
11
  span: Span;
11
12
  }
12
13
  export declare const prepareFetchRequestBodySource: (request: Request | RequestInit) => Request | RequestInit | undefined;
13
- export declare const captureRequestBodyLog: ({ bodyConfig, domainContext, event, fetchRequest, runtimeContext, span, }: CaptureRequestBodyLogOptions) => Promise<void>;
14
+ export declare const captureRequestBodyLog: ({ bodyConfig, domainContext, event, fetchRequest, occurredAt, runtimeContext, span, }: CaptureRequestBodyLogOptions) => Promise<void>;
14
15
  export {};
package/dist/plugins/resource.d.ts CHANGED
@@ -1,4 +1,8 @@
1
1
  import type { BkOTPlugin } from '../core/plugin';
2
+ /**
3
+ * Resource Timing 的统一消费端：静态资源按配置生成 span；Fetch/XHR timing 转交 request 插件，
4
+ * 与其已创建的请求 span 合并，避免同一次网络请求重复计数。
5
+ */
2
6
  type ResourceTimingWithStatus = PerformanceResourceTiming & {
3
7
  deliveryType?: string;
4
8
  renderBlockingStatus?: string;
package/dist/plugins/web-vitals.d.ts CHANGED
@@ -55,6 +55,7 @@ interface ViewVitalState {
55
55
  interactionIdMax: number;
56
56
  interactionIdMin: number;
57
57
  inpCandidates: InpCandidate[];
58
+ id: string;
58
59
  largestShiftTarget?: string;
59
60
  largestShiftValue: number;
60
61
  runtimeAttributes: Attributes;
@@ -69,6 +70,7 @@ interface InpCandidate {
69
70
  presentationDelay: number;
70
71
  processingDuration: number;
71
72
  }
73
+ export declare const isSameViewId: (currentViewId: string | undefined, nextViewId: string | undefined) => boolean;
72
74
  export declare const updateViewCls: (view: ViewVitalState, entry: LayoutShiftEntry) => void;
73
75
  export declare const updateViewInp: (view: ViewVitalState, entry: EventTimingEntry) => void;
74
76
  export declare const getViewInp: (view: ViewVitalState) => InpCandidate | undefined;
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@blueking/open-telemetry",
3
- "version": "0.0.16",
3
+ "version": "0.0.18",
4
4
  "description": "OpenTelemetry browser SDK for BK RUM",
5
5
  "author": "TencentCloud Real User Monitoring",
6
6
  "main": "dist/index.js",
package/skills/bk-rum-otele/references/data-model.md CHANGED
@@ -94,7 +94,7 @@ console.log(getDurationBucket(1200)); // 500ms~2s
94
94
  - 终端信息：`device.type`、`browser.name`、`browser.version`、`os.name`、`network.effective_type`
95
95
  - HTTP / Resource：`http.request.method`、`http.response.status_code`、`url.full`、`transfer_size`
96
96
  - Web Vitals：`vital.metric`、`vital.value`、`vital.rating`
97
- - Error：`exception.type`、`exception.message`、`exception.stacktrace`、`exception.fingerprint`
97
+ - Error Span 属性：`exception.message_short`、`exception.stack_top_frame`、`exception.fingerprint`；完整异常位于标准 `exception` Span Event
98
98
 
99
99
  ## 后端派生
100
100
 
package/skills/bk-rum-otele/references/plugins.md CHANGED
@@ -335,7 +335,7 @@ bkOT.setViewLoadingTime();
335
335
 
336
336
  插件会生成 error span，并使用 fingerprint 做窗口内节流，避免相同错误在短时间内刷屏。
337
337
 
338
- **产出遥测**：span `browser.error`（JS 错误）、`browser.unhandledrejection`（Promise 异常）、`browser.resource_error`（资源加载失败），均为 `span_type=error`，带 `exception.*`、`error.source`、`error.window_count`。
338
+ **产出遥测**：span `browser.error`（JS 错误）、`browser.unhandledrejection`（Promise 异常）、`browser.resource_error`（资源加载失败），均为 `span_type=error`，带异常摘要、`error.source`、`error.window_occurrence_index`；精确总量由 `browser.error.count` 记录。
339
339
 
340
340
  ```ts
341
341
  new BkOpenTelemetry({
package/skills/bk-rum-otele/references/telemetry-reference.md CHANGED
@@ -46,11 +46,11 @@
46
46
  | `browser.resource` | `resource` | resource 插件 | `resource.type`、`resource.url`、`resource.duration`、网络阶段、`resource.render_blocking_status`、`resource.protocol`、`resource.cache.hit` | 仅静态资源，跳过 Fetch/XHR |
47
47
  | `browser.web_vital` | `vital` | webVitals 插件 | `vital.metric`、`vital.value`、`vital.rating`、`vital.id`、`rum.navigation.type`、`vital.<lcp\|cls\|inp\|fcp\|ttfb>.*` | 每个指标一条 |
48
48
  | `browser.blank_screen` | `error` | blankScreen 插件（二次确认白屏时） | `blank_screen.empty_ratio`、`blank_screen.reason`、`blank_screen.root_selector`、`blank_screen.root_found`、`blank_screen.*_sample_count`、`blank_screen.center_element` | 每个 View 最多一条 |
49
- | `browser.error` | `error` | error 插件（`window.error`） | `exception.*`、`error.source=window.error`、`error.window_count`、`code.filepath`、`code.lineno`、`code.column`、`error.cross_origin` | |
50
- | `browser.unhandledrejection` | `error` | error 插件（Promise 异常） | `exception.*`、`error.source=unhandledrejection` | |
51
- | `browser.resource_error` | `error` | error 插件（资源加载失败） | `exception.*`、`error.source=resource`、`url.full`、`html.tag` | |
49
+ | `browser.error` | `error` | error 插件（`window.error`） | `exception.fingerprint`、`exception.message_short`、`exception.stack_top_frame`、`error.source=window.error`、`error.window_occurrence_index`、`code.filepath`、`code.lineno`、`code.column`、`error.cross_origin` | 完整异常写入标准 `exception` Span Event |
50
+ | `browser.unhandledrejection` | `error` | error 插件（Promise 异常） | `exception.fingerprint`、`error.source=unhandledrejection` | 完整异常写入标准 `exception` Span Event |
51
+ | `browser.resource_error` | `error` | error 插件（资源加载失败） | `exception.fingerprint`、`error.source=resource`、`url.full`、`html.tag` | 完整异常写入标准 `exception` Span Event |
52
52
  | `browser.long_task` | `longtask` | longTask 插件 | `long_task.id`、`long_task.entry_type`、`long_task.start_time`、`long_task.duration`、`long_task.blocking_duration`、`long_task.culprit`、`long_task.script.count`、`target_value` | LoAF 脚本详情写入 `long_task.script` Span Event |
53
- | `csp.violation` | `error` | cspViolation 插件 | `csp.blocked_uri`、`csp.violated_directive`、`csp.effective_directive`、`csp.source_file`、`csp.line_number`、`csp.status_code`、`csp.fingerprint`、`csp.window_count`、`csp.original_policy`（窗口首条） | |
53
+ | `csp.violation` | `error` | cspViolation 插件 | `csp.blocked_uri`、`csp.violated_directive`、`csp.effective_directive`、`csp.source_file`、`csp.line_number`、`csp.status_code`、`csp.fingerprint`、`csp.window_occurrence_index`、`csp.original_policy`（窗口首条） | |
54
54
  | `websocket.connect` | `custom` | websocket 插件（仅建连阶段） | `url.full`、`url.scheme`、`server.address`、`network.protocol.name=websocket`、`target_domain` | 长连接生命周期不绑定 span |
55
55
  | `action.click` / `action.custom` | `action` | action 插件 / `reportAction()` | `action.id/name/type/target.*`、`action.loading_time`、`action.frustration.*`、`action.*.count` | 自动点击或手动动作；挫败信号仅自动点击 |
56
56
  | `custom.<name>` | `custom` | `reportCustomEvent()` / 自定义插件 | `rum.custom.name`、业务自定义属性 | 带 `error` 时记录 exception、设置错误 Status/Result，`span_type` 仍为 `custom` |
@@ -63,6 +63,8 @@
63
63
  | `browser.web_vital.duration` | Histogram | `ms` | 同上（FCP/INP/LCP/TTFB 靠 `vital.metric` 区分） | webVitals |
64
64
  | `browser.view.loading_time` | Histogram | `ms` | `view.url_path_group`、`view.loading_type` | View 管理器，View 结束时记录最终值 |
65
65
  | `browser.blank_screen.count` | Counter | - | `view.url_path_group`、`blank_screen.root_selector`、`blank_screen.reason` | blankScreen |
66
+ | `browser.error.count` | Counter | - | `view.url_path_group`、`error.source`、`error.subtype` | error，span 节流前精确累计 |
67
+ | `browser.csp_violation.count` | Counter | - | `view.url_path_group`、`csp.disposition`、`csp.effective_directive` | cspViolation，span 节流前精确累计 |
66
68
  | `browser.long_task.count` | Counter | - | `view.url_path_group`、`long_task.entry_type` | longTask |
67
69
  | `browser.long_task.duration` | Histogram | `ms` | 同上 | longTask |
68
70
  | `browser.long_task.blocking_duration` | Histogram | `ms` | 同上 | longTask，仅 LoAF |
@@ -71,7 +73,7 @@
71
73
  | `browser.websocket.error.count` | Counter | - | `server.address`、`url.scheme`、`websocket.error.phase`（connect/runtime） | websocket |
72
74
  | `browser.websocket.connect.duration` | Histogram | `ms` | `server.address`、`url.scheme` | websocket，仅成功建连 |
73
75
 
74
- > 各 metric 只会合并 `context.attributes.metric` hook 返回的自定义低基数维度，不会合并 `context.attributes.page`，也不会携带 `session.id`、`view.id` 或 `action.id`。精确 View 关联请查询对应 span 或 View Snapshot Log。**metric 维度务必保持低基数**，不要把 URL、订单号、用户输入等放进来。
76
+ > 各 metric 只会合并 `context.attributes.metric` hook 返回的自定义低基数维度，不会合并 `context.attributes.page`，也不会携带 `session.id`、`view.id` 或 `action.id`。`view.url_path_group` 中明显的数字 ID、UUID、长十六进制段会归一为 `:id`。精确 View 关联请查询对应 span 或 View Snapshot Log。**metric 维度务必保持低基数**，不要把 URL、订单号、用户输入等放进来。
75
77
 
76
78
  ## Log 事件清单
77
79
 
@@ -80,8 +82,8 @@
80
82
  | `session.start` | INFO | session 插件（首次新建） | `session.id`、`session.start_time`、`session.rotate.reason=init` |
81
83
  | `session.rotate` | INFO | session 插件（轮换） | + `session.previous_id`、`session.rotate.reason`（`inactivity` / `maxLifetime`） |
82
84
  | `browser.view` | INFO | View 管理器 | `view.snapshot.type=create\|update\|final`、`view.document_version`、`view.duration`、`view.is_active`、`view.loading_time` |
83
- | `browser.request.body` | ERROR（错误请求）/ INFO（`capture: 'all'` 的成功请求） | Fetch/XHR request patch（仅显式配置 `request.body`） | `trace.id`、`span.id`、`request.body` / `response.body`、`*.body.content_type`、`*.body.truncated` |
84
- | `websocket.error` | ERROR | websocket 插件 | `url.full`、`websocket.error.phase`、`websocket.error.window_count` |
85
+ | `browser.request.body` | ERROR（错误请求）/ INFO（`capture: 'all'` 的成功请求） | Fetch/XHR request patch（仅显式配置 `request.body`） | 通过 OTel Log Context 关联 Trace/Span；属性含 `request.body` / `response.body`、`*.body.content_type`、`*.body.truncated` |
86
+ | `websocket.error` | ERROR | websocket 插件 | `url.full`、`websocket.error.phase`、`websocket.error.window_occurrence_index` |
85
87
  | `websocket.close` | INFO | websocket 插件 | `websocket.close.code`、`websocket.close.reason`、`websocket.close.was_clean` |
86
88
 
87
89
  > 错误主数据统一走 `error` span（见 Span 清单），SDK **不再**为同一个错误额外 emit error log，避免重复计数。
@@ -162,7 +164,7 @@
162
164
  | `exception.fingerprint` | string | 节流分组指纹（djb2 hash） |
163
165
  | `error.source` | string | `window.error`/`unhandledrejection`/`resource`/`csp` |
164
166
  | `error.handled` | boolean | 是否被业务捕获（自动采集恒为 `false`） |
165
- | `error.window_count` | number | 当前节流窗口内同指纹总触发次数 |
167
+ | `error.window_occurrence_index` | number | 当前节流窗口内该已上报 span 的触发序号；总量查询 `browser.error.count` |
166
168
  | `error.cross_origin` | boolean | 跨域脚本错误（`Script error.`） |
167
169
  | `code.filepath` / `code.lineno` / `code.column` | string/number | JS 错误位置 |
168
170
  | `html.tag` | string | 资源错误的元素标签 |
@@ -223,7 +225,7 @@
223
225
  | `csp.source_file` | string | 触发脚本（已脱敏） |
224
226
  | `csp.line_number` / `csp.column_number` | number | 位置 |
225
227
  | `csp.status_code` | number | 状态码 |
226
- | `csp.fingerprint` / `csp.window_count` | string/number | 节流指纹与窗口内触发次数 |
228
+ | `csp.fingerprint` / `csp.window_occurrence_index` | string/number | 节流指纹与该已上报 span 的窗口触发序号 |
227
229
  | `csp.original_policy` | string | 完整策略，仅窗口首条携带 |
228
230
 
229
231
  ### WebSocket
@@ -235,7 +237,7 @@
235
237
  | `network.protocol.name` | string | 固定 `websocket` |
236
238
  | `websocket.direction` | string | `in` / `out`（仅 metric） |
237
239
  | `websocket.error.phase` | string | `connect` / `runtime` |
238
- | `websocket.error.window_count` | number | 错误日志节流窗口内触发次数 |
240
+ | `websocket.error.window_occurrence_index` | number | 该已上报错误日志在节流窗口内的触发序号；总量查询 `browser.websocket.error.count` |
239
241
  | `websocket.close.code` / `websocket.close.reason` / `websocket.close.was_clean` | mixed | 关闭事件详情 |
240
242
 
241
243
  ### 白屏