highlight.io 会话搜索深链接（Session Search Deep Linking）实战指南

可观测性后端【免费下载链接】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点击查看免费下载在 highlight.io 中你在会话Session搜索页构建的每一条查询都会实时反映到浏览器地址栏的 URL 查询参数中。你可以将这类 URL 直接分享给同事让对方打开即看到完全相同的搜索结果也可以编写脚本以编程方式批量生成、拼接这类 URL用于埋点报表、告警通知或外部工单系统。本篇指南以 highlight.io 官方文档 sessions-search-deep-linking.md 为核心骨架结合仓库内的搜索语法实现、查询解析器与 ClickHouse 字段映射源码完整讲解深链接 URL 的语法、组合逻辑、常用场景示例与底层原理读完即可动手构造并分享自己的会话搜索链接。什么是会话搜索深链接会话搜索深链接的核心思想是搜索即 URL。highlight.io 把搜索框里输入的查询表达式原样写入/sessions页面的query查询参数因此 URL 本身就是一个可传递、可复用、可程序化生成的搜索状态。从源码实现看前端会话列表页通过use-query-params的useQueryParam(query, StringParam)读取 URL 中的query参数并将其作为搜索框的初始查询条件见 SearchContext.tsx用户在搜索框中提交查询后查询字符串被传入useGetSessions中的 GraphQL 变量最终下发到后端执行见 useGetSessions.ts。这意味着分享把带query参数的 URL 发给任何有权限的团队成员对方打开即看到同一组过滤条件与结果收藏把常用排查条件存为浏览器书签随时一键直达程序化生成在 CI 脚本、告警通知、工单系统中按需拼接 URL自动打开某个特定会话视图。深链接 URL 语法深链接的基本格式如下/sessions?query{key}{value}其中{key}是可查询的会话属性名{value}是对应的匹配值。query参数支持多个表达式组合逻辑关系通过 URL 编码后的空格与关键字表达。逻辑组合AND 与 OR逻辑运算符AND与OR直接内建于查询字符串中运算符两侧需要用空格分隔而空格在 URL 中必须编码为%20与AND/sessions?query{key1}{value1}%20AND%20{key2}{value2}或OR/sessions?query{key1}{value1}%20OR%20{key2}{value2}隐式 AND与大多数搜索引擎一致highlight.io 的查询表达式之间默认就是 AND 关系因此以下两种写法完全等价/sessions?query{key1}{value1}%20AND%20{key2}{value2} /sessions?query{key1}{value1}%20{key2}{value2}该行为同样体现在后端语法层面查询语法定义SearchGrammar.g4中显式提供了implicit_and_op规则即两个表达式之间即使没有书写任何运算符也会按 AND 语义解析。可用属性与运算符可查询的会话属性完整清单SDK 自动注入的属性见会话搜索文档的 Autoinjected attributes 一节例如identifier、email、visited-url、has_errors、active_length等。运算符与通配符、正则等更完整的通用搜索规则见 Search docs例如、!、、、*通配、/regex/正则、exists存在性判断以及括号分组。深链接实战示例以下示例均来自官方文档可直接复制使用注意 URL 中空格需编码为%20。查看某个特定用户的会话按identifier精确匹配/sessions?queryidentifieraliceexample.com排除本组织域名下的会话使用!与通配符*反向过滤/sessions?queryidentifier!*yourdomain.com*查看访问过应用内某个页面的会话按visited-url通配匹配/sessions?queryvisited-url*/your/path/name*同时过滤多个属性隐式 AND注意%20编码/sessions?queryidentifierBob%20email!aliceexample.com该示例等价于identifierBob AND email!aliceexample.com即同时满足用户标识为 Bob且邮箱不是 aliceexample.com两个条件。底层原理查询字符串如何变成 SQL深链接 URL 中的query参数并非黑盒魔法它最终会经历一条完整的解析链路URL 参数 → GraphQL 查询变量 → 词法/语法解析 → SQL 条件 → ClickHouse 执行。理解这条链路有助于你构造更精确的查询。ANTLR 语法驱动的解析器后端使用 ANTLR4 定义了一整套搜索语法SearchGrammar.g4支持大小写不敏感的AND/OR/NOT/EXISTS关键字、/!/////:二元运算符、()分组、引号包裹的字符串以及隐式 AND。语法规则implicit_and_search_expr第 29 行正是文档中默认 AND这一约定的语法级实现。入口函数在 parser.goAssignSearchFilters接收原始查询字符串构建 ANTLR 输入流与词法/语法解析器遍历语法树后将结果写入 SQL 构建器Parse则封装了从查询字符串到过滤条件Filters的最小链路。可以推断前端深链接 URL 中的query值正是沿此路径进入后端并最终作用于会话检索的。ClickHouse 字段映射解析出的查询键最终会映射到 ClickHouse 会话表的具体列。在 sessions.go 的fieldMap中可以看到一组明确的映射关系例如查询键深链接中的 keyClickHouse 列pages_visitedPagesVisitedidentifiedIdentifiedidentifierIdentifiercityCitycountryCountryos_nameOSNamebrowser_nameBrowserNamehas_commentsHasCommentshas_rage_clicksHasRageClickshas_errorsHasErrorslengthLengthactive_lengthActiveLengthenvironmentEnvironmentfirst_timeFirstTimevisited_urlVisitedURLservice_nameServiceNameservice_versionServiceVersion这意味着深链接中使用的键名必须与fieldMap中的查询键一致或属于 SDK 自动注入/自定义属性否则无法命中对应列。文档中的visited-url在底层即映射到VisitedURL列用于存储用户访问过的页面 URL。深链接中的可查询会话属性构造深链接前需要知道哪些键可以直接使用。highlight.io 的 SDK 默认会自动注入一组属性详见会话搜索文档的 Autoinjected attributes 表格包括属性含义示例值active_length用户活跃时长毫秒10mbrowser_name/browser_version用户浏览器及其版本Chrome/124.0.0.0city/state/country用户地理位置San Francisco/Virginia/Greececompleted会话是否已结束录制truedevice_id用户设备指纹1018613574environmentSDK 中指定的环境productionfirst_time是否用户首个会话falsehas_comments是否有人评论过该会话truehas_errors会话是否关联错误truehas_rage_clicks会话中是否存在 rage clicktrueidentified会话是否成功识别用户falseidentifier传给H.identify()的用户标识1ip用户 IP 地址127.0.0.1length会话总时长10mos_name/os_version用户操作系统及版本Mac OS X/10.15.7pages_visited会话内访问页面数10sample抽样排序用的唯一种子c1c9b1137183cbb1service_versionSDK 指定的服务版本e1845285cb360410aee05c61dd0cc57f85afe6daviewed_by_anyone/viewed_by_me会话是否被查看过true/false除自动注入属性外你还可以按H.track()传入的自定义属性、H.identify()传入的用户元数据以及用户点击行为clickSelector、clickInnerText进行过滤具体说明见 session-search.md。在深链接中使用这些键时规则完全一致。注意事项与实用技巧URL 编码URL 中不允许出现裸空格任何表达式之间的空格都必须编码为%20若值本身包含空格、冒号:、等号等特殊字符例如 URL 值https://app.highlight.io/建议用引号包裹值以避免解析歧义例如visited-urlhttps://app.highlight.io/。默认结果范围会话搜索默认只展示已完整处理的会话completedtrue对于会话较少的新项目会展示全部会话并给出示例查询completed(true or false)。默认键当表达式不带键名时如直接输入highlight会自动展开为对多个默认属性做匹配等价于email*highlight* OR city*highlight*这类表达式。实时会话在深链接中使用completedfalse可以直达实时live会话列表。抽样种子sample键用于对会话进行稳定抽样排序页面上的 New Random Seed 按钮会生成新的 16 位十六进制种子值你也可以在深链接中自行指定。时长过滤length与active_length支持时间后缀s、m、h例如length10m可找出所有超过 10 分钟的会话可用在深链接中快速筛选长会话。测试验证仓库中的QuerySessionIdsDeprecated、QuerySessionHistogramDeprecated等实现见 sessions.go与相关测试用例如 sessions_test.go覆盖了会话查询的执行链路可作为理解深链接查询行为的参考。小结会话搜索深链接是 highlight.io 将搜索状态编码进 URL 的能力一条query参数即可携带完整的过滤逻辑AND / OR / 隐式 AND可以被分享、收藏也能被脚本程序化生成。通过本文介绍的 URL 语法、示例与底层解析原理ANTLR 语法 → Go 解析器 → ClickHouse 字段映射你现在可以手动构造并分享任意会话搜索链接在自动化场景中按规则拼接 URL直达指定搜索结果结合 session-search.md 与 search.md 使用更丰富的运算符、通配符与分组语法构造更复杂的深链接查询。赞分享可观测性后端【免费下载链接】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点击查看免费下载相关推荐highlight.io 会话搜索实战指南基于 Track、Identify、点击与访问 URL 的 Session 查询highlight.io 会话搜索实战指南基于 Track、Identify、点击与访问 URL 的 Session 查询 highlight.io 的会话可观测性后端ReactXP 深链接Deep Linking全解析Linking API 的入站与出站通信实战指南ReactXP 深链接Deep Linking全解析Linking API 的入站与出站通信实战指南 导读 本文基于 ReactXP 官方文档中的 Lin跨平台前端highlight.io 会话回放Session Replay完全指南录制、搜索、隐私与性能优化highlight.io 会话回放Session Replay完全指南录制、搜索、隐私与性能优化 本篇技术指南基于开源仓库 highlight.io ht可观测性后端创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考