可观测性后端【免费下载链接】highlighthighlight.io: The open source, full-stack monitoring platform. Error monitoring, session replay, logging, distributed tracing, and more.项目地址https://gitcode.com/gh_mirrors/hi/highlight点击查看免费下载Session Replay会话回放是 highlight.io 全栈监控平台的核心能力之一它让你能够回放用户在 Web 应用中的真实操作过程把用户到底做了什么、为什么出错看得一清二楚。本文以仓库中的 1_overview.md 为骨架结合 frontend 与 sdk 目录下的真实实现系统讲解 Session Replay 的录制机制、功能特性、会话定义、搜索过滤、URL 提取与性能影响帮助你在接入 highlight.io 后快速用好这套能力。什么是 Session ReplaySession 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。跨源 iframehighlight 的录制客户端支持让 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.mdH.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 nameGraphQL 单端点导致网络请求难以区分highlight 解析出每个请求的 operation name 并展示在回放网络 tab 中格式化 payload对难以阅读的 GraphQL 请求/响应体做格式化便于直接阅读。具体见 graphql.md。从仓库实现看GraphQL 操作名的提取逻辑位于前端解析层见 frontend/parser 相关代码说明这是一条独立的解析链路而非简单地展示原始请求字符串。实时模式Live ModeLive 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 Searchhighlight.io 允许你通过 SDK 发送给它的任何数据来搜索会话。可搜索的数据形态包括track调用见 tracking-events.mdidentify调用见 identifying-sessions.md点击数据。搜索基于 搜索查询语法下面按检索类型展开见 session-search.md。默认搜索行为默认情况下highlight 显示已完成且完全处理的会话即completedtrue。对于会话较少的新项目highlight 会显示全部会话并给出示例查询completed(true or false)。默认搜索键Default Key会话搜索的默认键会跨多个属性检索包括用户的标识符和地理位置例如email、device_id、给定的identifier以及city、country。输入不带键的表达式如highlight时会等价展开为email*highlight* OR city*highlight*按 Track 数据搜索track调用携带的自定义属性可直接用于过滤。例如按追踪的功能开关FeatureFlag-Analytics的值过滤会话FeatureFlag-Analyticstrue按 Identify 数据搜索identify调用中名为identifier的属性其值对应传给H.init/H.identify第一个参数的值可用于检索。例如identifierspencerhighlight.io按用户点击搜索highlight 会把用户的页面点击记录为两个可查询属性见 session-search.mdclickSelector目标 HTML 元素的 selector由元素的tag、id、class值拼接而成clickTextContent目标元素的textContent属性只发送前2000 个字符。示例clickSelectorsvg clickTextContentLast 30 days按访问 URL 搜索通过visited-url过滤器按用户访问过的 URL 检索会话visited-urlhttps://app.highlight.io/由于 URL 常含:和等特殊字符可用引号包裹避免解析错误。同时支持contains**与matches//运算符visited-url*sessions* visited-url/.\d/sessions./自动注入的属性默认情况下highlight 的 SDK 会自动注入一批属性为会话检索提供额外上下文。完整清单如下摘自 session-search.md属性说明示例active_length用户活跃时间毫秒10mbrowser_name用户使用的浏览器Chromebrowser_version浏览器版本124.0.0.0city用户所在城市San Franciscocompleted会话是否录制完成truecountry用户所在国家Greecedevice_id用户设备指纹1018613574environmentSDK 中指定的环境productionfirst_time是否是该用户的首个会话falsehas_comments是否有人评论过该会话truehas_errors会话是否包含关联错误truehas_rage_clicks用户是否在会话中愤怒点击trueidentified会话是否成功识别了用户falseidentifier传给H.init的标识符1ip用户 IP 地址127.0.0.1length会话总时长10mos_name用户操作系统Mac OS Xos_version操作系统版本10.15.7pages_visited会话访问的页面数10sample用于会话抽样的唯一排序值c1c9b1137183cbb1service_versionSDK 中指定的服务版本e1845285cb360410aee05c61dd0cc57f85afe6dastate用户所在州/省Virginiaviewed_by_anyone是否有人查看过该会话trueviewed_by_me你的账号是否查看过该会话false其中identifier、ip、city、country等属性在会话检索与后端存储中有直接对应例如 backend/clickhouse/sessions.go 中维护的会话字段模型保证这些属性可被数据库层索引与查询。搜索技巧用completedfalse查看进行中的实时会话点击 New Random Seed 可为sample属性生成新的抽样值从而创建一批新的会话样本目前length与active_length尚不支持时间后缀运算该能力即将上线时间后缀s、m、h可用于时长类过滤例如length10m找出所有长于 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?queryidentifieraliceexample.com排除你所在组织的会话/sessions?queryidentifier!*yourdomain.com*查看访问过应用特定页面的会话/sessions?queryvisited-url*/your/path/name*组合多个属性/sessions?queryidentifierBob%20email!aliceexample.com提取会话 URLSession URL有时你希望在用户访问你的 Web 应用时提取会话 URL并发送给你的其他工具。例如接入客户支持工具时很多客户会把自家用户的会话 URL 发给支持工具以便协助排查问题。使用 SDK 提供的H.getSessionDetails方法即可该方法返回包含url与urlWithTimestamp属性的对象H.getSessionDetails().then(({url, urlWithTimestamp}) { console.log(url, urlWithTimestamp); });其中url是会话的通用链接urlWithTimestamp则带有时间戳参数可用于定位到会话中的具体时刻。更完整的 SDK 说明见 client.md。过滤会话Filtering Sessionshighlight.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_errorstrue的会话。用自定义逻辑过滤如需基于自定义逻辑过滤会话例如过滤未登录用户的会话使用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 接入你的客户支持链路让整个团队的排障闭环起来。赞分享可观测性后端【免费下载链接】highlighthighlight.io: The open source, full-stack monitoring platform. Error monitoring, session replay, logging, distributed tracing, and more.项目地址https://gitcode.com/gh_mirrors/hi/highlight点击查看免费下载相关推荐WezTerm 会话录制与回放指南wezterm record / replay 完整实战WezTerm 会话录制与回放指南wezterm record / replay 完整实战 导读 本指南聚焦 WezTerm 内置的命令行工具 wezterm桌面应用开发工具跨平台OneUptime Session Replay 会话回放完全指南从浏览器录制到隐私合规与故障排查OneUptime Session Replay 会话回放完全指南从浏览器录制到隐私合规与故障排查 导读 本篇技术指南围绕 OneUptime 开源可观测平台可观测性后端运维前端云原生微服务AI Agentrrweb 完全指南从项目架构到 session replay 的录制与回放实战rrweb 完全指南从项目架构到 session replay 的录制与回放实战 rrwebrecord and replay the web是一个用于录前端可观测性开发工具上一篇Skill Seekers SKILL.md 智能增强实战用 AI 把通用模板变成高质量技能文档下一篇终极指南3分钟打造你的个性化Obsidian知识库创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考