- 可观测性
- 后端
【免费下载链接】highlight
highlight.io: The open source, full-stack monitoring platform. Error monitoring, session replay, logging, distributed tracing, and more.
Session Replay（会话回放）是 highlight.io 全栈监控平台的核心能力之一，它让你能够回放用户在 Web 应用中的真实操作过程，把"用户到底做了什么、为什么出错"看得一清二楚。本文以仓库中的 1_overview.md 为骨架，结合 frontend 与 sdk 目录下的真实实现，系统讲解 Session Replay 的录制机制、功能特性、会话定义、搜索过滤、URL 提取与性能影响，帮助你在接入 highlight.io 后快速用好这套能力。
什么是 Session Replay
Session replay 让你的团队看到用户是如何使用你的 Web 应用的，并洞察 bug 发生的真正原因。在 highlight.io 中，团队特别强调 "cohesion"（一致性/内聚），也就是把会话（sessions）、错误（errors）和日志（logs）在你的整个技术栈中进行映射关联，从而获得关于用户实际行为准确而全面的认知。换句话说，Session Replay 不只是"录屏"，而是把一段用户操作与同一时间轴上的错误、日志、网络请求等数据对齐起来，形成可交叉检索的上下文。
从仓库结构看，highlight.io 的录制客户端位于 sdk/highlight-run（前端 SDK），回放播放器与相关解析逻辑位于 frontend；底层录制协议则构建在 rrweb 等录制基础库之上。这意味着会话回放能力不是孤立的"录屏工具"，而是整个观测数据管道中的一环：录制 → 上报 → 后端存储（见 backend/clickhouse/sessions.go）→ 检索与回放。
快速开始
接入 Session Replay 的完整流程可以参考 getting-started 总览。核心思路很简单：在你的 Web 应用中安装 highlight.run 的 SDK 并初始化，录制即自动开始。初始化代码形如：
import { H } from 'highlight.run'; H.init('<YOUR_PROJECT_ID>', { // ... 可选的配置项 });H.init是前端 SDK 的入口，所有 Session Replay 配置（如手动启动、禁用录制、隐私脱敏等）都通过这里的选项传入。初始化之后，highlight 会通过MutationObserver等浏览器 API 持续捕获 DOM 变化并上报到平台。
核心功能特性
Session Replay 的功能面非常广，下面按官方文档 1_overview.md 中列出的特性逐一展开，并补充仓库中的实现细节。
Shadow DOM 与 Web Components 录制
highlight.io 开箱即用地支持 Shadow DOM 与 Web Components。这意味着即使你的页面大量使用封装了内部 DOM 结构的自定义元素（如 Salesforce Lightning Web Components），录制器也能捕获其中的交互细节。
对于在 Salesforce 环境中安装 highlight，可参考 salesforce-lwc.md 中的详细说明。这一能力对大量使用组件化、框架封装的现代前端项目尤其重要——Shadow DOM 中的节点对普通 DOM 遍历是不可见的，录制器需要额外处理才能还原这些子树中的交互。
请求代理（Request Proxying）
从浏览器直接向第三方服务发送请求，存在被广告拦截器（ad blocker）和 Chrome 扩展屏蔽的风险。highlight.io 支持将请求通过你自己的域名进行代理，从而规避这类拦截。相关配置见 proxying-highlight.md。
代理的典型场景是：某些用户环境安装了比较激进的拦截插件，直接上报到 highlight.io 的域名可能被丢弃，导致会话数据缺失；通过自有域名代理后，上报流量与你的业务流量同源，可靠性显著提升。
Canvas 与 Iframe 录制
highlight.io 支持录制canvas（因此也支持 WebGL）元素。不过由于canvas的绘图本质（像素级快照而非 DOM 结构），录制存在质量/保真度上的取舍，高频重绘的 canvas 场景会产生大量快照数据。Canvas 录制的配置说明见 canvas.md。
iframe 方面分两种情况：
- 同源 iframe / 你拥有父页面：SDK 支持在 iframe 内录制，但受浏览器安全限制存在一定约束，详见 iframes.md。
- 跨源 iframe：highlight 的录制客户端支持让 iframe 把自身事件转发给父页面的会话。如果你不拥有嵌入 iframe 的父页面，但仍希望录制 iframe 内容，可在
H.init中传入recordCrossOriginIframe: false，强制 iframe 作为独立应用录制；否则 iframe 会等待父页面开始录制后再联动。
H.init('<YOUR_PROJECT_ID>', { recordCrossOriginIframe: false, // 强制跨源 iframe 独立录制 });DevTools 数据录制
highlight.io 支持录制你在 Chrome DevTools 窗口中看到的所有资源类型，即控制台消息（console）、网络请求（network）和错误（errors）。这些数据会与画面同步显示在回放的时间轴上，让"出错的瞬间"有据可查。相关埋点配置见 7_replay-configuration 总览。
值得一提的是，对 GraphQL 请求，由于 GraphQL 传统上所有请求都走同一个端点，追踪网络请求是一件麻烦事。highlight.io 已经提取出 GraphQL operation name，并在回放的网络面板中直接展示；同时把难以阅读的 GraphQL payload 做了格式化处理（见 graphql.md）。这让基于 GraphQL 的应用也能在会话回放中快速定位到具体的查询/变更操作。
用户识别与事件追踪
默认情况下，用户在你的 highlight.io 中是匿名的。但 highlight.io 提供了通过 JavaScript SDK 识别用户并记录其操作的能力，见 events-and-users.md：
H.identify：为会话绑定用户标识（如邮箱、设备 ID 或自定义 identifier），这是后续按用户检索会话、做个性化分析的基础。H.track：记录用户在会话中的自定义事件与属性（例如功能开关 FeatureFlag 的状态），这些属性会进入会话索引，可被搜索。
会话（Session）的定义
highlight 的会话生命周期规则非常明确（见 events-and-users.md）：
- 当你在 Web 应用中调用
H.init（或手动延迟录制时调用H.start）时，一个 highlight 会话开始； - 会话开始后，同一会话最长连续录制4 小时；
- 每个浏览器标签页/实例都会开启一个独立会话——同一时间打开 2 个标签页就会录制 2 个会话；
- 会话可以续接：单个标签页关闭后在15 分钟内重新打开，会恢复已有会话；超过 15 分钟则开启新会话；
- 活跃时间（Active time）的定义：用户与页面交互、且交互间隔不超过10 秒的时间段。例如用户连续移动鼠标/打字/点击 30 秒且间隔都不超过 10 秒，就计为 30 秒活跃时间。
这套定义直接影响"会话计数"与计费：过滤掉的会话不计入账单配额（见下文过滤章节），且活跃时间/会话时长也是搜索属性active_length、length的计算基础。
GraphQL 支持
如前述，highlight 在会话回放的网络面板中做了两项 GraphQL 专项优化：
- 提取 operation name：GraphQL 单端点导致网络请求难以区分，highlight 解析出每个请求的 operation name 并展示在回放网络 tab 中；
- 格式化 payload：对难以阅读的 GraphQL 请求/响应体做格式化，便于直接阅读。
具体见 graphql.md。从仓库实现看，GraphQL 操作名的提取逻辑位于前端解析层（见 frontend/parser 相关代码），说明这是一条独立的解析链路，而非简单地展示原始请求字符串。
实时模式（Live Mode）
Live Mode 支持实时跟踪用户，让你看到用户当前正在页面上做什么。见 live-mode.md：
- 当会话处于"活跃"状态（用户仍在页面且仍在发送会话数据）时，Live Mode默认开启；
- 你可以实时看到会话当前的样子，但尚未处理完的事件不可见——错误、控制台日志、网络流量只有在关闭 Live Mode 后才按最近处理进度显示；
- 在 Live Mode 下，时间轴拖动（time-scrubbing）被禁用，因为你看到的一直是最新的会话视图；
- 随时可以通过开关按钮关闭 Live Mode，此时会话显示到最新已处理数据为止；
- 点击会话时间轴写评论会自动退出 Live Mode，因为评论与具体时间戳绑定。
性能影响
highlight.io 在做技术决策时始终把站点性能放在第一位（见 performance-impact.md）：
- 包体积：highlight.run 的 gzip 后体积仅约11 KB，对页面加载指标的影响可以忽略；
- DOM 交互性能：录制基于浏览器原生
MutationObserverAPI；上报时采用周期性缓冲，既避免事件长时间滞留内存，又避免频繁的网络请求干扰用户交互； - 网络开销：客户端大约每3 秒上报一次遥测数据，并且保证同一时刻最多只有 1 个请求在途，同时根据用户网络速度自适应，不会压垮终端用户机器。
关于 Session Replay 对 Web 应用性能影响的更深入分析，仓库博客目录中有专门文章 session-replay-performance.md 可供参考。
隐私与脱敏（Privacy & Redaction）
对需要录制前端数据的工具而言，隐私是绕不开的话题。highlight.io 提供了对录制内容中特定数据进行脱敏（redact）的选项，完整说明见 privacy.md。这包括对特定 DOM 元素、属性值等进行隐藏或替换，确保密码、身份证号、密钥等敏感信息不会进入录制数据。
Rage Clicks（愤怒点击）
Rage Clicks 相当于用户"狂按电梯关门键"的行为——只不过对象是你应用上的某个元素，原因是按钮没按预期工作。highlight.io 可以标记这类挫败感行为（见 rage-clicks.md）：
- 默认判定规则：在2 秒或更长的时间窗口内，用户在8 像素半径范围内点击5 次及以上，即视为 rage click；
- 灵敏度可自定义（在 project settings 页面）：
- Elapsed Time（秒）：点击计入 rage click 的最大时间间隔；
- Radius（像素）：判定为同一 rage click 的点击间距；
- Minimum Clicks：构成 rage click 所需的最小相邻点击次数；
- 告警：在项目的 alerts 页面创建 rage click 告警，可在 Slack 或邮件中收到用户愤怒点击的通知。
从后端实现看，rage click 的检测与告警链路有对应支撑：仓库中存在专门处理会话告警的代码，如 backend/alerts/sessionalerts.go 与 backend/temp-alerts/temp-alerts.go，说明这类行为分析会进入实时告警管道。
播放器会话缓存（Player Session Caching）
多数情况下，回放器的本地缓存能带来更流畅的播放体验。但对运行内存密集型技术栈的用户（如使用 Canvas 录制、或 DOM 变化非常频繁），本地会话播放器偶尔会拖慢浏览器标签页。为此，highlight 在 dashboard 中增加了关闭会话缓存的选项（见 player-session-caching.md）。
该选项位于Settings > Account Settings > Player Settings。在资源受限的工作环境下关闭缓存，可以换取回放器的稳定性。
会话检索（Session Search）
highlight.io 允许你通过 SDK 发送给它的任何数据来搜索会话。可搜索的数据形态包括：
track调用（见 tracking-events.md）；identify调用（见 identifying-sessions.md）；- 点击数据。
搜索基于 搜索查询语法，下面按检索类型展开（见 session-search.md）。
默认搜索行为
默认情况下，highlight 显示已完成且完全处理的会话，即completed=true。对于会话较少的新项目，highlight 会显示全部会话，并给出示例查询completed=(true or false)。
默认搜索键（Default Key）
会话搜索的默认键会跨多个属性检索，包括用户的标识符和地理位置，例如email、device_id、给定的identifier，以及city、country。输入不带键的表达式（如highlight）时，会等价展开为：
email=*highlight* OR city=*highlight*按 Track 数据搜索
track调用携带的自定义属性可直接用于过滤。例如按追踪的功能开关FeatureFlag-Analytics的值过滤会话：
FeatureFlag-Analytics=true按 Identify 数据搜索
identify调用中名为identifier的属性（其值对应传给H.init/H.identify第一个参数的值）可用于检索。例如：
identifier=spencer@highlight.io按用户点击搜索
highlight 会把用户的页面点击记录为两个可查询属性（见 session-search.md）：
clickSelector：目标 HTML 元素的 selector，由元素的tag、id、class值拼接而成；clickTextContent：目标元素的textContent属性，只发送前2000 个字符。
示例：
clickSelector=svg clickTextContent="Last 30 days"按访问 URL 搜索
通过visited-url过滤器按用户访问过的 URL 检索会话：
visited-url="https://app.highlight.io/"由于 URL 常含:和=等特殊字符，可用引号包裹避免解析错误。同时支持contains（=**）与matches（=//）运算符：
visited-url=*sessions* visited-url=/.+\d/sessions.+/自动注入的属性
默认情况下，highlight 的 SDK 会自动注入一批属性，为会话检索提供额外上下文。完整清单如下（摘自 session-search.md）：
| 属性 | 说明 | 示例 |
|---|---|---|
active_length | 用户活跃时间（毫秒） | 10m |
browser_name | 用户使用的浏览器 | Chrome |
browser_version | 浏览器版本 | 124.0.0.0 |
city | 用户所在城市 | San Francisco |
completed | 会话是否录制完成 | true |
country | 用户所在国家 | Greece |
device_id | 用户设备指纹 | 1018613574 |
environment | SDK 中指定的环境 | production |
first_time | 是否是该用户的首个会话 | false |
has_comments | 是否有人评论过该会话 | true |
has_errors | 会话是否包含关联错误 | true |
has_rage_clicks | 用户是否在会话中愤怒点击 | true |
identified | 会话是否成功识别了用户 | false |
identifier | 传给H.init的标识符 | 1 |
ip | 用户 IP 地址 | 127.0.0.1 |
length | 会话总时长 | 10m |
os_name | 用户操作系统 | Mac OS X |
os_version | 操作系统版本 | 10.15.7 |
pages_visited | 会话访问的页面数 | 10 |
sample | 用于会话抽样的唯一排序值 | c1c9b1137183cbb1 |
service_version | SDK 中指定的服务版本 | e1845285cb360410aee05c61dd0cc57f85afe6da |
state | 用户所在州/省 | Virginia |
viewed_by_anyone | 是否有人查看过该会话 | true |
viewed_by_me | 你的账号是否查看过该会话 | false |
其中identifier、ip、city、country等属性在会话检索与后端存储中有直接对应，例如 backend/clickhouse/sessions.go 中维护的会话字段模型，保证这些属性可被数据库层索引与查询。
搜索技巧
- 用
completed=false查看进行中的实时会话； - 点击 "New Random Seed" 可为
sample属性生成新的抽样值，从而创建一批新的会话样本； - 目前
length与active_length尚不支持时间后缀运算，该能力即将上线； - 时间后缀（
s、m、h）可用于时长类过滤，例如length>10m找出所有长于 10 分钟的会话。
会话搜索深链接（Deep Linking）
你构建的搜索查询会直接反映在 URL 参数中，可以分享给他人做深链接，也可以编程式生成（见 sessions-search-deep-linking.md）。
语法
/sessions?query={key}={value}- 逻辑组合
AND/OR内建于查询中，用空格（%20）分隔：/sessions?query={key1}={value1}%20AND%20{key2}={value2}/sessions?query={key1}={value1}%20OR%20{key2}={value2}
- 默认隐式为
AND，因此以下两条查询等价：/sessions?query={key1}={value1}%20AND%20{key2}={value2}/sessions?query={key1}={value1}%20{key2}={value2}
- 会话属性列表见 session-search.md；
- 运算符与通用搜索语法见 search.md。
示例
查看特定用户的会话：
/sessions?query=identifier=alice@example.com排除你所在组织的会话：
/sessions?query=identifier!=*@yourdomain.com*查看访问过应用特定页面的会话：
/sessions?query=visited-url=*/your/path/name*组合多个属性：
/sessions?query=identifier=Bob%20email!=alice@example.com提取会话 URL（Session URL）
有时你希望在用户访问你的 Web 应用时提取会话 URL，并发送给你的其他工具。例如接入客户支持工具时，很多客户会把自家用户的会话 URL 发给支持工具，以便协助排查问题。
使用 SDK 提供的H.getSessionDetails方法即可，该方法返回包含url与urlWithTimestamp属性的对象：
H.getSessionDetails().then(({url, urlWithTimestamp}) => { console.log(url, urlWithTimestamp); });其中url是会话的通用链接，urlWithTimestamp则带有时间戳参数，可用于定位到会话中的具体时刻。更完整的 SDK 说明见 client.md。
过滤会话（Filtering Sessions）
highlight.io 允许你过滤掉不想在会话列表中看到的会话，适合处理与你的应用无关、或不可操作的会话。被过滤的会话不计入账单配额（见 filtering-sessions.md）。
摄入过滤（Ingestion Filters）
可以按产品维度设置摄入过滤，限制记录的数据点数量。对会话、错误、日志、追踪（traces）均可配置以下三种方式：
- 按百分比抽样：例如只摄入 1% 的会话。对每个收到的会话，系统基于该产品模型的标识符做随机化决策，保证抽样一致性；对 traces 而言，使用
Trace ID确保同一 trace 的所有子项一起被摄入或一起被丢弃。 - 速率限制：限制 1 分钟窗口内的最大摄入数据点数量。例如配置每分钟最多 100 个会话，可在产品用量激增时限制录制的会话数。
- 排除查询：例如配置排除查询
environment: development，避免摄入所有带development环境的会话。
这些过滤器只对实际保留的数据计费。例如只摄入 1% 的会话，就只按 1% 的会话计费（按上述会话定义计量）。过滤器配置入口在项目的设置页面（/settings/filters）。
按用户标识过滤
想过滤特定用户的会话时，可在项目设置的 "Session Replay" 选项卡下，把用户标识加入 "Filtered Sessions" 输入框。注意：过滤依据是你在H.identify中传入的identifier（即第一个参数）。
只保留有错误的会话
如果你主要用 highlight 做错误监控，可在项目设置中把摄入过滤器配置为"仅录制带错误的会话"，即设置Has Error: false过滤器（实际上是指不保留无错误的会话，等价于只保留has_errors=true的会话）。
用自定义逻辑过滤
如需基于自定义逻辑过滤会话（例如过滤未登录用户的会话），使用H.init配置中的manualStart标志，让你可以自行决定何时开始/停止会话：
H.init({ manualStart: true, // ... other options })然后手动启动会话：
useEffect(() => { if (userIsLoggedIn) { H.start() } }, [userIsLoggedIn])完全禁用会话录制
如果只想用 highlight 的错误监控或日志产品、不需要会话回放，可以这样配置：
import { H } from 'highlight.run'; H.init('<YOUR_PROJECT_ID>', { disableSessionRecording: true, // ... });设置disableSessionRecording: true后 SDK 将不再录制并上报会话数据，但仍可正常上报错误与日志。这一开关与摄取层的过滤（见 backend 中各类 ingest 路径）共同构成了"从客户端到服务端"的多层会话裁剪能力。
总结
highlight.io 的 Session Replay 是一套完整的能力矩阵：从开箱即用的 Shadow DOM/Canvas/iframe 录制，到 DevTools 数据（console、network、错误）与 GraphQL 专项优化；从 Live Mode 实时跟踪，到基于track/identify/点击/URL 的多维会话检索，再到深链接分享、URL 提取、三层摄入过滤与精细的性能调优。会话、错误、日志在时间轴上的"cohesion"对齐，让它不只是录屏，而是一个可以回答"用户到底遇到了什么"的完整观测工具。
接入后的最佳实践建议：优先在 privacy.md 配置脱敏规则；按计费与流量预期在 filtering-sessions.md 设置摄入抽样与速率限制；对内存敏感的环境关闭播放器缓存；最后，用H.getSessionDetails把会话 URL 接入你的客户支持链路，让整个团队的排障闭环起来。
- 可观测性
- 后端
【免费下载链接】highlight
highlight.io: The open source, full-stack monitoring platform. Error monitoring, session replay, logging, distributed tracing, and more.
相关推荐
WezTerm 会话录制与回放指南：wezterm record / replay 完整实战
WezTerm 会话录制与回放指南：wezterm record / replay 完整实战 导读 本指南聚焦 WezTerm 内置的命令行工具 wezterm
桌面应用开发工具跨平台OneUptime Session Replay 会话回放完全指南：从浏览器录制到隐私合规与故障排查
OneUptime Session Replay 会话回放完全指南：从浏览器录制到隐私合规与故障排查 导读 本篇技术指南围绕 OneUptime 开源可观测平台
可观测性后端运维前端云原生微服务AI Agentrrweb 完全指南：从项目架构到 session replay 的录制与回放实战
rrweb 完全指南：从项目架构到 session replay 的录制与回放实战 rrweb（record and replay the web）是一个用于录
前端可观测性开发工具
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
 回调修复的源码级解读)
