GeekIt

VictoriaMetrics命令速查

单机与集群启动、HTTP API 查询、MetricsQL、vmagent 采集、vmalert 告警、导入导出、备份恢复、调优与排查等 131 条命令

共 131 条命令 · 12 类场景 · 点击右侧图标可复制

命令 / 参数说明复制
victoria-metrics -help查看单机版全部启动参数
victoria-metrics -storageDataPath=/var/lib/victoria-metrics -retentionPeriod=12单机启动:数据目录与保留 12 个月
victoria-metrics -storageDataPath=/data/vm -httpListenAddr=:8428 -memory.allowedPercent=60限制内存使用比例,避免与业务争抢
victoria-metrics -storageDataPath=/data/vm -retentionPeriod=2y保留期支持 h/d/w/y 后缀
victoria-metrics -storageDataPath=/data/vm -selfScrapeInterval=30s自动抓取自身指标,便于监控自检
systemctl start victoria-metricssystemd 部署方式启动
docker run -d -p 8428:8428 -v /data/vm:/victoria-metrics-data victoriametrics/victoria-metrics容器方式单机运行
victoria-metrics-prod -storageDataPath=/data/vm使用优化版二进制(生产推荐)
ss -lntp | grep 8428确认 HTTP 端口监听
curl http://localhost:8428/health健康检查
curl http://localhost:8428/ready就绪检查,适合 K8s 探针
curl http://localhost:8428/metrics | head自身指标输出,确认服务正常
命令 / 参数说明复制
vmstorage -storageDataPath=/data/vmstorage -retentionPeriod=12 -httpListenAddr=:8482集群存储节点,负责数据落盘与查询
vminsert -storageNode=vmstorage1:8400,vmstorage2:8400 -httpListenAddr=:8480写入节点,按一致性哈希分发到 storage
vmselect -storageNode=vmstorage1:8401,vmstorage2:8401 -httpListenAddr=:8481查询节点,聚合各 storage 的结果
vminsert -storageNode=... -replicationFactor=2写入复制因子,多副本提升可用性
vmstorage -storageDataPath=/data -dedup.minScrapeInterval=30s去重窗口,双写采集场景必配
curl http://vminsert:8480/insert/0/prometheus/api/v1/write集群写入地址(accountID=0)
curl http://vmselect:8481/select/0/prometheus/api/v1/query?query=up集群查询地址
集群端口:8480 写、8481 读、8482 storage HTTPvmstorage 内部 gRPC 默认 8400/8401
单机版足以支撑千万级序列数据量或写入并发超限再上集群
accountID/ProjectID 实现多租户隔离路径中的 0 即租户 ID,可配合反代做映射
命令 / 参数说明复制
curl -G http://localhost:8428/api/v1/query --data-urlencode 'query=up'即时查询,兼容 Prometheus API
curl -G http://localhost:8428/api/v1/query_range --data-urlencode 'query=rate(http_requests_total[5m])' --data-urlencode 'start=1h' --data-urlencode 'step=60s'范围查询,start 支持相对时间
curl -s http://localhost:8428/api/v1/labels列出全部标签名
curl -s http://localhost:8428/api/v1/label/__name__/values列出全部指标名
curl -G http://localhost:8428/api/v1/series --data-urlencode 'match[]=up'查看匹配的序列
curl -s http://localhost:8428/api/v1/status/tsdbTSDB 状态:序列数、标签基数与内存
curl -s http://localhost:8428/api/v1/status/active_queries当前正在执行的查询
curl -s http://localhost:8428/api/v1/status/top_queries最耗资源的查询排行,优化入口
curl -G http://localhost:8428/api/v1/export --data-urlencode 'match[]={__name__!=""}'导出数据为 JSON 行格式
curl -X POST http://localhost:8428/api/v1/import -T dump.jsonl导入 JSON 行格式数据
curl -X POST http://localhost:8428/api/v1/import/prometheus --data-binary @metrics.txt按 Prometheus 文本格式导入
查询接口与 Grafana 原生兼容Grafana 数据源选 Prometheus,URL 填 8428 即可
命令 / 参数说明复制
rate(http_requests_total[5m])自动处理 counter 重置与多副本去重,比 PromQL 更稳
default(node_load1, 0)空值时给默认值,避免图表断线
if (up == 0, 1, 0)条件表达式,替代 PromQL 里繁琐的写法
ifnot(up, 1)为空时填充默认值
keep_metric_names(sum(rate(http_requests_total[5m])))保留原始指标名,兼容依赖名字的面板
label_set(up, "env", "prod")批量添加标签
label_del(up, "instance")删除标签
label_keep(up, "job", "instance")只保留指定标签
alias(sum(rate(x[5m])), "QPS")给结果起别名,图表更直观
sort_by_label(up, "instance")按标签排序
histogram_quantile(0.95, sum by (le) (rate(http_request_duration_seconds_bucket[5m])))与 PromQL 一致的直方图分位数
MetricsQL 完全兼容 PromQL可直接迁移现有查询,再按需替换为更简洁的函数
命令 / 参数说明复制
vmagent -promscrape.config=/etc/vmagent/scrape.yml -remoteWrite.url=http://vminsert:8480/insert/0/prometheus/api/v1/write启动采集代理并写入远端
vmagent -promscrape.config=/etc/vmagent/scrape.yml -remoteWrite.url=http://vm:8428/api/v1/write写入单机版
vmagent -remoteWrite.tmpDataPath=/var/lib/vmagent -remoteWrite.maxDiskUsagePerURL=10GB远端不可用时本地缓存,避免数据丢失
curl http://vmagent:8429/targets查看抓取目标与最近错误
curl http://vmagent:8429/api/v1/targetsJSON 格式目标列表
curl -X POST http://vmagent:8429/-/reload热加载配置
vmagent -promscrape.configCheckInterval=10s定期检查配置变化,自动生效
vmagent -remoteWrite.urlRelabelConfig=/etc/vmagent/relabel.yml写入前统一改标签,做多集群归一
vmagent -promscrape.suppressScrapeErrors抑制抓取错误日志,避免刷屏
vmagent 支持 Prometheus scrape_config 语法原有 prometheus.yml 的采集部分可直接复用
命令 / 参数说明复制
vmalert -rule=/etc/vmalert/rules.yml -datasource.url=http://vmselect:8481/select/0/prometheus -notifier.url=http://alertmanager:9093启动规则评估并发送告警
vmalert -rule=/etc/vmalert/rules.yml -datasource.url=http://localhost:8428 -remoteWrite.url=http://localhost:8428单机场景:评估结果写回供 ALERTS 查询
vmalert -rule=... -remoteRead.url=http://vmselect:8481/select/0/prometheus需要回读历史数据时配置 remoteRead
vmalert -evaluationInterval=30s全局评估间隔
vmalert -rule.validateTemplates=false跳过模板校验(不建议生产关闭)
curl http://vmalert:8880/api/v1/rules查看规则分组与状态
curl http://vmalert:8880/api/v1/alerts查看当前触发的告警
curl -X POST http://vmalert:8880/-/reload热加载规则文件
vmalert-tool unittest --files=rules_test.yml用单元测试验证规则(新版提供)
告警规则语法与 Prometheus 兼容expr/for/labels/annotations 写法一致
命令 / 参数说明复制
curl -G http://old-prom:9090/api/v1/export --data-urlencode 'match[]={__name__!=""}' > dump.jsonl从 Prometheus 导出全部数据
curl -X POST http://vm:8428/api/v1/import -T dump.jsonl导入到 VictoriaMetrics
vmctl prometheus --prom-snapshot=/tmp/snap --vm-addr=http://localhost:8428用 vmctl 从 Prometheus 快照迁移
vmctl influx --influx-addr=http://influx:8086 --vm-addr=http://localhost:8428从 InfluxDB 迁移
vmctl remote-read --remote-read-src-addr=http://other:8428 --vm-addr=http://localhost:8428通过 remote read 跨实例搬迁
vmctl verify-block /data/vm/data/...校验数据块完整性
curl -X POST http://vm:8428/api/v1/import/prometheus --data-binary @metrics.txt文本格式补录数据
导入前先确认时间戳与指标名合法非法行会被跳过并写日志
大库迁移分批导出按时间范围或标签分片,避免单次导出过大
命令 / 参数说明复制
curl http://localhost:8428/snapshot/create创建快照,返回快照名
curl http://localhost:8428/snapshot/list列出已有快照
curl "http://localhost:8428/snapshot/delete?snapshotName=<name>"删除指定快照
vmbackup -storageDataPath=/data/vm -snapshot.createURL=http://localhost:8428/snapshot/create -dst=s3://bucket/vm备份到对象存储,自动创建快照
vmbackup -storageDataPath=/data/vm -snapshot.createURL=http://localhost:8428/snapshot/create -dst=fs:///backup/vm备份到本地目录
vmbackup -storageDataPath=/data/vm -dst=s3://bucket/vm -origin=fs:///backup/vm增量备份:以已有备份为基准
vmrestore -src=s3://bucket/vm -storageDataPath=/data/vm-new恢复数据到新目录
vmrestore -src=s3://bucket/vm -storageDataPath=/data/vm -skipBackup=false覆盖恢复前先备份原目录
备份前确保时钟同步且对象存储可写凭据可用环境变量或 -credsFilePath 指定
恢复完成后再启动服务运行中恢复会导致数据目录不一致
命令 / 参数说明复制
curl -s http://localhost:8428/metrics | grep vm_rows写入行数等核心指标
curl -s http://localhost:8428/api/v1/status/tsdb序列数、标签基数与内存明细
curl -s "http://localhost:8428/api/v1/status/tsdb?topN=10&focusLabel=instance"按标签看基数 TopN,定位高基数来源
curl -s http://localhost:8428/api/v1/status/top_queries最耗资源的查询,优化首选
curl -s http://localhost:8428/api/v1/status/active_queries正在执行的查询,排查长查询
victoria-metrics -search.logSlowQueryDuration=5s超过 5 秒的查询记入日志
victoria-metrics -loggerLevel=INFO调整日志级别
curl -s http://localhost:8428/metrics | grep vm_slow_queries_total慢查询累计计数
curl -s http://localhost:8428/metrics | grep vm_cache看缓存命中率,判断内存是否够用
接入 Grafana 官方 VictoriaMetrics 面板覆盖写入、查询、缓存与磁盘
命令 / 参数说明复制
-retentionPeriod=12保留期越长磁盘占用越大,按月评估
-dedup.minScrapeInterval=30s双写或联邦场景去重,等价于采集间隔
-memory.allowedPercent=60缓存可用内存比例,留足系统余量
-search.maxUniqueTimeseries=300000单查询最大序列数,防止打爆内存
-search.maxSamplesPerQuery=100000000单查询最大样本数限制
-search.maxQueryDuration=30s查询超时,避免长查询拖垮实例
-insert.maxQueueDuration=1m写入排队时长,超时返回 429
-maxConcurrentInserts=8限制并发写入,保护磁盘
-storage.minFreeDiskSpaceBytes=10GB磁盘剩余低于阈值转为只读
-futureRetention=2d允许写入未来时间戳的范围
-search.latencyOffset=30s延迟展示最近数据,缓解乱序写入导致的不完整
磁盘建议用本地 SSD对象存储适合备份,不适合直接做数据目录
命令 / 参数说明复制
curl http://vmstorage1:8482/metrics | grep vm_storage单节点存储指标
vminsert -storageNode=... -replicationFactor=2提高复制因子,容忍单节点故障
vmselect -selectNode=...显式指定查询节点列表
curl http://vmselect:8481/select/1/prometheus/api/v1/query?query=up按租户 ID 查询(accountID=1)
curl -X POST http://vminsert:8480/insert/1/prometheus/api/v1/write按租户 ID 写入
curl -X POST http://vminsert:8480/internal/force_merge触发合并,压缩数据释放空间
curl -X POST http://vmstorage:8482/internal/force_flush强制刷盘,迁移或停机前使用
vmstorage 扩容后数据不会自动重平衡新数据按哈希写入新节点,历史数据需迁移工具处理
多租户隔离依赖反代或 vmauthvmauth 可按路径与账号路由到不同租户
curl http://vmselect:8481/select/0/prometheus/api/v1/status/tsdb租户级 TSDB 状态
命令 / 参数说明复制
the number of matching timeseries exceeds -search.maxSeries匹配序列过多:收窄标签或调大限制(评估内存)
the response size exceeds -search.maxResponseSize响应过大:减少返回点数或改用聚合查询
query timed out / context deadline exceeded查询超时:缩小时间范围、降低 step 粒度
out of memory / cannot allocate memory内存不足:降 memory.allowedPercent、限制并发与序列数
no space left on device磁盘写满:扩容、缩短保留期或 force_merge
remote write returned 400 Bad Request写入数据非法:标签名/值或时间戳不合规
429 Too Many Requests写入排队超限:降低采集频率或扩容 vminsert
vmstorage is unreachablestorage 节点不可达:检查 8400/8401 与网络
connection refused(8428/8480/8481)进程未启动或端口配置不一致
error parsing promscrape config抓取配置 YAML 语法错误,用 vmagent -promscrape.configCheckInterval 观察日志
duplicate samples 导致图表抖动多副本写入未去重,配置 -dedup.minScrapeInterval
slow query 日志频繁出现用 /api/v1/status/top_queries 找出元凶,加 recording rule
磁盘增长远超预期多为高基数标签,查 tsdb 接口的 focusLabel 统计
恢复后数据查不到确认恢复目录与 -storageDataPath 一致,且保留期覆盖该时间

运维常用组合

单机部署victoria-metrics -storageDataPath=/data/vm -retentionPeriod=12 → curl /health → Grafana 接 Prometheus 数据源
集群部署vmstorage(多节点) → vminsert -storageNode → vmselect -storageNode → vmagent 写 /insert/0 → 查询 /select/0
采集迁移复用 prometheus scrape_config → vmagent -promscrape.config → /targets 验证 → -remoteWrite.url 写入
数据迁移旧端 /api/v1/export → 新端 /api/v1/import → 抽样查询校验 → 切换 Grafana 数据源
备份恢复vmbackup -snapshot.createURL → 校验 s3 数据 → vmrestore 到新目录 → 启动并核对保留期
性能排障status/top_queries → status/tsdb 看基数 → metrics 看缓存与内存 → 调整限制参数或加规则

常见问题排查

1. 单机优先

VictoriaMetrics 单机可支撑千万级序列,集群带来运维复杂度,按实际规模选择

2. rate 更稳

MetricsQL 的 rate 自动处理 counter 重置与去重,迁移时可直接替换

3. 去重窗口对齐采集间隔

双写或多副本场景必配 -dedup.minScrapeInterval,否则图表会抖

4. 高基数是主要成本

用 status/tsdb 的 focusLabel 找基数来源,比无脑扩容有效

5. 先快照再备份

vmbackup 会自动创建快照,手动操作时要成对执行 snapshot/create 与删除

6. 慢查询看 top_queries

优化前先确认是谁在拖慢,加 recording rule 或改查询写法

共 131 条 VictoriaMetrics 命令 · 示例中的地址、租户 ID 与路径请替换为实际环境

关于VictoriaMetrics命令速查

在线 VictoriaMetrics 命令速查手册,按部署与启动、单机与集群架构、HTTP API 查询、MetricsQL 与 PromQL 差异、vmagent 采集、vmalert 告警、数据导入导出与迁移、快照备份与恢复、状态监控与慢查询、容量与性能调优、集群运维与多租户、常见报错与排查等 12 类场景整理 140+ 条常用命令,每条附中文说明与可直接复制的写法,支持关键词搜索、分类折叠和一键复制,打开网页即可查阅。涵盖 victoria-metrics -storageDataPath/-retentionPeriod/-httpListenAddr/-memory.allowedPercent/-selfScrapeInterval 与 systemd/docker 启动与 /health /ready /metrics、vmstorage 的 -storageDataPath/-retentionPeriod/-dedup.minScrapeInterval 与 8482 端口、vminsert -storageNode 与 8400 与 -replicationFactor、vmselect -storageNode 与 8401 与 8481 与 /insert/0 与 /select/0 多租户路径、/api/v1/query 与 query_range 与 labels 与 label/__name__/values 与 series 与 status/tsdb 与 status/active_queries 与 status/top_queries 与 export 与 import 与 import/prometheus、MetricsQL 的 default/if/ifnot/keep_metric_names/label_set/label_del/label_keep/alias/sort_by_label 与 rate 去重与 counter 重置处理、vmagent 的 -promscrape.config/-remoteWrite.url/-remoteWrite.tmpDataPath/-remoteWrite.maxDiskUsagePerURL/-promscrape.configCheckInterval/-remoteWrite.urlRelabelConfig 与 /targets 与 /-/reload、vmalert 的 -rule/-datasource.url/-notifier.url/-remoteRead.url/-evaluationInterval 与 /api/v1/rules 与 /api/v1/alerts 与 vmalert-tool unittest、vmctl prometheus/influx/remote-read 与 verify-block、/snapshot/create|list|delete 与 vmbackup 的 -snapshot.createURL/-dst/-origin 增量与 vmrestore、-search.maxUniqueTimeseries/-search.maxSamplesPerQuery/-search.maxQueryDuration/-search.latencyOffset/-insert.maxQueueDuration/-maxConcurrentInserts/-storage.minFreeDiskSpaceBytes/-futureRetention、force_merge 与 force_flush 与 vmauth 多租户,以及 number of matching timeseries exceeds、response size exceeds、query timed out、out of memory、no space left on device、400 Bad Request、429 Too Many Requests、vmstorage unreachable 等报错排查。适用于 VictoriaMetrics 时序数据库部署与运维、Prometheus 平滑替换与数据迁移、MetricsQL 查询优化、vmagent 大规模采集、vmalert 告警落地、集群与多租户隔离、备份恢复与容量治理,以及监控运维与 SRE 面试复习。

核心能力

  • 涵盖 victoria-metrics -storageDataPath/-retentionPeriod/-httpListenAddr/-memory.allowedPercent/-selfScrapeInterval 与 systemd/docker 启动与 /health /ready /metrics、vmstorage 的 -storageDataPath/-retentionPeriod/-dedup.minScrapeInterval 与 8482 端口、vminsert -storageNode 与 8400 与 -replicationFactor、vmselect -storageNode 与 8401 与 8481 与 /insert/0 与 /select/0 多租户路径、/api/v1/query 与 query_range 与 labels 与 label/__name__/values 与 series 与 status/tsdb 与 status/active_queries 与 status/top_queries 与 export 与 import 与 import/prometheus、MetricsQL 的 default/if/ifnot/keep_metric_names/label_set/label_del/label_keep/alias/sort_by_label 与 rate 去重与 counter 重置处理、vmagent 的 -promscrape.config/-remoteWrite.url/-remoteWrite.tmpDataPath/-remoteWrite.maxDiskUsagePerURL/-promscrape.configCheckInterval/-remoteWrite.urlRelabelConfig 与 /targets 与 /-/reload、vmalert 的 -rule/-datasource.url/-notifier.url/-remoteRead.url/-evaluationInterval 与 /api/v1/rules 与 /api/v1/alerts 与 vmalert-tool unittest、vmctl prometheus/influx/remote-read 与 verify-block、/snapshot/create|list|delete 与 vmbackup 的 -snapshot.createURL/-dst/-origin 增量与 vmrestore、-search.maxUniqueTimeseries/-search.maxSamplesPerQuery/-search.maxQueryDuration/-search.latencyOffset/-insert.maxQueueDuration/-maxConcurrentInserts/-storage.minFreeDiskSpaceBytes/-futureRetention、force_merge 与 force_flush 与 vmauth 多租户,以及 number of matching timeseries exceeds、response size exceeds、query timed out、out of memory、no space left on device、400 Bad Request、429 Too Many Requests、vmstorage unreachable 等报错排查

适用场景

适用于 VictoriaMetrics 时序数据库部署与运维、Prometheus 平滑替换与数据迁移、MetricsQL 查询优化、vmagent 大规模采集、vmalert 告警落地、集群与多租户隔离、备份恢复与容量治理,以及监控运维与 SRE 面试复习。VictoriaMetrics命令速查全程在浏览器中完成,无需安装插件,可放心用于日常办公与排障。

常见问题

VictoriaMetrics命令速查是免费的吗?需要注册或安装吗?
VictoriaMetrics命令速查完全免费,无需注册、无需下载安装任何软件,用浏览器打开网页即可直接使用,也不限制使用次数。
VictoriaMetrics命令速查支持哪些功能?
涵盖 victoria-metrics -storageDataPath/-retentionPeriod/-httpListenAddr/-memory.allowedPercent/-selfScrapeInterval 与 systemd/docker 启动与 /health /ready /metrics、vmstorage 的 -storageDataPath/-retentionPeriod/-dedup.minScrapeInterval 与 8482 端口、vminsert -storageNode 与 8400 与 -replicationFactor、vmselect -storageNode 与 8401 与 8481 与 /insert/0 与 /select/0 多租户路径、/api/v1/query 与 query_range 与 labels 与 label/__name__/values 与 series 与 status/tsdb 与 status/active_queries 与 status/top_queries 与 export 与 import 与 import/prometheus、MetricsQL 的 default/if/ifnot/keep_metric_names/label_set/label_del/label_keep/alias/sort_by_label 与 rate 去重与 counter 重置处理、vmagent 的 -promscrape.config/-remoteWrite.url/-remoteWrite.tmpDataPath/-remoteWrite.maxDiskUsagePerURL/-promscrape.configCheckInterval/-remoteWrite.urlRelabelConfig 与 /targets 与 /-/reload、vmalert 的 -rule/-datasource.url/-notifier.url/-remoteRead.url/-evaluationInterval 与 /api/v1/rules 与 /api/v1/alerts 与 vmalert-tool unittest、vmctl prometheus/influx/remote-read 与 verify-block、/snapshot/create|list|delete 与 vmbackup 的 -snapshot.createURL/-dst/-origin 增量与 vmrestore、-search.maxUniqueTimeseries/-search.maxSamplesPerQuery/-search.maxQueryDuration/-search.latencyOffset/-insert.maxQueueDuration/-maxConcurrentInserts/-storage.minFreeDiskSpaceBytes/-futureRetention、force_merge 与 force_flush 与 vmauth 多租户,以及 number of matching timeseries exceeds、response size exceeds、query timed out、out of memory、no space left on device、400 Bad Request、429 Too Many Requests、vmstorage unreachable 等报错排查。
VictoriaMetrics命令速查适合哪些场景使用?
适用于 VictoriaMetrics 时序数据库部署与运维、Prometheus 平滑替换与数据迁移、MetricsQL 查询优化、vmagent 大规模采集、vmalert 告警落地、集群与多租户隔离、备份恢复与容量治理,以及监控运维与 SRE 面试复习。