StarRocks Query Detail API 完全指南通过 FE HTTP 接口获取查询执行明细【免费下载链接】starrocksThe worlds fastest open query engine for sub-second analytics both on and off the data lakehouse. With the flexibility to support nearly any scenario, StarRocks provides best-in-class performance for multi-dimensional analytics, real-time analytics, and ad-hoc queries. A Linux Foundation project.项目地址: https://gitcode.com/GitHub_Trending/st/starrocksQuery Detail API 是 StarRocks FE 提供的一组 HTTP 接口用于读取缓存于 FE 内存中的近期查询执行明细QueryDetail覆盖查询 ID、耗时、扫描行数/字节数、CPU 与内存开销、物化视图来源等维度是构建查询历史系统、慢查询排查与集群运维监控的常用数据源。本文基于官方文档 docs/en/administration/http_interface/query_detail.md 展开并结合 FE 端源码Config.java、QueryDetail.java、QueryDetailQueue.java、QueryDetailAction.java、QueryDetailActionV2.java、StmtExecutor.java深入讲解接口的调用方式、参数语义、返回字段与底层收集机制帮助你在实战中直接落地使用。接口是什么FE 内存中的查询明细缓存StarRocks 的每条语句包括查询与 DDL在执行时都会在 FE 侧构建一个QueryDetail对象记录语句的元信息与执行统计。当 FE 配置项enable_collect_query_detail_info为true时这些QueryDetail记录会被写入 FE 内存中的有界队列QueryDetailQueue.java而Query detail API的作用就是通过 HTTP 方式把这些内存缓存读取出来供外部系统如 StarRocks Manager 等查询历史/监控组件轮询拉取。从源码注释可以看到其设计定位Its used to collect queries for monitorQueryDetailQueue.java即该队列本身就是为监控场景准备的。配置项说明也印证了这一点StarRocks-manager pull queries every 1 second, metrics calculate query latency every 15 second, do not set cacheTime lower than these timeConfig.java暗示该接口面向周期性拉取的监控系统设计。前置条件开启明细收集接口能否返回数据取决于 FE 是否在收集明细。官方文档明确指出Query detail records are collected only when the FE configurationenable_collect_query_detail_infois set totrue.该配置项定义于 Config.javaConfField(mutable true) public static boolean enable_collect_query_detail_info false;关键信息默认值false即默认不收集是否动态生效Is mutable是无需重启 FE 即可修改官方参数文档见 log_server_meta.md设置为TRUE后系统开始收集查询 profile设置为FALSE则停止。有两种方式开启-- 方式一通过 SQL 动态修改推荐立即生效 ADMIN SET FRONTEND CONFIG (enable_collect_query_detail_info true);# 方式二通过 FE HTTP 接口动态修改 curl -u root: http://fe_host:fe_http_port/api/_set_config?enable_collect_query_detail_infotrue由于该配置项mutable true修改后无需重启 FE。需要注意开启后每个 FE 会为每条语句在内存中保留一份QueryDetail在大并发集群上会带来一定内存与写入开销建议仅在需要监控/排查时开启。Endpointsv1 与 v2 两个版本接口提供两个版本均注册于 FE 的 HTTP 服务默认端口fe_http_port见 conf/fe.conf 中的http_port默认 8030版本路径特点v1GET /api/query_detail返回裸的 JSON 数组v2GET /api/v2/query_detail支持is_request_all_frontend参数返回包裹结构路由注册代码位于v1QueryDetailAction.java 中controller.registerHandler(HttpMethod.GET, /api/query_detail, ...)v2QueryDetailActionV2.java 中controller.registerHandler(HttpMethod.GET, /api/v2/query_detail, ...)请求参数名称必选默认值说明event_time是-下界过滤条件仅返回eventTime大于该值的记录传0可获取当前缓存中的所有记录user否-按user字段过滤不区分大小写is_request_all_frontend否仅 v2false为true时当前 FE 会向集群内其他存活 FE 发起请求并合并结果参数校验逻辑在源码中非常明确v1 在 QueryDetailAction.java 中event_time缺失时直接返回not valid parameter与 HTTP 400v2 在 QueryDetailActionV2.java 中做了同样的空值校验。event_time的语义需要特别理解它对应的不是查询开始时间startTime而是记录被写入队列时生成的单调递增纳秒时间戳eventTime。由于查询开始时会先入队一条RUNNING状态的记录结束时更新该记录并再次入队见下文生命周期一节因此用eventTime做增量拉取incremental pull是安全的不会遗漏状态更新。响应格式v1直接返回一个QueryDetail对象的 JSON 数组[ { queryId: 9fc7108f-..., eventTime: 1753671088000000000, ... } ]v2返回统一的包裹结构{ code: 0, message: OK, result: [ { queryId: 9fc7108f-..., ... } ] }其中result为QueryDetail列表。v2 的包裹结构定义于 RestBaseResultV2同目录下构造与序列化逻辑见 QueryDetailActionV2.java。认证与授权该接口要求HTTP Basic 认证即请求必须携带合法用户名/密码如-u root:认证通过即可访问没有额外的权限校验。也就是说任何通过认证的用户都能读取全部缓存的查询明细除非通过user参数做了过滤。这一点在 v1 与 v2 的实现中都通过requireOperateIfHttpAuthEnabled()QueryDetailAction.java、QueryDetailActionV2.java保证。由于接口可能暴露任意用户的 SQL 文本在生产环境建议仅在可信内网开放 FE HTTP 端口或将enable_collect_query_detail_info保持关闭、按需临时开启。QueryDetail 字段详解QueryDetail类定义于 QueryDetail.java字段与官方文档一一对应。以下是完整字段表字段类型说明queryIdstring查询 IDeventTimelong内部时间戳用于过滤由墙钟时间派生的单调纳秒时间戳isQueryboolean语句是否为查询remoteIPstring客户端 IP非客户端请求时为SystemconnIdint连接 IDstartTimelong查询开始时间Unix 毫秒时间戳endTimelong查询结束时间Unix 毫秒时间戳未完成时为-1latencylong查询延迟毫秒未完成时为-1pendingTimelong排队等待时间毫秒netTimelong净执行时间毫秒netComputeTimelong净计算时间毫秒statestring状态之一RUNNING、FINISHED、FAILED、CANCELLEDdatabasestring当前数据库sqlstringSQL 文本如配置了脱敏则可能为脱敏文本userstring登录用户qualified userimpersonatedUserstringEXECUTE AS的目标用户未模拟其他用户时为nullerrorMessagestring失败时的错误信息explainstringExplain 计划详细程度由query_detail_explain_level控制profilestring已收集时的 Profile 文本resourceGroupNamestring资源组名称scanRowslong扫描行数scanByteslong扫描字节数returnRowslong返回行数cpuCostNslongCPU 开销纳秒memCostByteslong内存开销字节spillByteslong落盘字节数cacheMissRatiofloat缓存未命中率百分比0-100warehousestringWarehouse 名称digeststringSQL digestcatalogstringCatalog 名称commandstringMySQL 命令名称preparedStmtIdstring预编译语句 IDqueryFeMemorylong该查询在 FE 侧分配的内存字节querySourcestring查询来源EXTERNAL、INTERNAL、MV、TASK几个值得展开的字段state对应源码中的枚举QueryMemStateQueryDetail.java四个状态值与文档一致。querySource对应枚举QuerySourceQueryDetail.javaEXTERNAL用户发起的查询INTERNAL系统/内部查询MV物化视图刷新产生的语句TASK任务提交的查询。该字段可帮助你在过滤监控数据时区分用户流量与系统内部流量例如排除INTERNAL与MV以免干扰慢查询统计。注意 StmtExecutor.java 中当语句实际由内部逻辑触发时会从EXTERNAL改写为INTERNAL。cacheMissRatio由calculateCacheMissRatio(readLocalCnt, readRemoteCnt)计算QueryDetail.java(readRemoteCnt * 100) / (readLocalCnt readRemoteCnt)读远程块的比例越高缓存命中率越低。当总读取数为 0 时为 0。sql的脱敏行为在 StmtExecutor.java 中当语句需要加密AuditEncryptionChecker.needEncrypt或enable_sql_desensitize_in_log开启时SQL 会被重建为脱敏文本否则若 SQL 含凭据关键词如密码会通过SqlCredentialRedactor.redact做凭据遮蔽。因此 API 返回的sql不一定是原始文本。database的处理构造 QueryDetail 时如果数据库名形如cluster:db带 cluster 前缀会截取冒号后的部分QueryDetail.java。记录的收集生命周期从入队到过期理解接口返回的数据形态需要知道QueryDetail是如何被写入和更新的。核心流程在 StmtExecutor.java 的两个方法中查询开始时——addRunningQueryDetail(parsedStmt)L4222-L4281若enable_collect_query_detail_info为false直接返回构造QueryDetail填入 queryId、isQuery、remoteIP、connId、startTime、database、sql、user、resourceGroupName、warehouse、catalog、command、preparedStmtId状态置为RUNNING通过QueryDetailQueue.addQueryDetail(queryDetail.copy())入队注意这里入队的是copy因为后续属性会变化。查询结束时——addFinishedQueryDetail()L4294-L4345计算endTime、latencyendTime - startTime、queryFeMemory线程分配内存差值根据执行状态设置FINISHED或FAILED失败时写入errorMessage填充pendingTime、netTime、netComputeTime从执行统计PQueryStatistics填充scanRows、scanBytes、cpuCostNs、memCostBytes、spillBytes、returnRows、digest并计算cacheMissRatio再次入队更新后的完整记录。队列管理——QueryDetailQueue.java内部为无界并发双端队列ConcurrentLinkedDequeQueryDetailL52每 5 秒由单线程调度器执行一次removeExpiredQueryDetails()L58-L60删除eventTime早于当前纳秒时间 - query_detail_cache_time_nanosecond的记录eventTime由getCurrentTimeNS()生成L122-L131同一毫秒内的多条记录会通过自增计数保证时间戳严格单调递增避免过滤时出现边界丢失。缓存时长配置——query_detail_cache_time_nanosecondConfig.java默认值30000000000即 30 秒单位纳秒可动态修改mutable true源码注释建议不要设低于 1 秒StarRocks Manager 每 1 秒拉取或 15 秒metrics 每 15 秒计算延迟。Explain 级别配置——query_detail_explain_levelConfig.java默认值COSTS可动态修改控制返回记录中explain字段的详细程度调整后可通过ADMIN SET FRONTEND CONFIG (query_detail_explain_level NORMAL);或EXTENDED等取值来平衡信息量与开销。SQL digest 配置——enable_sql_digestConfig.java开启后为每条 SQL 生成参数化的 digest 写入digest字段便于按 SQL 形态聚合统计。使用示例v1获取当前缓存的所有查询明细curl -u root: http://fe_host:fe_http_port/api/query_detail?event_time0v2增量拉取并聚合所有 FEcurl -u root: http://fe_host:fe_http_port/api/v2/query_detail?event_time0is_request_all_frontendtruev2按用户过滤curl -u root: http://fe_host:fe_http_port/api/v2/query_detail?event_time1753671088userroot其中user过滤在 QueryDetailQueue.java 中实现为queryDetail.getUser().equalsIgnoreCase(user)即不区分大小写匹配。增量拉取的正确姿势监控程序应当记录上次拉取返回记录中的最大eventTime下次以该值为event_time继续拉取从而避免重复与遗漏。由于队列中同一查询会以RUNNING和终态两条记录先后出现两条记录的eventTime不同增量拉取天然能拿到先 RUNNING 后 FINISHED/FAILED的完整状态流转。v2 全 FE 聚合的实现原理QueryDetailActionV2.java当is_request_all_frontendtrue时当前 FE 会构造同样的请求路径保留event_time与user参数携带当前认证信息通过fetchResultFromOtherFrontendNodes向集群内其他存活 FE 发起并行请求再以GsonUtils反序列化各 FE 返回的RestBaseResultV2ListQueryDetail并合并到结果集中返回。这在多 FE 集群中省去了逐个节点请求的麻烦。典型应用场景构建查询历史系统周期性调用 v2 接口增量拉取全集群查询明细落库后支持按用户、SQL、耗时、扫描量检索与审计慢查询定位用latency、pendingTime、netTime与netComputeTime拆分延迟构成判断瓶颈在排队、解析规划还是执行阶段资源开销分析结合cpuCostNs、memCostBytes、spillBytes、scanBytes、queryFeMemory评估大查询与落盘行为辅助资源组与 Warehouse 规划缓存效果观察cacheMissRatio可用于评估数据缓存命中情况故障复盘FAILED状态记录携带errorMessageexplain与profile字段可用于分析执行计划与性能 Profile。相关资源接口官方文档query_detail.mdHTTP 接口总览FE 接口清单其中列出了/api/query_detailhttp_interface.mdFE 配置参数说明enable_collect_query_detail_info等log_server_meta.md接口实现QueryDetailAction.java、QueryDetailActionV2.java数据模型与队列QueryDetail.java、QueryDetailQueue.java明细写入入口StmtExecutor.java配置定义Config.java需要注意的是本文所述端口、路径与配置取值均以当前仓库代码与文档为准不同 StarRocks 版本可能在字段或行为上有细微差异使用前请以实际部署版本的文档核对。【免费下载链接】starrocksThe worlds fastest open query engine for sub-second analytics both on and off the data lakehouse. With the flexibility to support nearly any scenario, StarRocks provides best-in-class performance for multi-dimensional analytics, real-time analytics, and ad-hoc queries. A Linux Foundation project.项目地址: https://gitcode.com/GitHub_Trending/st/starrocks创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考