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

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):适合查看原始数据和精确数值

Timehost=“web01”host=“web02”host=“db01”
10:0072.545.332.7
10:1571.846.133.2
10:3073.244.931.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

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

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


本章小结

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

扩展阅读