可观测性后端【免费下载链接】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 Replay、日志Logs、错误监控Errors、分布式追踪Traces与事件Events等全部产品页面上共享同一套统一的搜索查询语法。本文以官方 Search 文档 为骨架系统讲解这套语法的表达式构成、键值规则、通配符与正则、比较运算符、逻辑组合与分组技巧并结合仓库中的 ANTLR 文法、查询解析器与 SQL 监听器等源码实现揭示每条查询在服务端是如何被解析、翻译并最终落成 ClickHouse 查询的帮助你在各模块中写出精准、高效、可复用的搜索表达式。基本语法表达式与键值对一个搜索查询由一个或多个表达式expression组成。每个表达式可以是键key与值value之间的比较也可以是多个表达式的逻辑组合。最简单的形式是span_namegorm.Query这条查询的含义是筛选出所有span_name属性等于gorm.Query的追踪 span。键在等号左侧值在等号右侧。无键搜索与默认键你还可以省略键直接输入一个值此时查询会作用于该数据类型的默认键default keygorm.Query不同产品模块的默认键不同详见本文最后一节日志Logs默认键是message因此直接输入graphql request等价于message*graphql request*追踪Traces默认键是span_name因此直接输入gorm.Query等价于span_name*gorm.Query*会话Sessions默认键会跨多个属性搜索包括用户标识符email、device_id、identifier以及地理位置city、country等。这一行为在源码中有明确体现监听器在进入body_search_expr规则时会自动把当前键切换到tableConfig.BodyColumn即各模块配置的默认键列参见 listener/listener.go 中的EnterBody_search_expr。自定义属性过滤你在 SDK 中随会话、日志和追踪发送的任何自定义属性custom attributes都可以作为过滤键使用user_id42例如日志模块中logger.info(Queried table, { table: users, query: hello })产生的table:users与query:hello属性都可以直接用tableusers、queryhello来检索。键与值的规则键key是标识符可以包含字母数字字符以及下划线_、句点.、连字符-和星号*的任意组合。这在 antlr/SearchGrammar.g4 的ID词法规则中得到了印证ID : [A-Z_0-9.\-*] ;值value可以包含任意字符。如果值中包含空格或特殊字符必须用引号或包裹。需要说明的是从文法定义看除双引号、单引号外反引号同样被识别为字符串定界符STRING : ( ( \\ | ~[] )* | \ ( \\\ | ~[] )* \) | ( \\ | ~[] )* ;对应的反引号示例some value with spaces通配符匹配你可以使用*匹配值的部分模式。例如span_namegorm.*—— 匹配所有以gorm.开头的span_name值span_name*.Query—— 匹配所有以.Query结尾的span_name值span_name*orm*—— 匹配所有包含orm的值。如果通配符值中包含空格或特殊字符同样需要加引号tag*query error* visited-urlhttps://app.highlight.io/*源码层面的实现细节在 listener/listener.go 的appendRules中包含*的值会进入通配符分支调用wildcardValue进行转换func wildcardValue(value string) string { value strings.ReplaceAll(strings.ReplaceAll(value, _, \\_), *, %) if !strings.HasPrefix(value, %) { value % value } if !strings.HasSuffix(value, %) { value value % } return value }也就是说*会被替换为 SQL 的%下划线_会被转义为\_避免误匹配并且前后未显式写%的位置会被自动补齐。最终生成的查询是ILIKE形式的包含匹配例如visited-urlhttps://app.highlight.io/*最终会变成类似visited-url ILIKE %https://app.highlight.io/%的条件。正则表达式匹配你可以使用 matches 查询运算符/[your regex here]/来执行正则搜索。值的开头与结尾各加一个/即表示正则模式clickTextContent/\w.\w/—— 匹配所有以任意单词字符开头和结尾的clickTextContentbrowser_version/\d\.\d\.\d/—— 匹配所有形如[0-9].[0-9].[0-9]的浏览器版本。包含空格或特殊字符的正则同样需要引号包裹tag/\w \w/ visited-url/https://app.highlight.io/\d/./源码层面的实现细节在监听器中当值以/开头并以/结尾时会被识别为正则分支去除首尾/后对固定列生成column REGEXP value对扩展属性生成getAttributeFilterExpr(..., OperatorRegExp, ...)表达式参见 listener/listener.go 的appendRules。仓库自带的Unquote单测覆盖了引号与转义的处理逻辑见 listener/listener_test.go。比较运算符比较通过运算符完成。支持以下运算符运算符含义等于!不等于小于小于或等于大于大于或等于这些运算符在 antlr/SearchGrammar.g4 中被定义为bin_op规则!单独出现时不会被当作合法运算符从而避免解析错误bin_op : WS* (BANG | EQ | NEQ | GT | GTE | LT | LTE | COLON) WS* ;其中COLON:也被接受为比较运算符。在监听器中:与、!走同一套等值处理逻辑见appendRules中s.currentOp : || s.currentOp || s.currentOp !的分支。仓库中的 backend/queryparser/queryparser.go 同样演示了key:value形式查询的拆分方式其测试覆盖了多值、含冒号的值、引号空格值、通配符等场景见 queryparser_test.go。数值与时间后缀对于duration、length这类时长属性运算符右侧可以使用时间后缀。从 listener/listener.go 的实现看支持的后缀及其纳秒换算因子如下后缀含义h小时m分钟s秒ms毫秒us微秒ns纳秒不同列的基准单位由timeMetrics表决定Duration以纳秒ns为基准Length与ActiveLength以毫秒ms为基准。NumericValue会把带后缀的值按列基准单位换算为纯数字例如duration1s length10m active_length5m前者匹配所有时长超过 1 秒的 span后两者筛选时长超过 10 分钟/5 分钟的活动会话。NumericValue的换算行为由 listener/listener_test.go 中的TestNumericValue用例逐项验证例如10s在Duration列下换算为10000000000在Length列下换算为10000。存在与不存在exists / not exists你可以用exists运算符判断某个键是否存在。例如想找出所有关联了会话的追踪可以写secure_session_id existsexists还可以与not关键字组合使用。例如在追踪中只想看根级 span没有父 span 的 spanparent_span_id not exists源码层面的实现细节文法中exists_op同时接受EXISTS与NOT EXISTS两种形式见 antlr/SearchGrammar.g4。在监听器ExitExists_op中EXISTS被转换为等值判断的反向语义对应! 即存在非空值NOT EXISTS被转换为 即值为空/不存在并进一步包裹为NOT (...)规则。逻辑组合AND、OR、NOT表达式之间可以使用逻辑运算符AND、OR、NOT进行组合AND—— 两侧表达式都必须为真OR—— 至少一个表达式为真NOT—— 后随的表达式必须为假。注意隐式 AND除非你显式书写OR否则所有过滤器之间默认是AND关系。例如service_nameprivate-graph span_namegorm.Query完全等价于service_nameprivate-graph AND span_namegorm.Query从文法看search_expr规则显式包含implicit_and_op空产生式分支即相邻表达式之间默认按 AND 结合见 antlr/SearchGrammar.g4 的implicit_and_search_expr。此外文法声明了options { caseInsensitive true; }因此AND、OR、NOT、EXISTS等关键字大小写不敏感。监听器在ExitAnd_col_expr、ExitOr_col_expr、ExitNegated_col_expr等回调中把收集到的 SQL 规则分别用And(...)、Or(...)、NOT (...)合并并同步构造出对应的FilterOperation树Operator 为OperatorAnd/OperatorOr/OperatorNot供上层程序化地读取和复用过滤条件。分组表达式表达式可以用圆括号(和)分组从而控制运算优先级(key1value1 AND key2value2) OR key3value3你也可以用括号把某个键的多个取值分组service_name(private-graph OR public-graph)后者等价于service_nameprivate-graph OR service_namepublic-graph在需要针对同一个键筛选多个候选值时非常实用。查询示例汇总以下都是合法的高质量搜索查询示例覆盖了本文介绍的大部分语法要素service_nameprivate-graphservice_namepublic-graph AND span_name!gorm.Queryservice_nameworker OR span_namegorm.Queryservice_name!private-graph(service_namepublic-graph AND span_namegorm.Query) OR duration100000第 5 条将服务 span 名作为一组再与时长大于等于 100000 纳秒做 OR演示了括号在复杂业务场景中的用法。搜索分段Search SegmentsHighlight 的所有搜索页面都允许你保存搜索并在之后随时复用这类已保存的搜索被称为segments搜索分段。你可以把常用的过滤器组合例如线上环境 出错的会话、private-graph 服务的慢 span保存为 segment在会话、日志、错误、追踪等页面之间统一复用避免每次重新输入查询条件。特殊字符处理当值中包含特殊字符时必须用引号包裹。特殊字符包括空格运算符字符!、、:、、圆括号(和)。例如 URL 中通常同时包含:与直接写会干扰解析因此要写成visited-urlhttps://app.highlight.io/sessions带括号或比较符号的属性值同样建议引号包裹例如tag(error)、messagecode500。源码级解析原理从查询字符串到 ClickHouse SQL了解完语法之后我们来打通输入 → 解析 → SQL这条完整的调用链这部分逻辑集中在 backend/parser 目录。1. 文法定义ANTLR查询语言由 antlr/SearchGrammar.g4 定义规则覆盖了本文介绍的全部语法要素search_expr带显式/隐式 AND、OR、NOT、括号、key_val_search_expr键 二元运算符 值、exists_search_exprexists / not exists、body_search_expr无键表达式等。该文法在编译期生成 Go 版词法/语法分析器backend/parser/antlr/目录下的searchgrammar_lexer.go、searchgrammar_parser.go等。2. 入口函数backend/parser/parser.go 提供了两个核心入口GetSearchFilters(query, tableConfig, listener)创建 ANTLR 输入流、词法分析器、语法分析器用ParseTreeWalkerDefault遍历语法树驱动监听器逐步构建过滤条件最后返回listener.FiltersParse(query, tableConfig)便捷封装内部先构造一个临时的SelectBuilder再调用AssignSearchFilters。其中值得注意的一点是每个表的配置TableConfig会附带一个默认过滤条件。在GetSearchFilters中如果查询里没有出现指标名保留键就会自动拼上tableConfig.DefaultFilterif !strings.Contains(query, string(modelInputs.ReservedTraceKeyMetricName)) { query query tableConfig.DefaultFilter }这正是会话页面默认只看已完成会话completedtrue这类行为的实现来源。3. 表配置与键映射TableConfig定义于 backend/model/model.go#L2494它决定了键到实际列/属性的映射方式type TableConfig struct { TableName string BodyColumn string SeverityColumn string AttributesColumns []ColumnMapping // A prefix - column mapping AttributesTable string MetricColumn *string KeysToColumns map[string]string ArrayColumns map[string]bool ReservedKeys []string SelectColumns []string DefaultFilter string IgnoredFilters map[string]bool }KeysToColumns把已知键映射到 ClickHouse 固定列未映射到的键会被当作扩展属性extended attribute key处理走属性过滤分支AttributesColumns通过前缀匹配GetAttributesColumn把自定义属性解析到对应的列。4. 过滤条件到 SQL 的翻译在 listener/listener.go 的appendRules中不同类型键值的翻译策略各不相同默认键BodyColumn纯字母数字的值生成hasTokenCaseInsensitive(column, value)ClickHouse 分词级不区分大小写包含匹配含特殊字符的值则走wildcardValueILIKE固定列生成toString(column) value保证字符串语义大小比较直接使用,,,扩展属性列调用getAttributeFilterExpr生成基于 ClickHousearrayFilter的表达式如notEmpty(arrayFilter((k, v) - k key AND v value, column))大小比较还会用toFloat64OrNull(...)包裹以保证数值语义!运算符在ExitKey_val_search_expr中被转换为NOT (...)包裹形式语义上等价于键值不等于。5. 测试验证解析逻辑有完整的单测支撑listener/listener_test.go覆盖Unquote引号剥离与转义还原与NumericValue时间后缀换算等关键函数queryparser/queryparser_test.go覆盖无键正文、通配符转%、多值属性、含冒号值、引号空格值等解析场景。各产品模块的专属搜索上述语法在所有模块通用但每个模块都结合自己的数据结构与自动注入属性做了定制。各模块的完整指南见Session Search会话搜索Error Search错误搜索Log Search日志搜索Trace Search追踪搜索Event Search事件搜索下面提炼几个模块的关键差异点方便快速上手。会话搜索默认键跨多属性无键输入会同时作用于email、device_id、identifier、city、country等多个属性例如输入highlight等价于email*highlight* OR city*highlight*点击行为检索SDK 记录clickSelector元素 tag/id/class 拼接的选择器与clickInnerText元素文本最多前 2000 字符可搜索clickSelectorsvg、clickTextContentLast 30 days访问 URL 检索使用visited-url过滤键例如visited-urlhttps://app.highlight.io/配合通配符/正则可实现visited-url*sessions*、visited-url/.\d/sessions./常用自动注入属性active_length、browser_name、browser_version、city、completed、country、device_id、environment、first_time、has_comments、has_errors、has_rage_clicks、identified、identifier、ip、length、os_name、os_version、pages_visited、sample、service_version、state、viewed_by_anyone、viewed_by_me等。其中completedfalse可查看实时live会话。日志搜索默认键为message输入excluding session due to no user interaction events即可找到log.info(excluding session due to no user interaction events)这条日志常用自动注入属性code.filepath、code.function、code.lineno、environment、host.name、level、message、os.description、os.type、secure_session_id、service_name、service_version、source、span_id、trace_id等实用技巧用secure_session_id EXISTS过滤出所有与会话关联的日志。追踪搜索默认键为span_name常用自动注入属性duration纳秒、environment、has_errors、highlight.type、parent_span_id、secure_session_id、service_name、service_version、span_kind、span_name、trace_id等实用技巧用trace_id过滤可看到单个 trace 的所有 span 表格视图点击 span 可查看含火焰图的信息用duration1s筛选超过 1 秒的慢 span用secure_session_id EXISTS只看与会话关联的 span。在搜索框输入时界面会给出可用属性键的联想建议。小结highlight.io 的搜索语法在表达能力与易用性之间做了很好的平衡keyvalue的直观键值比较、*通配符与/regex/正则的灵活匹配、exists / not exists的存在性判断、AND / OR / NOT与括号的完备逻辑组合再加上各模块的默认键与自动注入属性几乎可以覆盖全栈监控场景下的一切检索需求。而在服务端这段查询字符串会经由 ANTLR 文法解析、SearchListener 规则回调、TableConfig 键映射最终被翻译为针对 ClickHouse 列与属性数组的精确 SQL 条件——理解这层实现能帮助你预测查询的执行形态写出更符合预期的表达式。赞分享可观测性后端【免费下载链接】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点击查看免费下载相关推荐Hound正则表达式搜索5个高级查询语法完全指南Hound正则表达式搜索5个高级查询语法完全指南 Hound是一款闪电般快速的代码搜索引擎专门为开发者提供高效的正则表达式搜索功能。这款开源工具基于Go语言搜索引擎开发者工具后端前端Kibana搜索语法正则表达式与模糊查询Kibana搜索语法正则表达式与模糊查询 在日常数据检索中你是否遇到过拼写错误导致搜索结果为空或者需要查找具有相似格式的数据却不知从何下手本文将详细介绍前端数据可视化数据分析后端可观测性掌握Sourcebot搜索语法正则表达式与布尔逻辑完全指南掌握Sourcebot搜索语法正则表达式与布尔逻辑完全指南 Sourcebot是一款自托管工具帮助开发者和AI智能体快速理解代码库。其强大的搜索功能支持正则上一篇一台旧电视盒子搞定全家打印用 amlogic-s9xxx-armbian 搭建 CUPS 网络打印服务器的完整教程下一篇MNN 内置 FlatBuffers 二进制格式内部原理偏移、vtable 与 FlexBuffers 编码全解析创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
