StarRocks SHOW BROKER 命令完全指南语法、返回字段与源码级原理解析【免费下载链接】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导读SHOW BROKER是 StarRocks 集群管理中最常用的诊断命令之一用于查看所有已添加到集群中的 Broker 节点信息包括其网络地址、存活状态、启动时间与心跳上报情况。本文以官方 SQL 参考文档 SHOW_BROKER.md 为骨架结合 FE 源码ShowExecutor、BrokerProcNode、BrokerMgr、FsBroker与仓库中 Apache HDFS Broker 实现带你掌握命令的完整语法、每个返回字段的真实含义以及Alive状态与ErrMsg背后的心跳机制原理让你能快速定位 Broker 失联、加载任务失败等集群问题。一、命令概述与适用场景SHOW BROKER用于查看 StarRocks 集群中所有已注册 Broker 节点的信息。在 StarRocks 中Broker 是负责对接外部存储系统如 HDFS的独立进程主要用于通过 Broker Load 加载外部数据文件、通过 Export 导出数据到外部存储。当数据加载任务失败、或怀疑某个 Broker 节点失联时第一时间执行SHOW BROKER即可掌握全部 Broker 的运行状态。该语句属于**集群管理Cluster Management**类别的节点与进程管理Nodes Processes命令在仓库文档中的位置为 nodes_processes。权限要求重要只有具备SYSTEM 级 OPERATE 权限的用户或拥有cluster_admin角色的用户才能执行该操作。这一权限约束在 FE 源码的授权检查链路中同样有据可查AuthorizerStmtVisitor 会针对ShowBrokerStmt进行 SYSTEM 级 OPERATE 权限校验未授权用户执行时会被拒绝。二、语法格式SHOW BROKER语法极为简洁无需任何参数SHOW BROKER与SHOW BACKENDS、SHOW FRONTENDS等同族命令一样它不需要指定 Broker 名称、数据库或任何过滤条件执行后一次性返回集群中全部 Broker 的信息。三、返回字段详解执行成功后返回结果集结构如下------------------------------------------------------------------------------------- | Name | IP | Port | Alive | LastStartTime | LastUpdateTime | ErrMsg | -------------------------------------------------------------------------------------各字段含义如下表参数说明NameBroker 的名称。IPBroker 运行所在节点的 IP 地址。PortBroker 使用的端口默认8000。AliveBroker 节点是否可达。trueBroker 存活且可达。falseBroker 不可达。LastStartTimeBroker 进程最后一次启动的时间。LastUpdateTimeBroker 最后一次向 FE 上报心跳的时间。ErrMsg当心跳失败或连接丢失时显示的报错信息。这些返回字段的列定义在 FE 源码中固定生成ShowResultMetaFactory.visitShowBrokerStatement 会遍历BrokerProcNode.BROKER_PROC_NODE_TITLE_NAMES常量将 7 列全部构建为VARCHAR(30)类型输出列名与上文一一对应。四、使用示例查看集群中所有 Broker 的信息SHOW BROKER; ------------------------------------------------------------------------------------- | Name | IP | Port | Alive | LastStartTime | LastUpdateTime | ErrMsg | ------------------------------------------------------------------------------------- | my_broker | 127.0.0.1 | 8000 | true | 2026-01-21 12:40:00 | 2026-01-21 12:40:05 | | -------------------------------------------------------------------------------------示例解读Name为my_broker是添加 Broker 时指定的名称通过ADD BROKER语句注册该 Broker 运行在127.0.0.1:8000端口使用默认值 8000Alive true表示 FE 能正常收到其心跳LastStartTime记录进程启动时刻LastUpdateTime在示例中比启动时间晚 5 秒说明 FE 刚刚收到一次成功的心跳ErrMsg为空表示无心跳异常。当某个 Broker 失联时Alive会变为false且ErrMsg会显示具体错误信息详见下文第六节的机制分析。五、执行链路从 SQL 到结果集的源码级解析了解命令背后完整的代码路径能帮助你更准确地解读返回结果。SHOW BROKER在 FE 中的执行链路如下1. 语法解析Parser ASTSQL 文本被解析为 AST 节点ShowBrokerStmt源码。该节点继承自ShowStmt本身不携带任何属性仅作为命令标识存在public class ShowBrokerStmt extends ShowStmt { public ShowBrokerStmt() { this(NodePosition.ZERO); } ... public R, C R accept(AstVisitorR, C visitor, C context) { return visitor.visitShowBrokerStatement(this, context); } }2. 权限校验AuthorizationShowBrokerStmt经由 AuthorizerStmtVisitor 完成 SYSTEM 级 OPERATE 权限检查与文档中的权限说明保持一致。3. 结果集构造Executor最终执行逻辑位于 ShowExecutor.visitShowBrokerStatementOverride public ShowResultSet visitShowBrokerStatement(ShowBrokerStmt statement, ConnectContext context) { BrokerProcNode procNode new BrokerProcNode(); ListListString rowSet procNode.fetchResult().getRows(); // Only success return new ShowResultSet(showResultMetaFactory.getMetadata(statement), rowSet); }4. 数据来源ProcNodeShowExecutor委托给 BrokerProcNode 拉取数据。BrokerProcNode从GlobalStateMgr获取BrokerMgr遍历getBrokersMap()中每个 Broker 名称brokerName下的所有FsBroker实例逐行拼装出Name / IP / Port / Alive / LastStartTime / LastUpdateTime / ErrMsg7 列数据public static final ImmutableListString BROKER_PROC_NODE_TITLE_NAMES new ImmutableList.BuilderString() .add(Name).add(IP).add(Port).add(Alive) .add(LastStartTime).add(LastUpdateTime).add(ErrMsg) .build(); Override public ProcResult fetchResult() { ... BrokerMgr brokerMgr GlobalStateMgr.getCurrentState().getBrokerMgr(); MapString, ArrayListMultimapString, FsBroker brokersMap brokerMgr.getBrokersMap(); for (Map.EntryString, ArrayListMultimapString, FsBroker entry : brokersMap.entrySet()) { String brokerName entry.getKey(); for (FsBroker broker : entry.getValue().values()) { ListString row Lists.newArrayList(); row.add(brokerName); row.add(broker.ip); row.add(String.valueOf(broker.port)); row.add(String.valueOf(broker.isAlive)); row.add(TimeUtils.longToTimeString(broker.lastStartTime)); row.add(TimeUtils.longToTimeString(broker.lastUpdateTime)); row.add(broker.heartbeatErrMsg); result.addRow(row); } } return result; }从源码可以确认两个实现细节数据实时取自内存状态结果来自BrokerMgr维护的 Broker 元数据含心跳结果并非实时探测因此Alive反映的是最近一次心跳结果时间戳为毫秒值格式化lastStartTime、lastUpdateTime在FsBroker中以毫秒时间戳long存储经TimeUtils.longToTimeString转为yyyy-MM-dd HH:mm:ss格式展示。BrokerMgr中的注册与查询接口见 BrokerMgr.java如addBrokers注册 Broker、getBrokersMap查询全部 BrokerBroker 列表则通过ADD BROKER/DROP BROKER语句维护。六、深入理解 Alive 与 ErrMsg心跳机制原理返回字段中最有诊断价值的是Alive与ErrMsg二者由 FE 侧的 Broker 心跳处理逻辑驱动。核心实现在 FsBroker.handleHbResponse逻辑如下心跳正常HbStatus.OK时若 Broker 之前处于死亡状态!isAlive则置为存活并记录lastStartTime首次恢复存活的时间点每次成功心跳都会更新lastUpdateTime并清空heartbeatErrMsg、重置重试计数。心跳异常非 OK时采用连续失败重试机制只有在失败次数超过 FE 配置项heartbeat_retry_times见 Config后才将isAlive置为false同时将心跳响应中的错误信息写入heartbeatErrMsg无信息时记为Unknown error这就是你在SHOW BROKER中看到的ErrMsg字段的来源。因此Alive false意味着该 Broker 已连续多次心跳失败ErrMsg中即为最后一次失败的原因如网络不可达、Broker 进程未启动等LastUpdateTime长期停滞则说明 FE 已长时间收不到该 Broker 的心跳。此外失败心跳信息也会被同步到 Follower FE保证主备内存状态一致源码注释中明确说明了这一点。七、配套操作与排查建议关联的管理命令注册 Broker使用ADD BROKER broker_name host:port[, ...]将 Broker 加入集群后SHOW BROKER才会看到对应记录下线 Broker使用DROP BROKER移除不再使用的 Broker同类状态查询SHOW BACKENDS、SHOW FRONTENDS、SHOW COMPUTE NODES分别查看 BE、FE、CN 节点状态可组合用于全面体检。集群中 Broker 的实际形态仓库自带 Apache HDFS Broker 的完整实现位于 fs_brokers/apache_hdfs_broker包含src源码与conf配置文件用于对接 HDFS 文件系统配合 Broker Load / Export 实现外部数据的导入与导出。常见问题排查路径SHOW BROKER结果为空集群中尚未注册任何 Broker检查是否执行过ADD BROKERAlive false且ErrMsg有内容按ErrMsg提示检查 Broker 所在主机网络、进程存活状态、端口默认 8000是否可连通确认 Broker 配置文件正确LastUpdateTime不更新Broker 与 FE 之间的心跳通道异常多为网络分区或 FE 主节点切换所致数据加载任务报 Broker not alive先执行SHOW BROKER确认对应 Broker 节点状态再结合 BrokerMgrTest 等测试用例理解 Broker 注册与心跳的预期行为。八、小结SHOW BROKER虽然语法只有一行却是运维 StarRocks 集群时不可或缺的巡检工具。理解其返回字段的真实含义——特别是Alive与ErrMsg由 FE 心跳机制连续失败重试、状态变更同步驱动——能帮助你在加载任务失败时快速定位 Broker 侧的问题根因。结合本仓库 FE 源码中的 ShowExecutor、BrokerProcNode、BrokerMgr 与 FsBroker即可对命令的执行链路与状态判定逻辑形成完整认知从而更从容地排查集群数据通路问题。【免费下载链接】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），仅供参考