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,支持自动化集成 |