强曰为道
与天地相似,故不违。知周乎万物,而道济天下,故不过。旁行而不流,乐天知命,故不忧.
文档目录

VictoriaMetrics 完全指南 / 04 - VMUI Web 界面

04 · VMUI Web 界面

本章目标

  • 了解 VMUI 的功能和界面布局
  • 掌握通过 VMUI 进行 MetricsQL 查询
  • 学会使用图表功能进行数据可视化
  • 掌握查询调试和性能分析技巧
  • 了解 VMUI 的高级功能(Top Queries、Query Stats 等)

4.1 VMUI 简介

VMUI(VictoriaMetrics UI)是 VictoriaMetrics 内置的 Web 界面,无需额外安装即可使用。它提供了查询编辑器、图表展示、查询历史等能力。

访问方式

单节点版:http://<host>:8428/vmui
集群版:  http://<vmselect-host>:8481/vmui

功能概览

┌─────────────────────────────────────────────────┐
│                    VMUI                          │
├────────────┬────────────┬───────────────────────┤
│  Query     │  Top       │  Query Stats          │
│  页面      │  Queries   │  (查询统计)            │
├────────────┴────────────┴───────────────────────┤
│                                                  │
│  ┌─────────────────────────────────────────┐    │
│  │           查询编辑器                      │    │
│  │  MetricsQL 语法高亮 + 自动补全           │    │
│  └─────────────────────────────────────────┘    │
│                                                  │
│  ┌─────────────────────────────────────────┐    │
│  │           图表区域                       │    │
│  │  时间序列折线图 + 表格视图               │    │
│  └─────────────────────────────────────────┘    │
│                                                  │
│  ┌─────────────────────────────────────────┐    │
│  │           查询历史                       │    │
│  │  最近查询列表 + 收藏                     │    │
│  └─────────────────────────────────────────┘    │
└─────────────────────────────────────────────────┘

4.2 首次使用

4.2.1 写入示例数据

为了让 VMUI 中有数据可以查询,先写入一些示例指标:

# 准备一批模拟指标数据
cat << 'EOF' > /tmp/metrics.txt
# 模拟 CPU 使用率指标
cpu_usage{host="web01", region="cn-north", env="prod"} 72.5
cpu_usage{host="web02", region="cn-north", env="prod"} 45.3
cpu_usage{host="web03", region="cn-south", env="staging"} 88.1
cpu_usage{host="db01", region="cn-north", env="prod"} 32.7

# 模拟内存使用率指标
memory_usage{host="web01", region="cn-north", env="prod"} 68.2
memory_usage{host="web02", region="cn-north", env="prod"} 55.8
memory_usage{host="web03", region="cn-south", env="staging"} 79.4
memory_usage{host="db01", region="cn-north", env="prod"} 82.1

# 模拟 HTTP 请求计数器
http_requests_total{host="web01", method="GET", path="/api/users", status="200"} 15234
http_requests_total{host="web01", method="POST", path="/api/users", status="201"} 342
http_requests_total{host="web01", method="GET", path="/api/users", status="404"} 89
http_requests_total{host="web02", method="GET", path="/api/users", status="200"} 12876
http_requests_total{host="web02", method="GET", path="/api/orders", status="200"} 8923

# 模拟磁盘指标
disk_usage{host="web01", mount="/"} 45.2
disk_usage{host="web01", mount="/data"} 78.9
disk_usage{host="db01", mount="/"} 38.1
disk_usage{host="db01", mount="/data"} 91.5
EOF

# 写入数据
curl -X POST \
    -H 'Content-Type: text/plain' \
    --data-binary @/tmp/metrics.txt \
    'http://localhost:8428/api/v1/import/prometheus'

# 验证写入
sleep 2
curl -s 'http://localhost:8428/api/v1/label/__name__/values' | python3 -m json.tool

预期输出:

{
    "status": "success",
    "data": [
        "cpu_usage",
        "disk_usage",
        "http_requests_total",
        "memory_usage"
    ]
}

4.2.2 界面语言设置

VMUI 支持自动检测浏览器语言。在界面右上角可以切换语言和主题(深色/浅色)。


4.3 查询页面详解

4.3.1 查询编辑器

VMUI 的查询编辑器支持:

功能 说明
语法高亮 MetricsQL 关键字、函数、标签自动着色
自动补全 输入前缀后显示可用的 metric name 和 label
查询历史 上下箭头切换历史查询
多行编辑 Shift+Enter 换行,Enter 执行
查询变量 使用 $variable 定义变量

4.3.2 基础查询示例

在查询框中输入以下查询:

# 1. 查看所有 CPU 使用率
cpu_usage

# 2. 按标签过滤
cpu_usage{host="web01"}

# 3. 正则匹配
cpu_usage{host=~"web.*"}

# 4. 排除标签
cpu_usage{host!~"db.*"}

# 5. 聚合查询 - 平均 CPU 使用率
avg(cpu_usage)

# 6. 按标签分组聚合
avg by (region) (cpu_usage)

# 7. 多指标计算
memory_usage / 100 * node_memory_total_bytes

# 8. 使用内置函数
rate(http_requests_total[5m])

4.3.3 时间范围控制

界面顶部的时间范围控件:

┌──────────────────────────────────────────┐
│  ◀ │ 2024-01-15 10:00 │ ▶ │ 1h ▼ │ 🔍  │
└──────────────────────────────────────────┘
控件 功能
◀ ▶ 前后移动时间窗口
时间显示 点击可自定义时间范围
1h ▼ 快速选择时间范围(5m, 15m, 1h, 6h, 1d, 7d, 30d)
🔍 刷新查询

快捷时间范围:

选项 含义
Last 5 minutes 最近 5 分钟
Last 15 minutes 最近 15 分钟
Last 1 hour 最近 1 小时
Last 6 hours 最近 6 小时
Last 1 day 最近 1 天
Last 7 days 最近 7 天
Last 30 days 最近 30 天

4.3.4 步长(Step)设置

步长决定查询结果的数据点密度:

Step = (end_time - start_time) / max_data_points

示例:
  时间范围:1h(3600秒)
  最大数据点:300
  Step = 3600 / 300 = 12s

在 VMUI 中,步长可以自动计算或手动指定。


4.4 图表功能

4.4.1 图表类型

VMUI 支持两种视图:

折线图(Graph):适合时序数据的趋势分析

100 ┤
 90 ┤                ╭─╮
 80 ┤            ╭──╯  ╰──╮
 70 ┤    ╭─────╯          ╰───
 60 ┤───╯
 50 ┤
    └─────────────────────────
    10:00  10:15  10:30  10:45

表格(Table):适合查看原始数据和精确数值

Time host=“web01” host=“web02” host=“db01”
10:00 72.5 45.3 32.7
10:15 71.8 46.1 33.2
10:30 73.2 44.9 31.8

4.4.2 图表交互

操作 方式
缩放 鼠标框选图表区域
平移 拖拽图表
查看数值 鼠标悬停到具体点
隐藏/显示序列 点击图例中的系列名
重置缩放 双击图表

4.4.3 多查询对比

在查询框下方点击 + Query 添加多个查询,可以在同一图表中对比:

Query A: avg by (host) (cpu_usage)          # 实线
Query B: avg by (host) (memory_usage)       # 虚线(不同颜色)

4.4.4 自定义图表设置

图表区域下方有额外设置:

设置项 说明
Custom step 自定义查询步长
Custom timezone 自定义时区
Stacked 堆叠模式(面积图)
Filled 填充模式

4.5 Top Queries 页面

Top Queries 是 VMUI 的独特功能,展示最近查询的统计信息:

访问路径:/vmui → Top Queries 标签
说明
Query 查询表达式
Count 执行次数
Avg Duration 平均执行时长
Max Duration 最大执行时长
Avg Series 平均返回序列数

使用场景

  • 发现慢查询:按 Max Duration 排序,找出耗时最长的查询
  • 优化高频查询:按 Count 排序,优化执行次数最多的查询
  • 容量规划:观察查询通常返回多少条时间序列

禁用 Top Queries

# 如果不需要 Top Queries 功能(节省少量资源)
victoria-metrics -search.logSlowQueryDuration=0

4.6 Query Stats 页面

Query Stats 展示当前正在执行的查询:

说明
Query 查询表达式
Duration 已执行时长
Start / End 查询时间范围

排查慢查询

场景:Grafana 面板加载很慢

1. 打开 VMUI → Query Stats
2. 观察 Duration 列
3. 找到耗时 > 5s 的查询
4. 复制查询表达式到 Query 页面分析
5. 使用 explain() 函数查看执行计划

4.7 高级查询技巧

4.7.1 使用 explain() 分析查询计划

# 查看查询执行计划
explain(avg by (region) (cpu_usage))

返回结果示例:

Series: 2
Query duration: 12ms
Series fetched: 4
Points fetched: 2880
Execution steps:
  1. Get series by filter: cpu_usage → 4 series
  2. Apply avg by (region) → 2 series

4.7.2 使用 format() 格式化输出

# 格式化指标名
format("CPU {host} = {region}", cpu_usage)

4.7.3 使用 label_value() 提取标签

label_value(cpu_usage, "host")

4.7.4 即时查询 vs 范围查询

# 即时查询(Instant Query)- 返回当前最新值
cpu_usage

# 范围查询(Range Query)- 返回时间范围内的数据点
cpu_usage[1h]

# 范围向量 + 函数 - 计算 5 分钟内的增长率
rate(http_requests_total[5m])

4.8 调试技巧

4.8.1 查询性能分析

# 1. 使用 explain() 查看执行计划
explain(rate(http_requests_total[5m]))

# 2. 减少数据量 - 使用精确标签匹配
rate(http_requests_total{host="web01"}[5m])  # ✅ 推荐
rate(http_requests_total[5m])                  # ⚠️ 可能返回过多序列

# 3. 缩短查询时间范围
rate(http_requests_total{host="web01"}[5m])   # ✅ 推荐
rate(http_requests_total[1h])                   # ⚠️ 需要更多内存

4.8.2 常见错误排查

错误信息 原因 解决方案
query timed out 查询超时 缩短时间范围或增加标签过滤
too many series 返回序列过多 增加 by 子句或标签过滤
invalid expression 语法错误 检查括号匹配和函数名拼写
empty result 无数据 检查 metric name 和标签是否正确
duplicate timestamp 重复时间戳 检查写入端的去重配置

4.8.3 查看原始数据

# 如果不确定某个 metric 的标签结构
# 直接输入 metric name,切换到 Table 视图查看
cpu_usage

# 可以看到所有标签和最新值

4.9 VMUI API

VMUI 也提供 API 接口,方便自动化和集成:

查询 API

# 即时查询
curl 'http://localhost:8428/api/v1/query?query=cpu_usage&time=2024-01-15T10:00:00Z'

# 范围查询
curl 'http://localhost:8428/api/v1/query_range?query=cpu_usage&start=2024-01-15T09:00:00Z&end=2024-01-15T10:00:00Z&step=60s'

# 获取 label 值列表
curl 'http://localhost:8428/api/v1/label/host/values'

# 获取 metric 名称列表
curl 'http://localhost:8428/api/v1/label/__name__/values'

# 获取 series 元数据
curl 'http://localhost:8428/api/v1/series?match[]=cpu_usage'

状态 API

# 构建信息
curl 'http://localhost:8428/api/v1/status/buildinfo'

# 运行时信息
curl 'http://localhost:8428/api/v1/status/active_queries'

# TSDB 状态
curl 'http://localhost:8428/api/v1/status/tsdb'

健康检查

curl 'http://localhost:8428/health'

4.10 VMUI 配置选项

自定义 URL 路径前缀

如果通过反向代理暴露 VMUI:

# 设置路径前缀
victoria-metrics -http.pathPrefix=/metrics/
# 访问地址变为:http://host:8428/metrics/vmui

Nginx 配置示例:

server {
    listen 80;
    server_name monitor.example.com;

    location /vm/ {
        proxy_pass http://127.0.0.1:8428/;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
}

禁用 VMUI

# 如果只通过 API 访问,可以禁用 VMUI(不暴露 Web 页面)
victoria-metrics -httpListenAddr=127.0.0.1:8428
# 然后通过 Nginx 只暴露 /api/ 路径

4.11 VMUI vs Grafana

特性 VMUI Grafana
内置 ✅ 无需安装 ❌ 需单独部署
语法高亮
图表类型 折线图、表格 50+ 种面板类型
仪表盘
告警
用户管理
适用场景 快速调试、临时查询 生产监控仪表盘

建议:VMUI 用于日常调试和临时查询,Grafana 用于生产监控仪表盘和告警。


本章小结

功能 说明
查询编辑器 MetricsQL 语法高亮、自动补全、查询历史
图表视图 折线图、表格,支持缩放、拖拽、隐藏系列
Top Queries 发现慢查询和高频查询
Query Stats 监控当前正在执行的查询
explain() 分析查询执行计划
API 完整的 HTTP API,支持自动化集成

扩展阅读