在 Grafana 中使用 Tempo TraceQL 查询编辑器三种查询模式、流式结果与仪表盘实战【免费下载链接】tempoGrafana Tempo is a high volume, minimal dependency distributed tracing backend.项目地址: https://gitcode.com/GitHub_Trending/tempo1/tempo导读本文基于 Grafana Tempo 仓库中的官方文档 docs/sources/tempo/traceql/query-editor/_index.md系统讲解如何在 Grafana 的 Explore 与 Tempo 数据源中使用TraceQL 查询编辑器包括 Search 查询构建器、TraceQL 代码编辑器、Service Graph 视图三种查询模式以及查询结果流式传输Streaming的配置与底层实现。读完本文你将掌握在 Grafana 中组合 TraceQL 查询、按 Trace ID 检索、开启流式查询并在仪表盘中使用 Traces 面板的完整实战方案并能结合仓库源码理解stream_over_http_enabled等关键配置的实际作用。一、背景为什么要在 Grafana 中编写 TraceQL 查询TraceQL 是 Grafana Tempo 专门为链路追踪设计的一门查询语言它面向「一次评估一条 trace」的语义通过由条件与聚合函数组成的管道pipeline来筛选 spanset。TraceQL 的详细语法与语义见 docs/sources/tempo/traceql/_index.md 与 docs/sources/tempo/traceql/construct-traceql-queries.md。在 Grafana 中TraceQL 的落地场景是Explore 页面 Tempo 数据源你可以直接编写 TraceQL 文本查询借助**自动补全autocomplete**获得字段与属性提示也可以使用Search 查询构建器通过下拉菜单与输入框以「低代码」方式生成 TraceQL 查询适合不熟悉语法或正在学习 TraceQL 的开发者还可以使用Service Graph 视图直接观察服务间的调用关系与 RED 信号。查询在 Tempo 数据源的 query editor 中完成最终都会转化为一条 TraceQL 表达式提交给 Tempo 后端执行。Tempo 查询引擎按 trace 为单位评估管道若某条 trace 的管道产出了 spanset则该 trace 进入结果集——这与 docs/sources/tempo/traceql/construct-traceql-queries.md 中「{ }选取 spanset、条件逐 span 求值」的模型完全一致。二、三种查询模式Query Types总览Tempo 数据源的 query editor 提供三种可以单独或组合使用的Query type它们构成了探索链路数据的三种视角查询模式交互方式适用人群Search 查询构建器下拉列表 文本字段可视化拼装条件不熟悉 TraceQL、想快速上手的学习者TraceQL 查询编辑器类代码编辑体验带自动补全已掌握或正在学习 TraceQL 语法的开发者Service Graph 视图预配置的可视化服务关系图需要全局观察服务依赖与 RED 信号的运维/研发这三种模式本质上是同一套 TraceQL 能力的三种表达方式Search 构建器生成查询文本TraceQL 编辑器直接编辑查询文本Service Graph 则消费 metrics-generator 产出的服务图数据。你可以先用构建器拖出骨架再切到 TraceQL 编辑器微调形成「积木式」的组合工作流。2.1 Search 查询构建器Search 查询构建器面向「不熟悉或正在学习 TraceQL」的用户通过下拉框与文本框即可组合出合法查询。典型界面如下构建器会实时把可视化条件翻译为 TraceQL 文本。例如选择resource.service.name、span name、duration等条件后页面底部会生成类似{resource.service.namemythical-requester}的查询表达式。这意味着构建器本身也是学习 TraceQL 语法的天然教具任何你拖出来的条件都能看到它对应的文本写法。2.2 TraceQL 查询编辑器TraceQL 查询编辑器提供类代码的编辑体验核心能力是autocomplete自动补全。当你在编辑器中输入http这类前缀时会弹出以该前缀开头的可用属性列表如http.flavor、http.host等直接点选即可完成字段输入除了编写 TraceQL 查询编辑器还支持一个高频操作在查询字段中直接输入 Trace ID 进行检索。当你不确定怎么写查询、只想快速定位某条具体 trace 时把 trace ID 粘进查询框即可直达该 trace 的详情页。查询执行后结果会在界面中以 Trace 列表与单条 trace 的节点图形式呈现你可以展开任意 span 查看其属性、时间轴与调用关系2.3 Service Graph 视图Service Graph 视图基于metrics由 Tempo metrics-generator 聚合出的服务图与 span 指标展示服务间的调用关系而不是直接查询 trace。只要完成 metrics-generator 的相关配置这个预配置视图即可直接可用。它帮助你发现持续报错的 span 及其发生频率总览整个服务中 span 调用的整体速率判断服务中最慢查询的耗时基于速率、错误与耗时即 RED 信号定位感兴趣的所有相关 trace。因此 Service Graph 视图非常适合先做全局巡检再下钻到具体 trace 的排查路径。更完整的说明见 docs/sources/tempo/traceql/query-editor/_index.md 中的 Service graph view 小节。三、流式查询结果Stream query results这是查询编辑器与后端配合的一项关键能力查询结果可以流式streaming传输到客户端让你在整条查询完成前就能先看到已匹配的 trace显著缩短「等待出结果」的体验。3.1 原理查询前端的 GRPC 流式端点从源码看Tempo 查询前端query frontend实现了tempopb.StreamingQuerier服务接口注册了多个流式 handler见 modules/frontend/frontend.gostreamingSearch—— 流式搜索对应 TraceQL 搜索streamingTags/streamingTagsV2—— 流式查询 tag 列表streamingTagValues/streamingTagValuesV2—— 流式查询 tag 取值streamingQueryRange/streamingQueryInstant—— 流式 TraceQL 指标查询这些 handler 在 modules/frontend/frontend.go 中统一接线客户端通过 GRPC 流式接口持续接收分批返回的匹配结果。3.2 关键配置stream_over_http_enabled要在 Grafana 中使用流式查询必须在 Tempo 中开启stream_over_http_enabled: true该配置项定义于 Tempo 主配置结构体 cmd/tempo/app/config.goStreamOverHTTPEnabled bool yaml:stream_over_http_enabled,omitempty它同时出现在仓库内多份真实部署配置中例如 example/docker-compose/single-binary/tempo.yaml 与 tools/packaging/tempo.yaml可作为开箱示例参考。GRPC API 的流式端点细节见 docs/sources/tempo/api_docs/_index.md。3.3 客户端侧的使用Grafana 与 tempo-cli除了 Grafana Exploretempo-cli也通过同一流式端点发起查询。其query api子命令支持--use-grpc标志例如按 TraceQL 搜索并走 GRPC 流式通道tempo-cli query api search --use-grpc --org-id my-org localhost:3200 {span.http.status_code 400} now-1h now更多命令形态含--header携带 token、now-1h相对时间、ISO 8601 绝对时间等见 docs/sources/tempo/operations/tempo_cli.md。3.4 流式相关的服务端调优参数流式行为还受到 query frontend 配置块的几个参数影响见 modules/frontend/docs/config-reference.md 中的配置参考query_frontend: most_recent_shards: 200 # most_recent 搜索的分片数默认 200 streaming_shards: 200 # 流式搜索的分片数默认 200 max_grpc_streaming_packet_size: 1048576 # 单次 GRPC 流式响应包上限字节其中max_grpc_streaming_packet_size定义于 modules/frontend/config.go控制流式响应的单包大小most_recent_shards则与 TraceQL 的with (most_recenttrue)查询提示配合使用用于把搜索按时间窗口分片并保留最新候选结果。四、结合 TraceQL 语法在查询编辑器中写出高质量查询查询编辑器是对 TraceQL 语法的直接承载。以下要点来自 docs/sources/tempo/traceql/construct-traceql-queries.md与编辑器内的自动补全行为一一对应可帮助你写出更精准、更高效的查询。4.1 最小查询与管道结构{ }空花括号{ }匹配所有 span。查询由若干通过|连接、再由组合条件的表达式构成管道每条 trace 中若管道产出 spanset即进入结果。例如{ span.http.status_code 200 span.http.status_code 300 } | count() 2表示「HTTP 状态码在 200~299 之间且 trace 内匹配 span 数大于 2」的 trace。4.2 内建字段intrinsics与自定义属性attributes内建字段用冒号分隔如span:duration、trace:duration、trace:rootService、span:childCount自定义属性用点号分隔并带作用域前缀如span.http.method、resource.service.name、event.exception.message、link.traceID。完整的内建字段表含类型、定义与示例见 docs/sources/tempo/traceql/construct-traceql-queries.md 的 Intrinsic fields 小节。性能建议trace:duration、trace:rootName、trace:rootService等 trace 级内建字段只需检查少量数据比 span 级内建字段更高效能使用时应优先使用。4.3 常用实战查询示例在查询编辑器中可直接运行的典型查询均可作为起点改造# 定位特定操作 {resource.service.name frontend name POST /api/orders} # 查找出错的 spanstatus 枚举error / ok / unset {resource.service.name frontend name POST /api/orders status error} # 跨多个 span 的组合条件两个花括号分别作用于不同 span {resource.deployment.environment production} {span.http.status_code 200} # 结构操作符frontend 服务的后代中有 error span {resource.service.namefrontend} {status error} # 聚合错误数超过 1 的服务 {status error} | by(resource.service.name) | count() 1 # 选择字段字段在满足所有条件后才被检索性能友好 {status error} | select(span.http.status_code, span.http.url) # 获取最新结果实验性查询提示 {} with (most_recenttrue)4.4 正则与数组语义TraceQL 使用 Go 正则且默认全量锚定{ span.foo ~ bar }等价于{ span.foo ~ ^bar$ }如需子串匹配应写成.*bar.*数组属性vParquet4支持逐元素匹配/~匹配任意一个元素!/!~仅当没有任何元素满足时才匹配支持minInt/maxInt常量、ns/us/ms/s/m/h时长单位、nil/! nil判空等字面量语义。五、在仪表盘中使用 TraceQL 面板除了 Explore 的临时查询TraceQL 也可以沉淀到仪表盘使用Traces 面板Traces panel visualization把 TraceQL 查询结果展示为可视化面板适合将日常巡检的查询固化为团队共享的监控视图仪表盘的整体组织、变量与时间范围管理遵循 Grafana 通用的 dashboard 使用方式。如果你不想手写查询Grafana 的Traces Drilldown提供了免写查询的探索路径可直接下钻查看 trace 数据——这适合「先看趋势再写查询」的工作流。六、配置清单与注意事项综合官方文档与仓库源码在 Grafana 中使用 TraceQL 查询编辑器前建议核对以下清单事项说明依据Tempo 数据源在 Grafana 中配置指向 Tempo 的数据源用于 Explore 与面板docs/sources/tempo/traceql/query-editor/_index.md流式查询stream_over_http_enabled: true否则查询结果不会流式返回cmd/tempo/app/config.go存储格式TraceQL 依赖 Parquet 列式格式Tempo 默认块格式docs/sources/tempo/traceql/_index.md查询前端调优most_recent_shards、streaming_shards、max_grpc_streaming_packet_sizemodules/frontend/docs/config-reference.md数组属性数组查询需 vParquet4 及以上span:childCount需 vParquet5 及以上docs/sources/tempo/traceql/construct-traceql-queries.md七、进一步阅读TraceQL 语言总览docs/sources/tempo/traceql/_index.md查询结构与完整语法参考docs/sources/tempo/traceql/construct-traceql-queries.mdTrace 结构与 span 层级docs/sources/tempo/traceql/trace-structure.md查询性能调优docs/sources/tempo/traceql/tune-traceql-queries.md命令行查询含--use-grpc流式通道docs/sources/tempo/operations/tempo_cli.md【免费下载链接】tempoGrafana Tempo is a high volume, minimal dependency distributed tracing backend.项目地址: https://gitcode.com/GitHub_Trending/tempo1/tempo创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
在 Grafana 中使用 Tempo TraceQL 查询编辑器：三种查询模式、流式结果与仪表盘实战
在 Grafana 中使用 Tempo TraceQL 查询编辑器三种查询模式、流式结果与仪表盘实战【免费下载链接】tempoGrafana Tempo is a high volume, minimal dependency distributed tracing backend.项目地址: https://gitcode.com/GitHub_Trending/tempo1/tempo导读本文基于 Grafana Tempo 仓库中的官方文档 docs/sources/tempo/traceql/query-editor/_index.md系统讲解如何在 Grafana 的 Explore 与 Tempo 数据源中使用TraceQL 查询编辑器包括 Search 查询构建器、TraceQL 代码编辑器、Service Graph 视图三种查询模式以及查询结果流式传输Streaming的配置与底层实现。读完本文你将掌握在 Grafana 中组合 TraceQL 查询、按 Trace ID 检索、开启流式查询并在仪表盘中使用 Traces 面板的完整实战方案并能结合仓库源码理解stream_over_http_enabled等关键配置的实际作用。一、背景为什么要在 Grafana 中编写 TraceQL 查询TraceQL 是 Grafana Tempo 专门为链路追踪设计的一门查询语言它面向「一次评估一条 trace」的语义通过由条件与聚合函数组成的管道pipeline来筛选 spanset。TraceQL 的详细语法与语义见 docs/sources/tempo/traceql/_index.md 与 docs/sources/tempo/traceql/construct-traceql-queries.md。在 Grafana 中TraceQL 的落地场景是Explore 页面 Tempo 数据源你可以直接编写 TraceQL 文本查询借助**自动补全autocomplete**获得字段与属性提示也可以使用Search 查询构建器通过下拉菜单与输入框以「低代码」方式生成 TraceQL 查询适合不熟悉语法或正在学习 TraceQL 的开发者还可以使用Service Graph 视图直接观察服务间的调用关系与 RED 信号。查询在 Tempo 数据源的 query editor 中完成最终都会转化为一条 TraceQL 表达式提交给 Tempo 后端执行。Tempo 查询引擎按 trace 为单位评估管道若某条 trace 的管道产出了 spanset则该 trace 进入结果集——这与 docs/sources/tempo/traceql/construct-traceql-queries.md 中「{ }选取 spanset、条件逐 span 求值」的模型完全一致。二、三种查询模式Query Types总览Tempo 数据源的 query editor 提供三种可以单独或组合使用的Query type它们构成了探索链路数据的三种视角查询模式交互方式适用人群Search 查询构建器下拉列表 文本字段可视化拼装条件不熟悉 TraceQL、想快速上手的学习者TraceQL 查询编辑器类代码编辑体验带自动补全已掌握或正在学习 TraceQL 语法的开发者Service Graph 视图预配置的可视化服务关系图需要全局观察服务依赖与 RED 信号的运维/研发这三种模式本质上是同一套 TraceQL 能力的三种表达方式Search 构建器生成查询文本TraceQL 编辑器直接编辑查询文本Service Graph 则消费 metrics-generator 产出的服务图数据。你可以先用构建器拖出骨架再切到 TraceQL 编辑器微调形成「积木式」的组合工作流。2.1 Search 查询构建器Search 查询构建器面向「不熟悉或正在学习 TraceQL」的用户通过下拉框与文本框即可组合出合法查询。典型界面如下构建器会实时把可视化条件翻译为 TraceQL 文本。例如选择resource.service.name、span name、duration等条件后页面底部会生成类似{resource.service.namemythical-requester}的查询表达式。这意味着构建器本身也是学习 TraceQL 语法的天然教具任何你拖出来的条件都能看到它对应的文本写法。2.2 TraceQL 查询编辑器TraceQL 查询编辑器提供类代码的编辑体验核心能力是autocomplete自动补全。当你在编辑器中输入http这类前缀时会弹出以该前缀开头的可用属性列表如http.flavor、http.host等直接点选即可完成字段输入除了编写 TraceQL 查询编辑器还支持一个高频操作在查询字段中直接输入 Trace ID 进行检索。当你不确定怎么写查询、只想快速定位某条具体 trace 时把 trace ID 粘进查询框即可直达该 trace 的详情页。查询执行后结果会在界面中以 Trace 列表与单条 trace 的节点图形式呈现你可以展开任意 span 查看其属性、时间轴与调用关系2.3 Service Graph 视图Service Graph 视图基于metrics由 Tempo metrics-generator 聚合出的服务图与 span 指标展示服务间的调用关系而不是直接查询 trace。只要完成 metrics-generator 的相关配置这个预配置视图即可直接可用。它帮助你发现持续报错的 span 及其发生频率总览整个服务中 span 调用的整体速率判断服务中最慢查询的耗时基于速率、错误与耗时即 RED 信号定位感兴趣的所有相关 trace。因此 Service Graph 视图非常适合先做全局巡检再下钻到具体 trace 的排查路径。更完整的说明见 docs/sources/tempo/traceql/query-editor/_index.md 中的 Service graph view 小节。三、流式查询结果Stream query results这是查询编辑器与后端配合的一项关键能力查询结果可以流式streaming传输到客户端让你在整条查询完成前就能先看到已匹配的 trace显著缩短「等待出结果」的体验。3.1 原理查询前端的 GRPC 流式端点从源码看Tempo 查询前端query frontend实现了tempopb.StreamingQuerier服务接口注册了多个流式 handler见 modules/frontend/frontend.gostreamingSearch—— 流式搜索对应 TraceQL 搜索streamingTags/streamingTagsV2—— 流式查询 tag 列表streamingTagValues/streamingTagValuesV2—— 流式查询 tag 取值streamingQueryRange/streamingQueryInstant—— 流式 TraceQL 指标查询这些 handler 在 modules/frontend/frontend.go 中统一接线客户端通过 GRPC 流式接口持续接收分批返回的匹配结果。3.2 关键配置stream_over_http_enabled要在 Grafana 中使用流式查询必须在 Tempo 中开启stream_over_http_enabled: true该配置项定义于 Tempo 主配置结构体 cmd/tempo/app/config.goStreamOverHTTPEnabled bool yaml:stream_over_http_enabled,omitempty它同时出现在仓库内多份真实部署配置中例如 example/docker-compose/single-binary/tempo.yaml 与 tools/packaging/tempo.yaml可作为开箱示例参考。GRPC API 的流式端点细节见 docs/sources/tempo/api_docs/_index.md。3.3 客户端侧的使用Grafana 与 tempo-cli除了 Grafana Exploretempo-cli也通过同一流式端点发起查询。其query api子命令支持--use-grpc标志例如按 TraceQL 搜索并走 GRPC 流式通道tempo-cli query api search --use-grpc --org-id my-org localhost:3200 {span.http.status_code 400} now-1h now更多命令形态含--header携带 token、now-1h相对时间、ISO 8601 绝对时间等见 docs/sources/tempo/operations/tempo_cli.md。3.4 流式相关的服务端调优参数流式行为还受到 query frontend 配置块的几个参数影响见 modules/frontend/docs/config-reference.md 中的配置参考query_frontend: most_recent_shards: 200 # most_recent 搜索的分片数默认 200 streaming_shards: 200 # 流式搜索的分片数默认 200 max_grpc_streaming_packet_size: 1048576 # 单次 GRPC 流式响应包上限字节其中max_grpc_streaming_packet_size定义于 modules/frontend/config.go控制流式响应的单包大小most_recent_shards则与 TraceQL 的with (most_recenttrue)查询提示配合使用用于把搜索按时间窗口分片并保留最新候选结果。四、结合 TraceQL 语法在查询编辑器中写出高质量查询查询编辑器是对 TraceQL 语法的直接承载。以下要点来自 docs/sources/tempo/traceql/construct-traceql-queries.md与编辑器内的自动补全行为一一对应可帮助你写出更精准、更高效的查询。4.1 最小查询与管道结构{ }空花括号{ }匹配所有 span。查询由若干通过|连接、再由组合条件的表达式构成管道每条 trace 中若管道产出 spanset即进入结果。例如{ span.http.status_code 200 span.http.status_code 300 } | count() 2表示「HTTP 状态码在 200~299 之间且 trace 内匹配 span 数大于 2」的 trace。4.2 内建字段intrinsics与自定义属性attributes内建字段用冒号分隔如span:duration、trace:duration、trace:rootService、span:childCount自定义属性用点号分隔并带作用域前缀如span.http.method、resource.service.name、event.exception.message、link.traceID。完整的内建字段表含类型、定义与示例见 docs/sources/tempo/traceql/construct-traceql-queries.md 的 Intrinsic fields 小节。性能建议trace:duration、trace:rootName、trace:rootService等 trace 级内建字段只需检查少量数据比 span 级内建字段更高效能使用时应优先使用。4.3 常用实战查询示例在查询编辑器中可直接运行的典型查询均可作为起点改造# 定位特定操作 {resource.service.name frontend name POST /api/orders} # 查找出错的 spanstatus 枚举error / ok / unset {resource.service.name frontend name POST /api/orders status error} # 跨多个 span 的组合条件两个花括号分别作用于不同 span {resource.deployment.environment production} {span.http.status_code 200} # 结构操作符frontend 服务的后代中有 error span {resource.service.namefrontend} {status error} # 聚合错误数超过 1 的服务 {status error} | by(resource.service.name) | count() 1 # 选择字段字段在满足所有条件后才被检索性能友好 {status error} | select(span.http.status_code, span.http.url) # 获取最新结果实验性查询提示 {} with (most_recenttrue)4.4 正则与数组语义TraceQL 使用 Go 正则且默认全量锚定{ span.foo ~ bar }等价于{ span.foo ~ ^bar$ }如需子串匹配应写成.*bar.*数组属性vParquet4支持逐元素匹配/~匹配任意一个元素!/!~仅当没有任何元素满足时才匹配支持minInt/maxInt常量、ns/us/ms/s/m/h时长单位、nil/! nil判空等字面量语义。五、在仪表盘中使用 TraceQL 面板除了 Explore 的临时查询TraceQL 也可以沉淀到仪表盘使用Traces 面板Traces panel visualization把 TraceQL 查询结果展示为可视化面板适合将日常巡检的查询固化为团队共享的监控视图仪表盘的整体组织、变量与时间范围管理遵循 Grafana 通用的 dashboard 使用方式。如果你不想手写查询Grafana 的Traces Drilldown提供了免写查询的探索路径可直接下钻查看 trace 数据——这适合「先看趋势再写查询」的工作流。六、配置清单与注意事项综合官方文档与仓库源码在 Grafana 中使用 TraceQL 查询编辑器前建议核对以下清单事项说明依据Tempo 数据源在 Grafana 中配置指向 Tempo 的数据源用于 Explore 与面板docs/sources/tempo/traceql/query-editor/_index.md流式查询stream_over_http_enabled: true否则查询结果不会流式返回cmd/tempo/app/config.go存储格式TraceQL 依赖 Parquet 列式格式Tempo 默认块格式docs/sources/tempo/traceql/_index.md查询前端调优most_recent_shards、streaming_shards、max_grpc_streaming_packet_sizemodules/frontend/docs/config-reference.md数组属性数组查询需 vParquet4 及以上span:childCount需 vParquet5 及以上docs/sources/tempo/traceql/construct-traceql-queries.md七、进一步阅读TraceQL 语言总览docs/sources/tempo/traceql/_index.md查询结构与完整语法参考docs/sources/tempo/traceql/construct-traceql-queries.mdTrace 结构与 span 层级docs/sources/tempo/traceql/trace-structure.md查询性能调优docs/sources/tempo/traceql/tune-traceql-queries.md命令行查询含--use-grpc流式通道docs/sources/tempo/operations/tempo_cli.md【免费下载链接】tempoGrafana Tempo is a high volume, minimal dependency distributed tracing backend.项目地址: https://gitcode.com/GitHub_Trending/tempo1/tempo创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考