@blueking/open-telemetry 0.0.34 → 0.0.35-beta.1

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

@@ -8,50 +8,72 @@ Session 是采样和访问会话边界；User、Device 以及 Session 字段共
 
 SDK 使用以下固定规则：
 
-| 规则 | 当前值 | 是否可配置 |
-| --- | ---: | --- |
-| 无活动超时 | 15 分钟 | 否 |
-| 最长生命周期 | 4 小时 | 否 |
-| 活动事件 | `click`、`keydown`、`scroll`、`touchstart` | 否 |
-| 活动续期节流 | 1 秒 | 否 |
-| 可见页面定期检查 | 60 秒 | 否 |
-| 采样率 | `1` | 是，`session.sampleRate` |
+| 规则               |                                                                                 当前值 | 是否可配置               |
+| ------------------ | -------------------------------------------------------------------------------------: | ------------------------ |
+| 无活动超时         |                                                                                15 分钟 | 否                       |
+| 最长生命周期       |                                                                                 4 小时 | 否                       |
+| 活动事件           | 可见页面中的可信 `click`、`pointerdown`、`keydown`、`wheel`、`touchstart`、`touchmove` | 否                       |
+| 活动续期节流       |                                                                                   1 秒 | 否                       |
+| 页面可见、切回前台 |                                                                     只检查过期，不续期 | 否                       |
+| 采样率             |                                                                                    `1` | 是，`session.sampleRate` |
 
-初始化时，SDK 尝试从 localStorage 读取同一应用和 Collector 隔离的 Session Record：
+首次可见访问时，SDK 从 localStorage 读取同一应用和 Collector 隔离的 Session Record，并在 Web Lock 内提交状态变更。后台打开的页面等待首次可见后初始化：
 
 - Record 有效：复用 ID，并延长无活动过期时间。
 - Record 不存在：创建新 Session，发送 `session.start` Span。
-- Record 已过期：创建新 ID，发送 rotate；旧 Session 的 end 由持有旧上下文的 Tab 发送。
-- localStorage 不可访问：退回当前 JavaScript 进程内存，不影响页面采集，但不能跨页面或跨 Tab 共享。
+- Record 已过期：结束旧 Session，再创建新 ID；提交状态变更的一方发送 end 和 rotate，其他 Tab 只处理本地上下文。
+- localStorage 或 Web Locks 不可用：退回当前页面内存，不影响采集，但刷新、新文档和其他 Tab 不共享该 Session。
 
 ## 续期与过期
 
-用户活动会延长有效 Session。达到 15 分钟无活动或 4 小时最长生命周期时，SDK：
+有效输入更新最后活动时间，截止时间为：
+
+```text
+expiresAt = min(lastActivityAt + 15 分钟, startedAt + 4 小时)
+```
+
+鼠标移动、页面保持可见、自动滚动、程序路由、轮询和上报不会续期。`scroll` 不独立计为输入，滚轮、触摸和键盘使用各自的可信输入事件。每次有效输入先检查过期，再续期或新建；节流不跳过过期检查。
+
+达到截止时间后，SDK：
 
 1. 通知 View、Action 等插件 Session 已过期。
-2. 发送 `session.end` Span。
+2. 由提交共享过期状态的一方发送 `session.end` Span。
 3. 清除运行时 `session.*`。
 4. 结束当前 View。
 5. 触发一次 flush。
 6. 在下一次用户活动时创建新 Session 和 `session_renewal` View。
 
-页面重新可见时只检查和延长仍有效的 Session，不会主动创建新 Session。这样后台放置很久的页面不会仅因切回前台就复活旧访问。
+已经初始化的页面重新可见时只检查，不延长或创建 Session。浏览器冻结导致 Timer 延后时，恢复或首次输入仍按当前时间判断；超时结束事件使用原截止时间，而非恢复时刻。
+
+Session 切换提交期间，SDK 暂存事件关联，保持第一次点击、路由及请求的时间和上下文，提交后按所属 Session 决定采样。待定期间不为请求新注入 `traceparent`，业务已有 Trace Header 保持不变。旧请求跨过边界才结束时，仍使用开始时的旧关联。
+
+## Action 关联边界
+
+Action 自身使用单个字符串 `action.id`。Resource、Error、Long Task 根据事件发生时间及所属 Session/View 匹配逐 Action 的有效区间，以 `action.ids: string[]` 记录全部关联；多个自动点击窗口重叠时可以同时命中，不再只取最近一次。子事件不双写旧 `action.id`，没有关联时不写 `action.ids`。未声明 `span_type` 的通用 OpenTelemetry Span 不自动推测 Action 归属。
+
+View 切换或 Session 结束会关闭旧自动 Action 的区间，后续新 View/Session 的事件不再进入旧动作。已开始请求跨边界晚到结束时保留原 Session/View/Action 关联。动作的 Span 起止时间表示已观察区间；只有正常页面稳定才有毫秒单位的 `action.loading_time`，边界中断使用 `action.end_reason` 说明，不把中断当作加载完成。完整字段与结束原因见 [用户 Action](./actions.md)。
 
 ## 跨 Tab 行为
 
 默认 storage key 按 `application.name` 与 **解析后 Endpoint 的 host** 计算：
 
 ```text
-bk_ot_session__${hash36(application.name + "\0" + endpointHost)}
+bk_ot_session__${hash36(application.name + "\0" + endpointHost)}__v2
 ```
 
-`hash36` 是 djb2 风格非密码学 hash，转成 36 进制。同一浏览器 origin 下，不同 `application.name` 或不同 Collector host 不会共用 Session。多个同源 Tab 默认共享同一 key 下的 Session Record。
+`hash36` 是 djb2 风格非密码学 hash，转成 36 进制。同一浏览器 origin 下，不同 `application.name` 或不同 Collector host 不会共用 Session。共享存储及 Web Locks 可用时，多个同源 Tab 共享同一 key 下的 Session Record；状态变更在锁内重新读取后提交。
 
 - 其他 Tab 只延长当前相同 Session 时，本 Tab 会更新自己的过期 Timer。
 - 其他 Tab 使 Session 过期或替换 ID 时，本 Tab 会停用自己的 Session。
 - 已停用的 Tab 不会被其他 Tab 的新 Session 被动复活；本 Tab 发生用户活动后才读取并接管共享 Session。
+- `storage` 通知仅触发重新读取当前状态，迟到的旧通知不能关闭新 Session。
+- 关闭单个 Tab 或停止一个 SDK 实例，只结束本地 View，不代表其他 Tab 的共享 Session 结束。
+
+共享记录最多保留 100 条结束快照。Tab 冻结并错过多次轮换后，会按旧 Session ID 查找真实结束时间；不能拿恢复时刻或冻结前的旧期限代替。若快照已被裁剪、存储清空或损坏，则保守清理本地关联，不伪造旧 View 和未完成 Action 的最终结束事件；接收侧需允许最终 View 更新缺失，并利用全局 Session end 和已有活动证据恢复边界。
 
-需要完全隔离不同接入实例时，可设置显式 `session.storageKey`。
+独立的 `tab.id` 保存在 sessionStorage，刷新时保留；不可访问时使用内存 ID。它用于页面分组，不作为共享状态锁或结束去重键。复制标签页可能复制 sessionStorage，因此不能依赖 `tab.id` 在所有复制场景中唯一。
+
+需要完全隔离不同接入实例时，可设置显式 `session.storageKey`；实际存储也使用 `__v2` 后缀。新版本不复用旧命名空间的 active 记录，避免旧 Tab 的可见续期逻辑污染新规则。升级时可能产生一次 Session 分段。
 
 ```ts
 new BkOpenTelemetry({
@@ -73,6 +95,8 @@ new BkOpenTelemetry({
 - 中间值：同一应用、同一 Session 始终得到相同决定。
 - Session 轮换后使用新 ID 重新计算。
 
+迟到的 Resource、LongTask、WebVitals 按发生时所属 Session 判断采样，旧 Session 已采样时不会因当前 Session 未采样或已过期而提前丢弃。停止采集或撤回 Consent 后，仍会阻止迟到回调继续上报。
+
 输入有限数值会限制到 `0..1`；缺省、`NaN` 或无限值回退为 `1`。采样率写入 Resource 的 `session.sample_rate`，不是每条 Span 的业务属性。
 
 完整过滤与上报行为见[上报协议、批处理与采样](./transport-sampling.md)。
@@ -81,23 +105,28 @@ new BkOpenTelemetry({
 
 Span 名按 `session.<session.phase>` 生成：
 
-| `session.phase` | 使用时机 | 内部 lifecycle reason（不上报为 Attribute） |
-| --- | --- | --- |
-| `start` | 首次创建 | `init` |
-| `rotate` | 旧 Session 过期后新建 | `inactivity`、`maxLifetime` |
-| `end` | 当前 Session 失效 | `inactivity`、`maxLifetime`、`external` |
+| `session.phase` | 使用时机              | 内部 lifecycle reason（不上报为 Attribute） |
+| --------------- | --------------------- | ------------------------------------------- |
+| `start`         | 首次创建              | `init`                                      |
+| `rotate`        | 旧 Session 过期后新建 | `inactivity`、`maxLifetime`                 |
+| `end`           | 提交 Session 超时结束 | `inactivity`、`maxLifetime`                 |
 
-实际上报字段只有：
+Session 生命周期字段及公共关联字段包括：
 
 - `session.id`
 - `session.type=user`
 - `session.has_replay=false`
 - `session.phase`
+- `session.start_time`：所属 Session 的创建时间，epoch 毫秒。
+- `session.last_activity_time`：所属 Session 的最后有效活动时间，epoch 毫秒；后台请求不会更新此值。
+- `tab.id`：标签页分组标识。
 
-过期原因通过 `onSessionLifecycle` 通知插件，**不会**写成 `session.lifecycle.reason` 或 `session.start_time`。完整字段见[遥测字段字典](./telemetry-reference.md#session-字段)。
+过期原因通过 `onSessionLifecycle` 通知插件，**不会**写成 `session.lifecycle.reason`。外部状态删除、替换或降级只关闭本地绑定，没有可靠的共享过期依据时不发送全局 end。完整字段见[遥测字段字典](./telemetry-reference.md#session-字段)。
 
 生命周期 Span 是瞬时事件，持续时间由服务端根据时间戳推导。
 
+接收侧需按应用隔离范围、`session.id` 和 `phase=end` 幂等处理，不能按随机 `span.id` 统计结束次数。SDK 的单方发送只减少重复，不能保证网络恰好投递一次；也可能因页面退出缺少 end。接收侧应结合已上报的活动时间恢复期限，不以后台请求的接收时间续期。
+
 ## User 上下文
 
 初始化时可传入用户：
@@ -121,12 +150,12 @@ SDK 只维护 `user.id`，并原样透传：不 hash、不截断、不验证、
 
 `tracking.device` 默认开启。构造阶段读取相对稳定的设备信息并写入 Resource：
 
-| 字段 | 来源 | 可能缺失 |
-| --- | --- | --- |
-| `user_agent.name` | UA 简单识别：Edge/Chrome/Firefox/Safari/Other | 否 |
-| `user_agent.version` | UA 主版本 | 未识别版本时 |
-| `user_agent.os.name` | UA / UA-CH platform | 否，无法识别为 `Other` |
-| `device.type` | UA-CH mobile 或移动 UA 特征 | 否，仅为 `mobile` 或 `desktop` |
+| 字段                 | 来源                                          | 可能缺失                       |
+| -------------------- | --------------------------------------------- | ------------------------------ |
+| `user_agent.name`    | UA 简单识别：Edge/Chrome/Firefox/Safari/Other | 否                             |
+| `user_agent.version` | UA 主版本                                     | 未识别版本时                   |
+| `user_agent.os.name` | UA / UA-CH platform                           | 否，无法识别为 `Other`         |
+| `device.type`        | UA-CH mobile 或移动 UA 特征                   | 否，仅为 `mobile` 或 `desktop` |
 
 关闭 `tracking.device` 时，这些 Device Resource 字段不写入。当前不读取 `navigator.deviceMemory`，因此没有 `device.memory_gib`。
 
@@ -134,14 +163,14 @@ SDK 只维护 `user.id`，并原样透传：不 hash、不截断、不验证、
 
 Device 插件还维护：
 
-| 字段 | 更新时机 |
-| --- | --- |
-| `device.id` | 插件启动时 |
-| `browser.viewport.width/height` | 启动、resize、orientationchange |
-| `browser.screen.width/height` | 启动、resize、orientationchange |
-| `network.status` | 启动、online、offline、connection change |
-| `network.effective_type` | 启动和 connection change |
-| `network.connection.type` | 同上 |
+| 字段                            | 更新时机                                 |
+| ------------------------------- | ---------------------------------------- |
+| `device.id`                     | 插件启动时                               |
+| `browser.viewport.width/height` | 启动、resize、orientationchange          |
+| `browser.screen.width/height`   | 启动、resize、orientationchange          |
+| `network.status`                | 启动、online、offline、connection change |
+| `network.effective_type`        | 启动和 connection change                 |
+| `network.connection.type`       | 同上                                     |
 
 视口变化使用 250ms trailing debounce。`network.status` 在浏览器环境中始终存在，其他网络字段只有浏览器实现 Network Information API 时才存在。这些变化不主动生成 Span，只影响后续 Span 的上下文。