@blueking/open-telemetry 0.0.26 → 0.0.27

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blueking/open-telemetry",
-  "version": "0.0.26",
+  "version": "0.0.27",
   "description": "OpenTelemetry browser SDK for BK RUM",
   "author": "TencentCloud Real User Monitoring",
   "main": "dist/index.js",
@@ -23,7 +23,7 @@
     "docs:preview": "vitepress preview wikis",
     "dev": "vite dev",
     "dts": "vue-tsc --project tsconfig.dts.json",
-    "test:rum-context": "node --experimental-default-type=module --experimental-strip-types --test tests/action-plugin.test.mjs tests/consent.test.mjs tests/experience-plugins.test.mjs tests/request-model.test.mjs tests/runtime-context.test.mjs tests/sampling.test.mjs tests/session-state.test.ts tests/session-plugin.test.mjs tests/session-page-view.test.mjs tests/session-processors.test.mjs tests/web-vitals.test.mjs"
+    "test:rum-context": "node --experimental-default-type=module --experimental-strip-types --test tests/action-plugin.test.mjs tests/consent.test.mjs tests/experience-plugins.test.mjs tests/request-model.test.mjs tests/runtime-context.test.mjs tests/sampling.test.mjs tests/session-state.test.ts tests/session-plugin.test.mjs tests/session-page-view.test.mjs tests/session-processors.test.mjs tests/trace-context.test.mjs tests/web-vitals.test.mjs"
   },
   "dependencies": {
     "@opentelemetry/api": "^1.9.1",

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

@@ -24,7 +24,7 @@ SDK 只产生原始 RUM Span：
 | View / Router | `tracking.view` | auto | Navigation Timing、History、hash、BFCache | `browser.view` | [View 与路由](./views-routing.md) |
 | View Loading Time | `tracking.view.loadingTime` | 开 | 请求/资源/DOM/`window.open` 活动 | `browser.view` update | [View 与路由](./views-routing.md) |
 | Fetch/XHR | `tracking.request` | 开 | fetch、XMLHttpRequest、Resource Timing | `browser.resource` CLIENT | [网络](./network.md) |
-| Trace Header | `allowedTracingUrls` | 无白名单 | W3C Trace Context | 被观测请求的 `traceparent` | [网络](./network.md) |
+| Trace Header | `allowedTracingUrls` | 无白名单 | W3C Trace Context | 被观测请求的 `traceparent` + `browser.resource` Span Link | [网络](./network.md) |
 | 静态资源 | `tracking.resource` | 开 | Resource PerformanceObserver | `browser.resource` CLIENT | [网络](./network.md) |
 | JS Error | `tracking.error` | 开 | window error | `browser.error` | [错误与安全](./errors-security.md) |
 | Promise rejection | `tracking.error` | 开 | unhandledrejection | `browser.unhandledrejection` | [错误与安全](./errors-security.md) |
@@ -101,7 +101,7 @@ Fetch/XHR 插件统一负责：
 
 - 建 `browser.resource` CLIENT Span；
 - 请求结果和 HTTP status；
-- 可选 W3C `traceparent`；
+- 可选 W3C `traceparent`：为每个白名单请求生成独立 trace context，并用 Span Link 关联，Link Attributes 记录命中格式与原始 Header；业务已有 trace Header 时不注入；
 - 与 Resource Timing 在最多 200ms 内匹配；
 - 向 View/Action activity 通知开始与结束。
 

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

@@ -161,7 +161,7 @@ tracking: {
 | 配置 | 默认 | 说明 |
 | --- | --- | --- |
 | `excludedUrls` | 无 | 匹配后不建请求 Span、不注入 trace header，也不计入 View/Action 活动 |
-| `allowedTracingUrls` | 无 | 只有明确匹配的 URL 才注入 W3C `traceparent`，同源也不例外 |
+| `allowedTracingUrls` | 无 | 只有明确匹配的 URL 才注入 W3C `traceparent`，同源也不例外；注入的是独立 trace context，并通过 Span Link 关联回 RUM Span。业务已自行设置 trace Header 时不注入 |
 | `beforeSend` | 无 | 只作用于 Fetch/XHR 请求事件；`event.resource.outcome` 区分 response/abort/timeout/network_error，返回 `false` 丢弃请求 Span |
 
 URL matcher 支持 string、RegExp 或函数：

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

@@ -20,12 +20,13 @@ SDK 不采集任何请求 Body、响应 Body、WebSocket 消息内容、消息
 
 1. 把 URL 转成绝对 URL。
 2. 排除 SDK 自身上报和 `excludedUrls`。
-3. 创建 `browser.resource` CLIENT Span。
-4. 按白名单决定是否注入 `traceparent`。
-5. 把请求开始/结束通知给 View/Action 页面活动。
-6. 根据 Response 或终止原因生成结构化 outcome，并补充结果、异常和 Resource Timing。
-7. 执行请求级 `beforeSend`。
-8. 结束 Span，并进入全局过滤链路。
+3. 按白名单探测既有 Trace Header，规划本次请求的 trace context。
+4. 创建 `browser.resource` CLIENT Span，并把关联后端 Trace 的 Span Link 一并写入。
+5. 需要时注入 `traceparent`。
+6. 把请求开始/结束通知给 View/Action 页面活动。
+7. 根据 Response 或终止原因生成结构化 outcome，并补充结果、异常和 Resource Timing。
+8. 执行请求级 `beforeSend`。
+9. 结束 Span，并进入全局过滤链路。
 
 Patch 在插件 shutdown 时仅在全局方法仍是 SDK 安装版本的情况下恢复，避免覆盖 SDK 之后由业务安装的其他 Patch。
 
@@ -82,7 +83,7 @@ Matcher 规则：
 
 ## W3C Trace Context
 
-默认不向任何请求注入 Trace Header，包括同源请求。只有 `allowedTracingUrls` 显式命中时才使用 `W3CTraceContextPropagator` 注入 `traceparent`：
+默认不向任何请求注入 Trace Header，包括同源请求。只有 `allowedTracingUrls` 显式命中时才注入：
 
 ```ts
 tracking: {
@@ -94,9 +95,11 @@ tracking: {
 }
 ```
 
-Fetch 会合并 `init.headers` 或输入 Request 的 Headers；XHR 使用 `setRequestHeader()`。白名单应使用 URL-aware 函数或有边界的正则，不要用过宽字符串。
+白名单应使用 URL-aware 函数或有边界的正则，不要用过宽字符串。
 
-当前请求 Span 命中 Session 采样后，注入值采用 W3C Trace Context v00：
+### 每个请求一条独立后端 Trace
+
+注入的 `traceparent` **不复用** RUM Span 自身的 trace context，而是为每个命中白名单的请求生成一对全新的 trace-id / span-id：
 
 ```text
 traceparent: 00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01
@@ -104,22 +107,59 @@ traceparent: 00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01
              └ version=00                       parent-id：16 位 ─────┘  sampled=01
 ```
 
-这里的 `parent-id` 是本次 Fetch/XHR CLIENT Span 的 `spanId`。请求 Patch 只在当前 Session 已采样时创建并注入记录型 Span，因此当前实现发出的 flags 为 `01`。如果活动父上下文带有 `traceState`，传播器还会写 `tracestate`；SDK 自身不创建 `tracestate`。
+这样后端按 trace-id 检索时，一条 Trace 只对应一个 API 请求，也不会把前端的 `browser.resource` Span 混进后端链路。前后端的关联改由 **Span Link** 承担，后端可按 `link.trace_id` 反查对应的 RUM Span。
+
+每个命中白名单的请求恒定产出**一条** Link，结构固定为 trace context 加上记录来源的 `attributes`：
+
+```json
+{
+  "links": [
+    {
+      "trace_id": "4bf92f3577b34da6a3ce929d0e0e4736",
+      "span_id": "00f067aa0ba902b7",
+      "attributes": {
+        "format": "traceparent",
+        "traceparent": "00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01"
+      }
+    }
+  ]
+}
+```
+
+`attributes.format` 是命中的传播格式，其余键是该格式的**原始 Header 名与原始取值**（不做补零或进制转换），例如 Datadog 会带上 `x-datadog-trace-id`、`x-datadog-parent-id`、`x-datadog-sampling-priority` 等。这些 Link Attributes 不经过 `privacy.redactAttributes` 脱敏。
+
+请求 Patch 只在当前 Session 已采样时创建 Span 并注入，因此发出的 flags 恒为 `01`。注入的 span-id 在前端没有对应的已上报 Span，后端 Trace 的根 Span 会以它作为 `parent_span_id`。
+
+### 业务已有 Trace Header 时不注入
+
+注入前 SDK 会先读取本次请求最终会发出的 Header，按下列优先级探测业务是否已经自行传播链路：
+
+| 优先级 | `format` | Header | 能否解析出合法 OTel id |
+| --- | --- | --- | --- |
+| 1 | `traceparent` | `traceparent`（连带记录 `tracestate`） | 能 |
+| 2 | `sentry-trace` | `sentry-trace` | 能 |
+| 3 | `b3` | `b3`（单头） | 能，64 位 trace-id 左侧补零到 128 位 |
+| 4 | `b3-multi` | `x-b3-traceid` / `x-b3-spanid` / `x-b3-parentspanid` / `x-b3-sampled` / `x-b3-flags` | 同上 |
+| 5 | `datadog` | `x-datadog-trace-id` / `x-datadog-parent-id` / `x-datadog-sampling-priority` / `x-datadog-origin` / `x-datadog-tags` | 能，十进制换算为 hex，128 位时从 `x-datadog-tags` 的 `_dd.p.tid` 拼接高位 |
+| 6 | `sw8` | `sw8` | **不能**，SkyWalking 的 trace-id 不是 16 字节 hex |
+
+一旦探测到上表任一 Header，SDK **完全不注入**，只把命中格式的原始 Header 写进 Link Attributes。只记录命中格式自己的 Header——若 `traceparent` 与 `b3` 同时存在，按优先级只记录前者。
 
-已有 Header 的处理取决于浏览器 API：
+几点需要注意：
 
-- Fetch 使用 `Headers.set()`，会覆盖 Headers 中已有的 `traceparent` / `tracestate`；
-- XHR 在 `send()` 前调用 `setRequestHeader()`，浏览器可能把业务先设置的同名值追加合并，形成无效 Trace Context；不要由业务再手工设置同名 Header；
-- SDK 不先解析入站 Header 再决定是否保留，`allowedTracingUrls` 命中即按当前活动 SpanContext 注入。
+- `traceparent` 与 SDK 注入的是同一个 Header，因此**格式非法时视作没有既有链路并覆盖注入**——这种值后端同样无法接续。其余格式只要 Header 存在就一律尊重。
+- 解析不出合法 id 时（`sw8`、或 `b3: 0` 这类只有采样标记的值），SDK 会补一对随机 id 让 Link 结构保持统一，但**不会注入**。这对占位 id 在后端不存在对应 Trace，只有 `attributes` 里的原始 Header 有排查价值。
+- 后端只解析 W3C `traceparent`。如果业务发的是 `b3` / `sw8` / Datadog 这类格式，SDK 不注入意味着后端不会生成 Trace，Link 中的 trace-id 在后端查不到。
+- Fetch 读取的是 `init.headers`，缺省时回退到输入 `Request` 的 Headers；XHR 因为浏览器不提供读取请求头的 API，SDK 会额外 Patch `setRequestHeader()` 做快照，这层 Patch 仅在配置了 `allowedTracingUrls` 时安装，`open()` 时快照同步失效。
 
 跨域注入会触发 CORS 预检，服务端至少需要允许：
 
 ```http
 Access-Control-Allow-Origin: https://your-web.example.com
-Access-Control-Allow-Headers: traceparent, tracestate
+Access-Control-Allow-Headers: traceparent
 ```
 
-若你的链路从不携带 `tracestate`，可以只允许 `traceparent`；如业务还有自定义 Header，应一并加入允许列表。
+如业务还有自定义 Header 或自有的 trace Header，应一并加入允许列表。
 
 ## 请求级 beforeSend
 

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

@@ -159,6 +159,8 @@ allowedTracingUrls: [
 
 不要使用宽泛 `/./` 或所有 URL，避免向第三方发送 Trace ID，也避免触发额外预检。API 端必须允许 `traceparent` header，并正确接续 W3C Trace Context。
 
+每个命中白名单的请求都会生成一条独立的后端 Trace，因此后端 Trace 数量约等于被注入的请求数。评估后端存储与采样容量时按这个量级估算，必要时在服务端做二次采样。
+
 ## 7. 排除长活动与噪声
 
 两类配置语义不同：

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

@@ -50,9 +50,10 @@
 
 | OTLP 字段           | 类型/格式           | 条件             | 详细说明                                                                                                                                                                                                                      |
 | ------------------- | ------------------- | ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `traceId`           | 32 位十六进制字符串 | 必有             | 16 字节 Trace ID。同一条调用链上的 Span 使用同一个值，可用于串联用户操作、前端请求和已传播 Trace Context 的后端链路。                                                                                                         |
+| `traceId`           | 32 位十六进制字符串 | 必有             | 16 字节 Trace ID。同一条调用链上的 Span 使用同一个值。注意注入到后端的 `traceparent` 使用的是另一个独立 trace-id，不等于本字段，两者通过 `links` 关联。                                                                        |
 | `spanId`            | 16 位十六进制字符串 | 必有             | 当前 Span 的 8 字节唯一 ID，与 `traceId` 一起唯一定位本次 Span。                                                                                                                                                              |
 | `parentSpanId`      | 16 位十六进制字符串 | 有活动父 Span 时 | 父 Span ID。没有活动父上下文的 RUM 根 Span不包含该字段；缺失不代表数据异常。                                                                                                                                                  |
+| `links`             | link[]              | 注入或探测到 Trace Header 时 | 关联的其他 Trace。`browser.resource` Span 用它指向本次请求对应的后端 Trace，每项含 `traceId`、`spanId`、`traceFlags`。后端可按 `link.trace_id` 反查 RUM Span。                                            |
 | `name`              | string              | 必有             | Span 名称，例如 `browser.view`、`browser.resource`。稳定一级分类使用 `span_type`，具体类别使用各领域字段查询。                                                                                                                |
 | `kind`              | enum number/string  | 必有             | OpenTelemetry Span Kind。SDK 内置值为 `INTERNAL` 或 `CLIENT`；不同 OTLP JSON 实现可能编码为枚举数字或名称。                                                                                                                   |
 | `startTimeUnixNano` | epoch ns 字符串     | 必有             | Span 开始时间。OTLP JSON 使用十进制字符串保存纳秒整数，避免 JavaScript Number 精度丢失。                                                                                                                                      |
@@ -203,6 +204,15 @@ Session Span 允许没有 `view.id`：SDK 先建立 Session，再创建初始 Vi
 | `resource.decoded_body_size`      | number  | 有 Resource Timing                | 解码/解压后的响应体大小，单位 bytes，可与 encoded size 对比压缩收益。                                                                           |
 | `resource.transfer_size`          | number  | 有 Resource Timing                | `transferSize`，本次网络实际传输字节数（含响应头）；受缓存和 Timing-Allow-Origin 影响可能为 `0`，可与 body size 对比判断是否命中缓存。          |
 
+命中 `allowedTracingUrls` 的请求还会带一条 Span Link，用于关联后端 Trace。Trace 来源不记在 Span Attributes 上，而是记在 Link Attributes 上：
+
+| 字段        | 类型   | 条件           | 说明                                                                                                                                     |
+| ----------- | ------ | -------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
+| `format`    | string | 恒有           | 命中的传播格式，取值为 `traceparent`、`sentry-trace`、`b3`、`b3-multi`、`datadog`、`sw8`。为 `traceparent` 且 Link 的 trace-id 由 SDK 生成时，表示是 SDK 注入的。 |
+| Header 原名 | string | 该 Header 存在 | 命中格式的原始 Header 名与原始取值，未做补零或进制转换，例如 `traceparent`、`b3`、`x-datadog-trace-id`、`sw8`。仅记录命中格式自己的 Header。 |
+
+Link 的 `trace_id` / `span_id` 优先取自解析结果；`sw8` 这类无法映射为合法 OTel id 的格式会补一对随机占位 id，此时后端不存在对应 Trace。Link Attributes 不经过 `privacy.redactAttributes` 脱敏。
+
 网络阶段字段均为 number、单位 ms。每个 `*.start` 相对该 Resource Entry 的 `startTime`，每个 `*.duration` 为对应阶段结束值减开始值：
 
 | 字段                           | 条件                                   | 计算口径与使用方式                                                                               |

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

@@ -277,6 +277,16 @@ tracking: {
 
 跨域还需要服务端 CORS 允许请求头 `traceparent`。如果预检失败，缩小白名单并修复 API 服务的 CORS；不要把所有第三方 URL 加入白名单。
 
+命中白名单却依然没有注入时，看 Span Link 的 `attributes.format`。只要它不是 SDK 自己生成的 `traceparent`，就说明业务已经设置了 trace Header（`sentry-trace`、`b3`、Datadog、`sw8`，或业务自己的 `traceparent`），SDK 会尊重既有链路而不注入，只把原始 Header 记进 Link Attributes。
+
+## 后端按 `traceparent` 的 trace-id 查不到 RUM Span
+
+注入的 trace-id 与 RUM Span 自身的 `traceId` **不是同一个值**，两者通过 Span Link 关联。后端应按 `browser.resource` Span 的 `link.trace_id` 反查，而不是直接用 `traceId` 匹配。
+
+如果 Link 的 `attributes.format` 不是 `traceparent`，说明业务用的是 `b3` / `sw8` / Datadog 等格式。后端只解析 W3C `traceparent`，这种情况下后端不会生成 Trace，Link 里的 trace-id 自然查不到。
+
+`sw8` 以及 `b3: 0` 这类只有采样标记的值，SDK 解析不出合法 OTel id，会补一对**随机占位 id** 让 Link 结构保持统一。这对 id 在后端一定查不到，判断依据仍是 `attributes.format` 与其中的原始 Header。
+
 ## 请求 Span 太多或 View loading 一直不结束
 
 使用两个不同的排除入口：