StarRocks 异步物化视图监控指标Metrics接入 Prometheus 完整指南【免费下载链接】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本文以 StarRocks 从 v3.1 起新增的异步物化视图监控指标体系为主线讲解如何在 Prometheus 中通过/metrics端点开启物化视图指标采集并逐项解读每个指标Counter / Gauge / Histogram的类型、语义、标签与使用场景帮助读者建立物化视图刷新与查询改写链路的可观测能力并据此制定监控告警与性能调优策略。概述为什么要监控异步物化视图异步物化视图Asynchronous Materialized View是 StarRocks 中用于加速查询的核心组件其刷新任务由 TaskManager / TaskRunScheduler 统一调度查询阶段则由查询改写器Query Rewriter决定是否将用户查询改写为对物化视图的访问。一旦物化视图刷新失败、长时间 pending、被置为 inactive或者改写命中率长期偏低都会直接影响查询性能与数据新鲜度。从 v3.1 开始StarRocks 为异步物化视图提供了一整套结构化监控指标覆盖三类核心信号刷新Refresh任务触发数、成功 / 失败 / 空任务数、pending / running 任务数、刷新耗时分布查询Query改写命中、考虑、匹配的次数以及物化视图直接查询的使用次数存量State行数、存储大小、分区数、active / inactive 状态。这些指标由 FE 进程维护并在/metricsHTTP 端点输出可直接被 Prometheus 抓取再配合 Grafana 做可视化与告警。一、让 Prometheus 采集物化视图指标1.1 采集原理与权限前提物化视图指标由 FE 的 MetricsActionGET /metrics暴露。从源码MetricsAction.java#L158-L205可以看到请求参数with_materialized_view_metrics只有取值为all或minified时才会开启物化视图指标采集一旦开启该参数FE 会校验请求者身份需要登录账号且该账号必须拥有user_admin与db_admin角色root账号除外否则相关指标采集会被静默降级关闭AccessDeniedException时isCollectMVMetrics被置为false。此外FE 是否按物化视图维度维护指标还受 FE 配置项控制enable_materialized_view_metrics_collect默认truemutable true可在运行时修改见 Config.java#L1827-L1828。关闭后各物化视图的实体会被替换为MaterializedViewMetricsBlackHoleEntity空实现按物化视图粒度的指标将不再收集但集群级mv_global_*指标不受影响。1.2 Prometheus 配置示例要让 Prometheus 访问集群中的物化视图元数据需要在 Prometheus 配置文件prometheus/prometheus.yml中添加如下配置global: .... scrape_configs: - job_name: dev metrics_path: /metrics # Add the following configurations. basic_auth: username: root password: params: with_materialized_view_metrics : [all] ....各字段说明字段说明metrics_path固定为/metrics即 FE 的指标 HTTP 端点见 MetricsAction.java#L74 中API_PATH。basic_auth.username登录 StarRocks 集群的用户名。除root外用户必须同时被授予user_admin和db_admin角色否则无法获取按物化视图粒度的指标。basic_auth.password登录 StarRocks 集群的密码。params.with_materialized_view_metrics物化视图指标采集范围取值all收集全部物化视图相关指标minified不收集 Gauge 型指标以及值为0的 Counter 指标。1.3all与minified两种模式的差异minified模式对应的代码逻辑位于 MaterializedViewMetricsRegistry.java#L102-L130doCollectMetrics跳过 Gauge 指标因为 Gauge 在采集时会尝试获取数据库锁并访问更多元数据ignore gauge metrics since it will try db lock and visit more metadata开销较大跳过值为0的 Counter 指标减少无意义的零值序列。因此当物化视图数量很多、采集开销敏感时优先使用minified当需要完整信号包括0值、Gauge 与 Histogram 分布时使用all。注意minified模式下 Histogram 不会被输出见 MaterializedViewMetricsRegistry.java#L150-L156mv_refresh_duration需要all模式才能拿到。1.4 相关测试验证仓库中已有针对该采集链路的测试可作为配置与行为的交叉验证MetricsActionTest.java验证/metrics请求参数解析与权限校验行为MaterializedViewGlobalMetricsTest.java验证mv_global_*集群级指标的统计逻辑。二、指标总览与标签体系物化视图指标分为**按物化视图粒度per-MV与集群级global**两类均由 MaterializedViewMetricsRegistry 统一注册与采集具体的度量对象定义在 MaterializedViewMetricsEntity。按物化视图粒度的指标在输出时会被统一附加以下标签见 MaterializedViewMetricsRegistry.java#L124-L127db_name物化视图所在数据库名mv_name物化视图名mv_id物化视图 IDwarehouse_name物化视图所属 Warehouse在存算分离 / 多 Warehouse 场景下有效可能为空字符串。集群级mv_global_*指标则带有refresh_mode、status、warehouse_name、usage_type、state等标签见下文各指标说明。集群级指标通过独立注册表globalHistogramRegistry与MetricRepo中的MetricWithLabelGroup维护并始终输出不受按物化视图粒度的权限开关影响见 MaterializedViewMetricsRegistry.java#L49-L51。三、刷新类指标Refresh指标名类型语义mv_refresh_jobsCounter物化视图触发的刷新任务job总数。一个刷新任务对应一次用户手动触发或定时调度触发一个 job 内部可能执行多个 task run。每个 job 在其达到终态时计数一次被合并进后续批次的MERGEDtask run 不计入。mv_refresh_total_success_jobsCounter刷新成功SUCCESS的 job 数每个 job 计一次。mv_refresh_total_failed_jobsCounter刷新失败FAILED的 job 数每个 job 计一次。mv_refresh_total_empty_jobsCounter因待刷新数据为空而被取消的刷新 job 数对应MERGED/SKIPPED终态。mv_refresh_total_retry_meta_countCounter刷新 job 检查基表是否更新的次数重试元数据检查计数。mv_refresh_pending_jobsGauge当前处于 pending排队中状态的刷新 job 数采集时实时计算。mv_refresh_running_jobsGauge当前正在运行running的刷新 job 数。mv_refresh_durationHistogram刷新 job 的墙钟耗时单位毫秒。多批次 job 从第一个 task run 开始算到最后一个 task run 完成。上述刷新计数器的统计入口是 MaterializedViewMetricsEntity.java#L368-L386 的increaseRefreshJobStatus只有 job 达到终态isFinishState()才会计数且MERGED、SKIPPED归入 emptySUCCESS归入成功FAILED归入失败。该方法的调用方是刷新任务处理器 MVTaskRunProcessor.java分别在失败、正常结束等路径调用因此这几个指标真实反映了刷新任务的最终结果。mv_refresh_pending_jobs与mv_refresh_running_jobs是 Gauge其取值实时查询TaskRunScheduler的排队计数与运行状态见 MaterializedViewMetricsEntity.java#L178-L218适合直接用于“刷新积压”告警。四、查询与改写类指标Query / Rewrite指标名类型语义mv_query_total_countCounter查询预处理阶段中该物化视图被使用的次数。mv_query_total_hit_countCounter查询计划阶段判定该物化视图可改写查询的次数。注意该值可能偏高因为最终计划可能因成本较高而放弃改写。mv_query_total_considered_countCounter物化视图实际改写查询的次数不含直接查询该物化视图的情况。mv_query_total_matched_countCounter物化视图进入查询最终计划的次数含直接查询该物化视图的情况。mv_query_total_text_based_matched_countCounter文本改写text based rewrite匹配的次数该指标在实体初始化时注册见 MaterializedViewMetricsEntity.java#L159-L162。这四个 Counter 的注册与递增方法一一对应MaterializedViewMetricsEntity.java#L342-L365它们共同刻画一条查询改写漏斗count预处理使用→hit判定可改写→considered实际改写→matched进入最终计划。通过对比相邻两级的差值可以判断改写是否因成本估算而被最终放弃。相关测试可参考 MvRewriteMetricsTest.java其中覆盖了改写场景下这些计数器的递增行为。五、物化视图状态类指标Gauge指标名类型语义mv_row_countGauge物化视图当前行数。采集时需获取数据库/表锁tryLockTablesWithIntensiveDbLock超时返回 0见 MaterializedViewMetricsEntity.java#L220-L246。mv_storage_sizeGauge物化视图存储大小单位字节。同样需要短暂持锁读取见 MaterializedViewMetricsEntity.java#L248-L274。mv_inactive_stateGauge物化视图状态0表示 active1表示 inactive。mv_partition_countGauge物化视图分区数非分区物化视图返回0。这几个 Gauge 直接映射物化视图的“健康度”mv_inactive_state为1表示物化视图不可用可能是基表 schema 变更等原因导致失效是重点告警对象mv_row_count/mv_storage_size可用于观察物化视图的数据规模变化是否与预期一致。六、集群级Global指标集群级指标面向整集群 / 多 Warehouse 的可观测性不区分单个物化视图无论按物化视图粒度的采集权限如何都会输出指标名类型标签语义mv_global_countGaugerefresh_mode、status集群中异步物化视图数量按刷新模式与状态ACTIVE/INACTIVE分组。实现见 MaterializedViewMetricsRegistry.java#L162-L185。mv_global_query_rewrite_queries_totalCounterstate按物化视图改写结果分组的查询数HIT查询改写为使用物化视图、NO_HIT改写已开启但未使用任何物化视图、DISABLED改写被会话变量或 FE 配置关闭。每条查询计一次。mv_global_query_mv_usage_totalCounterusage_type、refresh_mode物化视图被查询使用的次数REWRITE查询被改写为使用该物化视图或DIRECT直接查询该物化视图并按刷新模式分组。mv_global_refresh_jobs_totalCounterwarehouse_name集群所有物化视图的刷新 job 总数按 Warehouse 聚合是mv_refresh_jobs的全集群汇总在 job 的终态 task run 上计一次排除MERGED。始终输出不受按物化视图粒度权限影响。mv_global_refresh_success_jobs_totalCounterwarehouse_name集群成功刷新 job 总数按 Warehouse 聚合。mv_global_refresh_failed_jobs_totalCounterwarehouse_name集群失败刷新 job 总数按 Warehouse 聚合。mv_global_refresh_durationHistogramwarehouse_name集群刷新 job 的墙钟耗时毫秒按 Warehouse 聚合每个 job 记录一次。mv_global_refresh_pending_jobsGaugewarehouse_name集群当前 pending 刷新 job 数按 Warehouse 聚合。mv_global_refresh_running_jobsGaugewarehouse_name集群当前 running 刷新 job 数按 Warehouse 聚合。实现要点均可在 MaterializedViewMetricsRegistry.java 中确认刷新类聚合计数器注册在 MetricRepo.java#L175-L190MetricWithLabelGroup按warehouse_name/state标签分组递增入口为increaseGlobalRefreshJobStatusMaterializedViewMetricsRegistry.java#L190-L201与按物化视图粒度的计数在同一 job 终态钩子上触发保证聚合值与明细之和一致mv_global_count与两个全局 Gauge 在每次抓取scrape时实时枚举集群内所有异步物化视图计算collectGlobalMvCount/collectGlobalGauges不依赖每日清理的实体缓存mv_global_query_mv_usage_total采用二维计数器usage_type×refresh_mode实现递增入口为increaseMvUsageMaterializedViewMetricsRegistry.java#L272-L282mv_global_query_rewrite_queries_total的递增入口为increaseGlobalQueryRewrite调用方为查询改写校验器 MVRewriteValidator.java全局刷新耗时直方图存放在独立的globalHistogramRegistry中抓取时无条件输出MaterializedViewMetricsRegistry.java#L214-L218。七、指标使用的注意事项与最佳实践权限与模式选择采集按物化视图粒度的指标必须使用root或同时具备user_admin、db_admin角色的账号若 Prometheus 无这些权限建议改用仅依赖集群级mv_global_*指标的监控方案。minifiedvsall物化视图数量大、采集压力高时用minified跳过 Gauge 与零值 Counter需要mv_refresh_duration等 Histogram 或完整零值信号时必须用all。Gauge如mv_row_count采集会短暂加锁高频抓取需谨慎。改写效果评估综合mv_query_total_*四个 Counter 的漏斗差值可判断改写被成本模型否决的比例结合mv_global_query_rewrite_queries_total{stateHIT|NO_HIT}可从集群视角评估改写整体收益。告警建议示例按需调整阈值mv_inactive_state 1物化视图失效立即告警mv_global_refresh_failed_jobs_total较历史基线突增刷新失败告警mv_global_refresh_pending_jobs 0持续存在刷新积压告警rate(mv_refresh_duration_bucket)分位数如 P95超阈值刷新变慢关注基表数据量与刷新调度。与集群整体监控协同物化视图指标是 FE 指标体系的一部分同一/metrics端点还支持typejson、typecore等输出格式见 MetricsAction.java#L140-L148可结合 metrics.md 中 FE 的通用指标一起纳入监控大盘。八、源码路径速查主题文件指标 HTTP 端点与参数解析、权限校验MetricsAction.java物化视图指标注册表、集群级指标采集MaterializedViewMetricsRegistry.java按物化视图粒度的指标实体定义与递增逻辑MaterializedViewMetricsEntity.java集群级刷新 / 改写计数器的注册MetricRepo.java采集开关 FE 配置项Config.java刷新任务处理中指标递增的调用点MVTaskRunProcessor.java查询改写结果的指标上报MVRewriteValidator.java指标采集链路测试MetricsActionTest.java、MaterializedViewGlobalMetricsTest.java、MvRewriteMetricsTest.java通过上述指标运维与开发人员可以完整掌握每个异步物化视图乃至整个集群物化视图体系的刷新健康度、查询改写效果与资源消耗为物化视图的创建、刷新策略与调度配置提供数据支撑。【免费下载链接】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），仅供参考