@blueking/open-telemetry 0.0.27 → 0.0.29

package/dist/schema/attributes.d.ts

@@ -54,7 +54,7 @@ export declare const RUM_ATTRIBUTES: {
     readonly viewPhase: "view.phase";
     readonly viewStartedAt: "view.started_at";
     readonly viewUrl: "view.url";
-    readonly viewUrlPathGroup: "view.url_path_group";
+    readonly viewUrlTemplate: "view.url_template";
     readonly viewVersion: "view.version";
     readonly websocketPhase: "websocket.phase";
 };

package/package.json

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

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

@@ -114,6 +114,6 @@ View Loading Time 默认开启；默认关闭、按需打开：`longTask`、`csp
 - **隐私要业务显式配置**：SDK 不猜哪些字段敏感，URL、属性需通过 `privacy` / `request.beforeSend` 显式处理；SDK 不采集 HTTP Body；`user.id` 需 hash 的话要在传入前处理。`tracking.beforeSend` 新写入的字段不会再次自动经过 `redactAttributes`。
 - **Consent**：未授权初始化时配置 `privacy.trackingConsent: 'not-granted'`，用户授权后调用 `setTrackingConsent('granted')`；撤销授权会停止采集并解除 patch。该配置不会阻止构造阶段读取 Device Resource 快照；要求授权前零读取时必须延迟构造 SDK。
 - **单一信号**：只有 `/v1/rum` Trace 通道；计数、直方图、分位数、错误指纹和跨事件聚合由服务端完成。
-- **低基数路由**：用 `tracking.view.getPathGroup` 把 `/user/123` 归类成 `/user/:id`，避免高基数 URL 污染指标维度。
+- **低基数路由**：`tracking.view.getUrlTemplate` 与 `tracking.request.getUrlTemplate` 分别把页面路由和请求路径归类成 `/user/:id`，避免高基数 URL 污染指标维度。默认已按形状折叠数字 ID、UUID 和长十六进制段。
 - **手动 View 的时机**：使用 `autoStart: false`，先 `await start()` 建立 Session，再调用 `startView()`；启动前调用会因没有有效采样 Session 而被忽略。
 - **Action 命名隐私**：默认 `nameCollection: 'explicit'` 只读取 `data-bk-action-name`，否则退回标签名；只有显式设为 `text` 才读取可访问名称和 DOM 文本。

package/skills/bk-rum-otele/evals/evals.json

@@ -5,7 +5,7 @@
       "id": 0,
       "name": "vue3-integration",
       "prompt": "我们是一个 Vue3 + vue-router 的后台管理系统，想接入蓝鲸 RUM 做前端监控。collector 地址是 https://rum.example.com，token 放在 window.__RUM_TOKEN__。帮我写接入代码：要能追踪 SPA 路由切换、检测白屏（挂载点 #app），生产环境按 20% 采样，并且把 URL 里的 token 参数脱敏。",
-      "expected_output": "给出使用 @blueking/open-telemetry 的 BkOpenTelemetry 接入代码：application/transport(endpoint+token)、session.sampleRate=0.2、tracking.blankScreen.rootSelector='#app'、privacy.redactUrl 脱敏 token、通过 tracking.view.getPathGroup 自动追踪或 manual + await start() + startView() 对接 vue-router。API/配置项名称需与 SDK 实际一致。",
+      "expected_output": "给出使用 @blueking/open-telemetry 的 BkOpenTelemetry 接入代码：application/transport(endpoint+token)、session.sampleRate=0.2、tracking.blankScreen.rootSelector='#app'、privacy.redactUrl 脱敏 token、通过 tracking.view.getUrlTemplate 自动追踪或 manual + await start() + startView() 对接 vue-router。API/配置项名称需与 SDK 实际一致。",
       "files": [],
       "assertions": []
     },

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

@@ -142,7 +142,7 @@ rum.startView({ name: '订单详情' });
 rum.setViewName('订单详情');
 ```
 
-没有采样 Session 时调用被忽略。
+没有采样 Session 时调用被忽略。`view.name` 只在显式命名后才上报，未调用时该字段不存在，聚合请按 `view.url_template`。
 
 ### `setViewLoadingTime(): void`
 

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

@@ -108,7 +108,7 @@ SDK 只创建 OpenTelemetry Trace Provider。Session、View、请求、资源、
 
 - `user.id`
 - `session.id`、`session.start_time`、`session.type`、`session.has_replay`
-- `view.id`、`view.name`、`view.url`、`view.url_path_group`、`view.loading_type`
+- `view.id`、`view.url`、`view.url_template`、`view.loading_type`，以及显式命名后才出现的 `view.name`
 - 活动窗口内的 `action.id`
 - Device 插件产生的视口、屏幕、网络和设备 ID
 - View 自定义属性

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

@@ -93,7 +93,7 @@ View 类型：
 
 每个 View 产生 start/update/end 生命周期 Span，`view.version` 递增。Loading Time 等待页面活动安静后更新；隐藏页面会取消当前自动计算，业务可用 `setViewLoadingTime()` 手动确认。
 
-自动 mode 不因 query-only 改变创建 View。默认 path group 只是 pathname，不会自动模板化动态 ID。
+自动 mode 不因 query-only 改变创建 View。默认 `view.url_template` 会把数字 ID、UUID 和长十六进制段折叠为 `:id`，但只按形状猜，非数字动态段需要用 `getUrlTemplate` 显式提供。
 
 ## 网络与资源
 

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

@@ -110,7 +110,7 @@ context: {
 
 Hook 每次调用都应返回新的普通对象，且不能抛异常。SDK 不 hash、不改写 `user.id`。如果 ID 敏感，接入方必须在传入前完成不可逆处理。
 
-未配置 `attributes.page` 时默认返回空对象。页面地址由 `view.url` 表达，低基数路由由 `view.url_path_group` 表达；该 Hook 只用于补充业务自定义的页面维度。
+未配置 `attributes.page` 时默认返回空对象。页面地址由 `view.url` 表达，低基数路由由 `view.url_template` 表达；该 Hook 只用于补充业务自定义的页面维度。
 
 属性合并优先级不是全局统一的：各插件会先组合公共字段、Hook 字段和事件字段，`startSpan()` 再用运行时上下文作为底层。精确字段请以对应能力页和[RUM 数据模型](./data-model.md)为准。
 
@@ -163,6 +163,7 @@ tracking: {
 | `excludedUrls` | 无 | 匹配后不建请求 Span、不注入 trace header，也不计入 View/Action 活动 |
 | `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 |
+| `getUrlTemplate` | 折叠动态段后的 pathname | 生成低基数 `url.template`，例如 `/api/orders/:id`。收到的是未脱敏 URL，返回空值或抛错时回退到默认规则 |
 
 URL matcher 支持 string、RegExp 或函数：
 
@@ -179,10 +180,10 @@ URL matcher 支持 string、RegExp 或函数：
 | --- | --- | --- | --- |
 | `tracking` | `'auto' \| 'manual'` | `'auto'` | 自动监听 History/hash，或只接受 `startView()` |
 | `loadingTime` | `boolean` | `true` | 自动计算初始加载和路由稳定耗时 |
-| `getPathGroup` | `(url) => string \| undefined` | URL pathname | 生成低基数 `view.url_path_group` |
+| `getUrlTemplate` | `(url) => string \| undefined` | 折叠动态段后的 pathname | 生成低基数 `view.url_template` |
 | `excludedActivityUrls` | URL matcher | 无 | 不让长轮询/流式/埋点请求延长 View loading time |
 
-`getPathGroup` 返回 `undefined` 时回退到 pathname。自动路由不会因 query-only 变化创建新 View；hash 变化会创建，但纯锚点语义由业务自行决定是否改用 manual。详见[View、路由与页面加载](./views-routing.md)。
+`getUrlTemplate` 返回 `undefined` 或抛错时回退到默认规则：取 pathname 并把数字 ID、UUID、长十六进制段折叠为 `:id`。它与 `tracking.request.getUrlTemplate` 共用这套默认折叠，但两者是独立入口——页面路由与 API 路径的模板规则通常不同。自动路由不会因 query-only 变化创建新 View；hash 变化会创建，但纯锚点语义由业务自行决定是否改用 manual。详见[View、路由与页面加载](./views-routing.md)。
 
 ## action
 
@@ -280,7 +281,7 @@ const rum = new BkOpenTelemetry({
   session: { sampleRate: 0.2 },
   tracking: {
     view: {
-      getPathGroup(url) {
+      getUrlTemplate(url) {
         return new URL(url, location.href).pathname.replace(/\/orders\/[^/]+/, '/orders/:id');
       },
       excludedActivityUrls: [/\/events\/stream(?:\?|$)/],

package/skills/bk-rum-otele/references/framework-integration.md

@@ -14,7 +14,7 @@ SDK 不绑定 Vue、React 或具体 Router。框架集成主要解决四件事
 tracking: {
   view: {
     tracking: 'auto',
-    getPathGroup: groupRoute,
+    getUrlTemplate: groupRoute,
   },
 }
 ```
@@ -73,7 +73,7 @@ export const rum = new BkOpenTelemetry({
   transport: { endpoint: window.__RUM_ENDPOINT__ },
   tracking: {
     view: {
-      getPathGroup(rawUrl) {
+      getUrlTemplate(rawUrl) {
         const path = new URL(rawUrl, location.href).pathname;
         return routeGroups.find(item => item.pattern.test(path))?.group ?? path;
       },
@@ -98,7 +98,7 @@ export const rum = new BkOpenTelemetry({
   tracking: {
     view: {
       tracking: 'manual',
-      getPathGroup(rawUrl) {
+      getUrlTemplate(rawUrl) {
         const path = new URL(rawUrl, location.href).pathname;
         return path.replace(/\/orders\/[^/]+/, '/orders/:id');
       },
@@ -154,7 +154,7 @@ export const rum = new BkOpenTelemetry({
   transport: { endpoint: window.__RUM_ENDPOINT__ },
   tracking: {
     view: {
-      getPathGroup(rawUrl) {
+      getUrlTemplate(rawUrl) {
         return new URL(rawUrl, location.href).pathname.replace(/\/orders\/[^/]+/, '/orders/:id');
       },
     },
@@ -196,7 +196,7 @@ export const rum = new BkOpenTelemetry({
   tracking: {
     view: {
       tracking: 'manual',
-      getPathGroup: rawUrl =>
+      getUrlTemplate: rawUrl =>
         new URL(rawUrl, location.href).pathname.replace(/\/orders\/[^/]+/, '/orders/:id'),
     },
     blankScreen: { rootSelector: '#root' },
@@ -275,10 +275,10 @@ export const router = createBrowserRouter([
 
 ## Hash Router
 
-自动模式会观察 hash。默认 URL 清洗会移除 hash，所以 `view.url` 看不到 hash 内容，但 `getPathGroup(rawUrl)` 仍可在清洗前解析它：
+自动模式会观察 hash。默认 URL 清洗会移除 hash，所以 `view.url` 看不到 hash 内容，但 `getUrlTemplate(rawUrl)` 仍可在清洗前解析它：
 
 ```ts
-getPathGroup(rawUrl) {
+getUrlTemplate(rawUrl) {
   const url = new URL(rawUrl, location.href);
   const hashPath = url.hash.replace(/^#/, '').split('?')[0] || '/';
   return hashPath.replace(/\/orders\/[^/]+/, '/orders/:id');

package/skills/bk-rum-otele/references/getting-started.md

@@ -111,12 +111,12 @@ session: {
 
 ## 6. 治理动态路由
 
-默认 `view.url_path_group` 是 pathname，因此 `/orders/1001` 与 `/orders/1002` 仍是两个分组。生产环境应模板化动态段：
+默认规则会把 pathname 里的数字 ID、UUID 和长十六进制段折叠为 `:id`，因此 `/orders/1001` 与 `/orders/1002` 会归到同一个 `/orders/:id`。代价是纯数字段无法与语义段区分，`/reports/2024/summary` 也会变成 `/reports/:id/summary`。需要精确模板时自行覆盖：
 
 ```ts
 tracking: {
   view: {
-    getPathGroup(rawUrl) {
+    getUrlTemplate(rawUrl) {
       const path = new URL(rawUrl, location.href).pathname;
       return path
         .replace(/\/orders\/[^/]+/g, '/orders/:id')

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

@@ -39,9 +39,14 @@ Fetch 和 XHR 都生成 `browser.resource`：
 | `resource.type`             | `fetch`                                        | `xhr`                       |
 | `http.request.method`       | `init.method`、Request method 或 `GET`，转大写 | `open()` method，转大写     |
 | `url.full`                  | 绝对 URL，经脱敏                               | 同左                        |
+| `url.template`              | 低基数路由模板，只含 path                      | 同左                        |
 | `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 判断路由），返回空值或抛错都回退到默认规则。
+
+这套折叠规则与 View 的 `view.url_template` 共用，但入口独立：页面路由和 API 路径的模板规则通常不同，所以 `tracking.view.getUrlTemplate` 与 `tracking.request.getUrlTemplate` 互不影响。
+
 Span 开始时间使用请求开始时间，结束时间优先使用匹配到的 `PerformanceResourceTiming.responseEnd`；没有匹配时使用 Fetch resolve/reject 或 XHR `load/abort/timeout/error` 的完成时间。`http.response.status_code` 只表示真实 HTTP Response，不会上报 XHR 的本地占位值 `0`。
 
 ## Outcome 与 Status
@@ -119,6 +124,7 @@ traceparent: 00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01
       "span_id": "00f067aa0ba902b7",
       "attributes": {
         "format": "traceparent",
+        "injected": true,
         "traceparent": "00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01"
       }
     }
@@ -126,7 +132,9 @@ 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` 脱敏。
+`attributes.format` 是命中的传播格式，`attributes.injected` 标记这条 trace context 是否由 SDK 生成——业务自带合法 `traceparent` 时 `format` 与 SDK 注入同值，只能靠 `injected` 区分。其余键是该格式的**原始 Header 名与原始取值**（不做补零或进制转换），例如 Datadog 会带上 `x-datadog-trace-id`、`x-datadog-parent-id`、`x-datadog-sampling-priority` 等。
+
+`tracestate` 不做记录：它在本链路上没有消费者（SDK 从不注入 `tracestate`，后端只解析 `traceparent`），而 W3C 允许 32 个成员、每成员 256 字符，最坏情况下会给每个被追踪请求平白增加数 KB 负载。这些 Link Attributes 也不经过 `privacy.redactAttributes` 脱敏。
 
 请求 Patch 只在当前 Session 已采样时创建 Span 并注入，因此发出的 flags 恒为 `01`。注入的 span-id 在前端没有对应的已上报 Span，后端 Trace 的根 Span 会以它作为 `parent_span_id`。
 
@@ -136,14 +144,14 @@ traceparent: 00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01
 
 | 优先级 | `format` | Header | 能否解析出合法 OTel id |
 | --- | --- | --- | --- |
-| 1 | `traceparent` | `traceparent`（连带记录 `tracestate`） | 能 |
+| 1 | `traceparent` | `traceparent` | 能 |
 | 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，SDK **完全不注入**，Link Attributes 里 `injected` 为 `false`，并写入命中格式的原始 Header。只记录命中格式自己的 Header——若 `traceparent` 与 `b3` 同时存在，按优先级只记录前者。
 
 几点需要注意：
 

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

@@ -85,24 +85,26 @@ privacy: {
 
 SDK 在写入 View、Request、Resource、错误资源、CSP source、Long Task source、referrer 等 URL 字段时调用该 Hook。自定义插件直接写入名为 URL 的任意属性不会被自动识别，插件必须显式调用 `context.config.hooks.redactUrl()`。
 
-## 路由分组不是 URL 脱敏
+## 路由模板不是 URL 脱敏
 
 ```ts
 tracking: {
   view: {
-    getPathGroup(url) {
+    getUrlTemplate(url) {
       return new URL(url, location.href).pathname.replace(/\/orders\/[^/]+/, '/orders/:id');
     },
   },
 }
 ```
 
-`getPathGroup` 只生成低基数 `view.url_path_group`，不会改写 `view.url`。要保护原 URL，仍需 `privacy.redactUrl`。建议两者使用相同的动态段规则，但用途不同：
+`getUrlTemplate` 只生成低基数 `view.url_template`，不会改写 `view.url`。要保护原 URL，仍需 `privacy.redactUrl`。建议两者使用相同的动态段规则，但用途不同：
 
 - `redactUrl`：隐私和敏感数据边界；
-- `getPathGroup`：聚合维度和查询基数。
+- `getUrlTemplate`：聚合维度和查询基数。
 
-未配置 `context.attributes.page` 时默认返回空对象，不存在独立的默认页面属性路径。页面地址统一由经过 `redactUrl` 的 `view.url` 表达，聚合维度使用 `view.url_path_group`；业务通过该 Hook 添加的属性仍需自行确保不包含敏感信息。
+请求侧的 `tracking.request.getUrlTemplate` 同理，只生成 `url.template`，不影响 `url.full` 的脱敏。注意它收到的是**未脱敏**的请求 URL，因此自定义实现不要把 query 里的原值拼进返回的模板。
+
+未配置 `context.attributes.page` 时默认返回空对象，不存在独立的默认页面属性路径。页面地址统一由经过 `redactUrl` 的 `view.url` 表达，聚合维度使用 `view.url_template`；业务通过该 Hook 添加的属性仍需自行确保不包含敏感信息。
 
 ## 属性脱敏
 
@@ -267,7 +269,7 @@ SDK 不实现以下能力：
 ## 上线评审清单
 
 1. `redactUrl` 覆盖 path 中的动态 ID，且仍删除 query/fragment/认证信息；
-2. `view.url_path_group` 是低基数模板；
+2. `view.url_template` 是低基数模板；
 3. `user.id` 已按公司规范处理；
 4. Action 未开启不必要的文本采集；
 5. CSP、错误 stack、自定义字段经过字段评审；

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

@@ -26,7 +26,7 @@ export const rum = new BkOpenTelemetry({
   },
   tracking: {
     view: {
-      getPathGroup(rawUrl) {
+      getUrlTemplate(rawUrl) {
         return new URL(rawUrl, location.href).pathname
           .replace(/\/orders\/[^/]+/g, '/orders/:id')
           .replace(/\/users\/[^/]+/g, '/users/:id');
@@ -97,7 +97,7 @@ Session 采样率控制整体数据量。粗略估算：
 
 必须排查：
 
-- `view.url_path_group` 是否含订单 ID、用户 ID、UUID；
+- `view.url_template` 是否含订单 ID、用户 ID、UUID；
 - custom/action name 是否拼业务 ID；
 - 自定义属性是否包含时间戳、随机值、整条 URL；
 - error message 是否因为动态值导致无限分组。
@@ -220,7 +220,7 @@ SDK 设计为：
 - exporter 失败不会让业务 Fetch/XHR 失败；
 - unsupported Performance API 时跳过对应能力。
 
-但自定义 Hook/插件仍是业务代码：必须快速、同步、无副作用，不应发网络请求或抛异常。上线前对 `redactUrl`、`redactAttributes`、`getPathGroup`、两个 `beforeSend` 做异常与性能测试。
+但自定义 Hook/插件仍是业务代码：必须快速、同步、无副作用，不应发网络请求或抛异常。上线前对 `redactUrl`、`redactAttributes`、`getUrlTemplate`、两个 `beforeSend` 做异常与性能测试。
 
 ## 12. 灰度验收
 

package/skills/bk-rum-otele/references/session-context.md

@@ -171,7 +171,7 @@ context: {
 }
 ```
 
-未配置时默认返回空对象。页面地址使用 `view.url`，低基数路由使用 `view.url_path_group`；业务需要额外页面维度时可自行返回。
+未配置时默认返回空对象。页面地址使用 `view.url`，低基数路由使用 `view.url_template`；业务需要额外页面维度时可自行返回。
 
 Hook 每次执行，应保持低成本且不要抛错。它可能包含高基数字段，但服务端聚合维度应只选择稳定、低基数属性。
 

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

@@ -16,7 +16,7 @@
 | 领域属性               | `resource.*`、`error.*`、`vital.*`、`long_task.*` 等            | 具体发生了什么，耗时、来源和诊断细节是什么？      |
 | OTLP Envelope 与 Event | `traceId`、`spanId`、时间戳、`status`、`events`                 | 如何定位单条记录、关联调用链和读取异常/脚本归因？ |
 
-推荐先用 Resource 字段限定应用和环境，再以 `span_type` 选择信号类型，最后使用领域字段细分。Session/View 聚合优先使用 `session.id`、`view.id`；路由聚合优先使用低基数的 `view.url_path_group`，不要直接按完整 URL 或原始 path 建立高基数索引。
+推荐先用 Resource 字段限定应用和环境，再以 `span_type` 选择信号类型，最后使用领域字段细分。Session/View 聚合优先使用 `session.id`、`view.id`；路由聚合优先使用低基数的 `view.url_template`，不要直接按完整 URL 或原始 path 建立高基数索引。
 
 ## 阅读约定
 
@@ -95,9 +95,9 @@ Resource Attribute 描述产生 Span 的 SDK 实例和运行环境，同一实
 | `session.type`            | string   | Session 有效                    | 当前固定为 `user`，为未来区分其他 Session 类型保留。                                                                                 |
 | `session.has_replay`      | boolean  | Session 有效                    | 当前固定为 `false`，表示 SDK 没有随该 Session 上报 Session Replay 数据。                                                             |
 | `view.id`                 | string   | View 有效                       | 当前页面视图的关联 ID。首次加载、有效 SPA 路由变化、BFCache 恢复或 Session 续建都会创建新 View。                                     |
-| `view.name`               | string   | View 有效                       | View 的可读名称。默认取路由分组，也可由 `startView` 或 `setViewName` 设置，适合展示和聚合。                                          |
+| `view.name`               | string   | 显式命名后                      | 业务给出的可读名称，仅在 `startView({ name })` 或 `setViewName()` 调用后存在。默认不上报，展示请用 `view.name ?? view.url_template`。 |
 | `view.url`                | string   | View 有效                       | 创建 View 时的完整 URL，经 `redactUrl` 脱敏。与当前实时 `location.href` 不一定相同。                                                 |
-| `view.url_path_group`     | string   | View 有效                       | 低基数路由模板。默认把数字 ID、UUID 和长十六进制路径段归一为 `:id`，也可由 `getPathGroup` 自定义。                                   |
+| `view.url_template`     | string   | View 有效                       | 低基数路由模板。默认把数字 ID、UUID 和长十六进制路径段归一为 `:id`，也可由 `getUrlTemplate` 自定义。                                   |
 | `view.loading_type`       | string   | View 有效                       | View 创建类型：`initial_load` 首次文档加载、`route_change` SPA 路由、`bf_cache` BFCache 恢复、`session_renewal` Session 到期后续建。 |
 | `action.id`               | string[] | 自动 Action 活动中              | 与当前 Span 同时相关的自动 Action ID 数组；允许多个点击 Action 生命周期重叠。注意 Action Span 自身的同名字段是单个 string。          |
 | `device.id`               | string   | Device 插件开启                 | SDK 生成的匿名设备关联 ID。默认仅在本次插件生命周期内稳定；`persistentId: true` 时写入 localStorage，从而跨页面和 Session 保持。     |
@@ -109,7 +109,7 @@ Resource Attribute 描述产生 Span 的 SDK 实例和运行环境，同一实
 | `network.effective_type`  | string   | Network Information API 支持    | 浏览器估算的有效网络类型，常见为 `slow-2g`、`2g`、`3g`、`4g`。它反映体验模型，不等同于真实无线制式。                                 |
 | `network.connection.type` | string   | 浏览器提供 `connection.type` 时 | 浏览器返回的原始连接类型，例如 `wifi`、`cellular`、`ethernet`；多数 Safari/Firefox 环境可能缺失。                                    |
 
-默认 `context.attributes.page()` 返回空对象，不附加独立页面属性。页面地址使用 View 创建时冻结并经过 `redactUrl` 的 `view.url`，低基数路由聚合使用 `view.url_path_group`；业务需要额外页面维度时可自定义该 Hook。
+默认 `context.attributes.page()` 返回空对象，不附加独立页面属性。页面地址使用 View 创建时冻结并经过 `redactUrl` 的 `view.url`，低基数路由聚合使用 `view.url_template`；业务需要额外页面维度时可自定义该 Hook。
 
 ## RUM 公共分类字段
 
@@ -166,9 +166,9 @@ Session Span 允许没有 `view.id`：SDK 先建立 Session，再创建初始 Vi
 | `view.id`                  | string | 所有阶段                                                  | View 关联 ID。同一 View 的 start/update/end 使用相同值，可与该 View 内其他 Span 关联。                                                   |
 | `view.version`             | number | 从 1 递增                                                 | 每次 `emitViewEvent` 递增；用于恢复同一 View 生命周期快照的先后顺序。                                                                    |
 | `view.started_at`          | number | epoch ms                                                  | View 开始时间。初始 View 使用 `performance.timeOrigin`，路由/BFCache/续建 View 使用创建时刻。                                            |
-| `view.name`                | string | 所有阶段                                                  | 默认取 `view.url_path_group`，也可由 `startView({ name })` 或 `setViewName` 设置。                                                       |
+| `view.name`                | string | 显式命名后                                                | 业务可读名称，仅 `startView({ name })` 或 `setViewName()` 后存在；未命名的 View 不带该字段。                                             |
 | `view.url`                 | string | 所有阶段                                                  | 创建 View 时的 URL，经 `redactUrl` 脱敏；在该 View 生命周期内保持不变。                                                                  |
-| `view.url_path_group`      | string | 所有阶段                                                  | 低基数路由分组。数字 ID、UUID、长十六进制段默认折叠为 `:id`，用于稳定聚合动态路由。                                                      |
+| `view.url_template`      | string | 所有阶段                                                  | 低基数路由模板。数字 ID、UUID、长十六进制段默认折叠为 `:id`，用于稳定聚合动态路由。                                                      |
 | `view.loading_type`        | string | 所有阶段                                                  | `initial_load`、`route_change`、`bf_cache` 或 `session_renewal`，含义见运行时公共属性。                                                  |
 | `view.loading_time`        | number | 计算完成后，ms                                            | 从 `view.started_at` 到页面活动稳定的耗时。初始加载同时等待 load event 和页面活动，以较晚者为准；可由 `setViewLoadingTime()` 手动结束。  |
 | `view.loading_time_source` | string | 有 `view.loading_time` 时                                 | `auto` 表示 SDK 自动观察页面活动；`manual` 表示业务调用 `setViewLoadingTime()`。                                                         |
@@ -190,7 +190,8 @@ Session Span 允许没有 `view.id`：SDK 先建立 Session，再创建初始 Vi
 | 字段                              | 类型    | 条件/单位                         | 来源与详细说明                                                                                                                                  |
 | --------------------------------- | ------- | --------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
 | `url.full`                        | string  | 有有效请求/资源 URL               | 绝对 URL，经 `redactUrl` 脱敏。用于定位请求目标；不要假设 query 中仍保留原始参数。                                                              |
-| `server.address`                  | string  | URL 可解析                        | URL 的 `hostname`，不含端口。相对 URL 会基于当前页面地址解析。                                                                                  |
+| `url.template`                    | string  | Fetch/XHR                         | 低基数路由模板，只含 path，例如 `/api/orders/:id`。默认把数字 ID、UUID、长十六进制段折叠为 `:id`，可由 `tracking.request.getUrlTemplate` 覆盖。按 API 路由聚合请求时用它，不要用 `url.full`。静态资源 Span 没有该字段。 |
+| `server.address`                  | string  | URL 可解析                        | URL 的 `hostname`，不含端口。相对 URL 会基于当前页面地址解析。模板不含 host，跨域同路径会聚到一起，需要区分来源时配合该字段。                    |
 | `server.port`                     | number  | URL 显式包含端口                  | URL 的显式端口号。使用协议默认端口且 URL 未写端口时缺失。                                                                                       |
 | `resource.type`                   | string  | 必有                              | Fetch/XHR 为 `fetch`/`xhr`；静态资源使用 `PerformanceResourceTiming.initiatorType`，为空时为 `other`，常见还有 `script`、`link`、`img`、`css`。 |
 | `http.request.method`             | string  | Fetch/XHR                         | 归一为大写的 HTTP 方法，例如 `GET`、`POST`。静态资源通常没有可用的请求方法，因此缺失。                                                          |
@@ -206,12 +207,15 @@ Session Span 允许没有 `view.id`：SDK 先建立 Session，再创建初始 Vi
 
 命中 `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。 |
+| 字段        | 类型    | 条件           | 说明                                                                                                                                       |
+| ----------- | ------- | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
+| `format`    | string  | 恒有           | 命中的传播格式，取值为 `traceparent`、`sentry-trace`、`b3`、`b3-multi`、`datadog`、`sw8`。                                                  |
+| `injected`  | boolean | 恒有           | 这条 trace context 是否由 SDK 生成并注入。`true` 表示请求原本没有任何 trace Header；`false` 表示业务已自行传播，SDK 未注入。业务自带合法 `traceparent` 时 `format` 与 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` 脱敏。
+Link 的 `trace_id` / `span_id` 优先取自解析结果；`sw8` 这类无法映射为合法 OTel id 的格式会补一对随机占位 id，此时后端不存在对应 Trace。
+
+两点数据口径需要注意：Link Attributes 不经过 `privacy.redactAttributes` 脱敏；`tracestate` 不做记录，它在本链路上没有消费者，且体积最坏可达数 KB。
 
 网络阶段字段均为 number、单位 ms。每个 `*.start` 相对该 Resource Entry 的 `startTime`，每个 `*.duration` 为对应阶段结束值减开始值：
 

package/skills/bk-rum-otele/references/transport-sampling.md

@@ -60,9 +60,9 @@ https://rum.example.com/collector/v1/rum
                 { "key": "session.type", "value": { "stringValue": "user" } },
                 { "key": "session.has_replay", "value": { "boolValue": false } },
                 { "key": "view.id", "value": { "stringValue": "view-01" } },
-                { "key": "view.name", "value": { "stringValue": "/orders/:id" } },
+                { "key": "view.name", "value": { "stringValue": "订单详情" } },
                 { "key": "view.url", "value": { "stringValue": "https://app.example.com/orders/123" } },
-                { "key": "view.url_path_group", "value": { "stringValue": "/orders/:id" } },
+                { "key": "view.url_template", "value": { "stringValue": "/orders/:id" } },
                 { "key": "view.loading_type", "value": { "stringValue": "initial_load" } },
                 { "key": "span_type", "value": { "stringValue": "resource" } },
                 { "key": "outcome.type", "value": { "stringValue": "success" } },

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

@@ -277,13 +277,13 @@ tracking: {
 
 跨域还需要服务端 CORS 允许请求头 `traceparent`。如果预检失败，缩小白名单并修复 API 服务的 CORS；不要把所有第三方 URL 加入白名单。
 
-命中白名单却依然没有注入时，看 Span Link 的 `attributes.format`。只要它不是 SDK 自己生成的 `traceparent`，就说明业务已经设置了 trace Header（`sentry-trace`、`b3`、Datadog、`sw8`，或业务自己的 `traceparent`），SDK 会尊重既有链路而不注入，只把原始 Header 记进 Link Attributes。
+命中白名单却依然没有注入时，看 Span Link 的 `attributes.injected`。为 `false` 说明业务已经自行设置了 trace Header，SDK 尊重既有链路而不注入，此时 `attributes.format` 告诉你是哪种格式，同组的原始 Header 也一并记在 Link Attributes 里。注意不能只看 `format`：业务自带合法 `traceparent` 时它同样是 `traceparent`，与 SDK 注入无法区分。
 
 ## 后端按 `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 自然查不到。
+如果 Link 的 `attributes.injected` 为 `false` 且 `attributes.format` 不是 `traceparent`，说明业务用的是 `b3` / `sw8` / Datadog 等格式。后端只解析 W3C `traceparent`，这种情况下后端不会生成 Trace，Link 里的 trace-id 自然查不到。
 
 `sw8` 以及 `b3: 0` 这类只有采样标记的值，SDK 解析不出合法 OTel id，会补一对**随机占位 id** 让 Link 结构保持统一。这对 id 在后端一定查不到，判断依据仍是 `attributes.format` 与其中的原始 Header。
 
@@ -407,7 +407,7 @@ tracking: {
 - pathname 或非纯锚点 hash 变化会触发；
 - Router 同时手动 `startView()` 且使用 auto 会重复；
 - 微前端多个实例会重复；
-- `getPathGroup` 默认仅返回 pathname，不会自动识别 `/orders/123` 动态 ID；
+- 默认模板只按形状折叠数字 ID、UUID 和长十六进制段，识别不了 `/orders/abc-slug` 这类非数字动态段，需要用 `getUrlTemplate` 显式提供；
 - `setViewName()` 是改名，不创建新 View；
 - Session 续期和 BFCache 恢复会创建具有特定 loading type 的 View。
 

package/skills/bk-rum-otele/references/views-routing.md

@@ -13,7 +13,7 @@ View 表示一次可独立分析的页面体验。初始文档加载、SPA 路
 | `bf_cache` | 从 Back/Forward Cache 恢复 | `view` |
 | `session_renewal` | Session 过期后新 Session 接管当前页面 | `view` |
 
-每个 View 都生成新的 `view.id`。View 名称、URL、路由分组和自定义属性作为运行时上下文挂到其间发生的普通 Span。
+每个 View 都生成新的 `view.id`。View 的 URL、路由模板和自定义属性作为运行时上下文挂到其间发生的普通 Span；名称只在业务显式命名后才带上。
 
 ## 自动路由模式
 
@@ -52,14 +52,16 @@ bkOT.startView({
 
 `attributes` 会经过 `redactAttributes`，并删除 SDK 所有保留字段；业务无法通过 View attributes 覆盖 `session.*`、`view.*`、`span_type` 或 `outcome.*`。
 
-## View 名称和路由分组
+## View 名称和路由模板
 
-默认 `view.url_path_group` 是 URL pathname，`view.name` 默认等于该分组。
+默认 `view.url_template` 取 URL pathname 并把数字 ID、UUID、长十六进制段折叠为 `:id`。请求 Span 的 `url.template` 复用同一套折叠规则，但走独立的 `tracking.request.getUrlTemplate`。
+
+`view.name` 与 `view.url_template` 是两个不同维度：前者是业务给出的可读标签（「订单详情」），后者是路由模板（`/orders/:id`）。**只有显式调用 `startView({ name })` 或 `setViewName()` 时才会上报 `view.name`**，未命名的 View 不带该字段，后端展示时用 `view.name ?? view.url_template` 兜底即可。这样 `view.name` 的存在本身就表示"业务命名过"，也不会在每条 Span 上重复一份模板字符串。
 
 ```ts
 tracking: {
   view: {
-    getPathGroup(url) {
+    getUrlTemplate(url) {
       return new URL(url, location.href).pathname
         .replace(/\/orders\/[^/]+/, '/orders/:id')
         .replace(/\/users\/[^/]+/, '/users/:id');
@@ -68,7 +70,7 @@ tracking: {
 }
 ```
 
-`getPathGroup()` 应返回低基数、稳定的路由模板。当前业务 View 默认实现不会自动把数字、UUID 或其他业务 ID 替换为 `:id`，接入方必须按自己的路由规则显式提供模板。
+`getUrlTemplate()` 应返回低基数、稳定的路由模板。默认实现已经会把数字 ID、UUID 和长十六进制段替换为 `:id`，但它只能按形状猜：纯数字段无法与语义段区分，`/reports/2024/summary` 会被折成 `/reports/:id/summary`。路由规则明确的应用应显式提供模板，不要依赖猜测。
 
 运行期可修改名称：
 
@@ -76,12 +78,12 @@ tracking: {
 bkOT.setViewName('订单详情-只读');
 ```
 
-名称变化不会创建新 View，但会更新运行时上下文并发送 `browser.view` update。传入与当前相同名称时不发送更新。
+名称变化不会创建新 View，但会更新运行时上下文并发送 `browser.view` update。传入与当前相同名称时不发送更新。首次调用会让此后的 Span 开始带上 `view.name`。
 
 ## URL 与前序页面
 
 - `view.url`：当前 URL，经 `privacy.redactUrl`。
-- `view.url_path_group`：聚合路由模板。
+- `view.url_template`：聚合路由模板。
 - `url.previous`：前一个原始 URL 经脱敏；初始加载为空字符串。
 - `document.referrer`：仅初始自动加载写入并脱敏。
 

package/dist/core/telemetry-attributes.d.ts

@@ -1,3 +0,0 @@
-import type { Attributes } from '@opentelemetry/api';
-export declare const normalizeViewPathGroup: (pathGroup: string) => string;
-export declare const getInstrumentationSpanRuntimeAttributes: (runtimeAttributes: Attributes, fallbackViewPathGroup?: string) => Attributes;