VictoriaMetrics vmctl prometheus 模式参数详解从 Prometheus 快照迁移时序数据的完整实践【免费下载链接】VictoriaMetricsVictoriaMetrics: fast, cost-effective monitoring solution and time series database项目地址: https://gitcode.com/GitHub_Trending/vi/VictoriaMetrics本文以 vmctl prometheus 子命令的完整参数清单 为主体逐个讲解vmctl prometheus全部命令行参数的作用、默认值与适用场景并结合 app/vmctl/flags.go、app/vmctl/prometheus.go、app/vmctl/prometheus/prometheus.go 等源码说明每个参数在迁移流水线中的实际生效位置帮助你在真实环境中配置出一条可复制、可调优、可排障的 Prometheus → VictoriaMetrics 数据迁移命令。1. 命令定位vmctl prometheus 做什么vmctl是 VictoriaMetrics 官方提供的数据迁移 CLI 工具其prometheus子命令的定位见 app/vmctl/main.go是NAME: vmctl prometheus - Migrate time series from Prometheus USAGE: vmctl prometheus [command options]它通过读取 Prometheus 磁盘上的 TSDB 快照snapshot目录来迁移历史数据而不是走 remote read。整个流程可以概括为三步用 Prometheus 官方的tsdb.DBReadOnly以只读方式打开快照目录扫描出所有 block 并按时间/标签过滤Explore 阶段启动--prom-concurrency个并发 worker 逐个 block 读取时序数据Read 阶段通过 VictoriaMetrics 的 import API 批量写入目标实例Import 阶段由 app/vmctl/vm/vm.go 中的Importer实现。因此参数天然分成四组prom-* 源端参数如何读快照、vm-* 目标端参数如何写入 VictoriaMetrics、全局参数交互与日志、pushmetrics.* 自监控参数如何上报 vmctl 自身指标。下文按此组织完整命令示例可配合 vmctl prometheus 迁移指南 使用。2. 源端参数--prom-* 如何读取快照参数默认值说明--prom-snapshot必填Prometheus 快照目录路径。快照由 Prometheus 通过快照 API 生成需要让 vmctl 在同一文件系统内可访问该目录--prom-concurrency1并发读取快照 block 的 reader 数量--prom-filter-time-start无不限制RFC3339 格式时间只保留时间戳 ≥ 该值的时序。例2020-01-01T20:07:00Z--prom-filter-time-end无不限制RFC3339 格式时间只保留时间戳 ≤ 该值的时序--prom-filter-label无不过滤用于过滤的标签名例如__name__表示按指标名过滤--prom-filter-label-value.*对--prom-filter-label指定标签取值匹配的正则表达式--prom-tmp-dir-pathos.TempDir()打开只读 TSDB 时使用的临时目录这些参数在 flags.go 的 promFlags 中定义其中--prom-snapshot被标记为Required: true。它们最终组装为 prometheus.Config 并传入Client。2.1 --prom-snapshot唯一必填的源端参数Client.NewClient 内部调用tsdb.OpenDBReadOnly(cfg.Snapshot, cfg.TemporaryDir, nil)即以 Prometheus 的只读模式直接打开快照目录。这意味着快照必须是 Prometheus 数据目录中通过其快照接口生成的目录包含多个01xxxx命名的 block 目录vmctl 与快照目录需要位于同一文件系统或挂载点可访问的位置迁移不需要 Prometheus 处于在线状态--prom-tmp-dir-path会作为OpenDBReadOnly的临时目录参数传入默认使用系统临时目录若系统临时目录空间不足只读 TSDB 打开时需要少量临时文件空间可以显式指定更大的目录。2.2 时间过滤两级筛选机制--prom-filter-time-start/--prom-filter-time-end会经历两次解析与过滤字符串解析为毫秒时间戳parseTime 使用time.Parse(time.RFC3339, ...)解析格式不合法会直接报错退出block 级粗筛Explore 阶段Explore 遍历快照内所有 block用 filter.inRange 判断 block 的MinTime/MaxTime与过滤窗口是否有交集无交集的 block 直接计入blocks skipped不进入后续读取series 级细筛Read 阶段Client.Read 在用 block 查询器tsdb.NewBlockQuerier打开每个 block 时把查询区间的起止时间收敛为max(block.MinTime, filter.min)与min(block.MaxTime, filter.max)从而在 chunk 层面就跳过窗口外的样本。inRange的边界行为由 prometheus_test.go 的 TestInRange 完整覆盖例如f(3, 10, 9, 12, true)表示 block[9,12]与过滤窗口[3,10]有交集会保留而f(3, 10, 12, 15, false)表示完全在窗口外会被跳过。两个参数只设置其一时另一边界视为无限min0或max0时取 block 自身边界。实际效果过滤条件在 Explore 阶段就能把快照的统计信息打印出来blocks found / blocks skipped / min time / max time / samples / series让你在执行真正的写入前就能确认数据规模是否符合预期。2.3 标签过滤--prom-filter-label --prom-filter-label-value这两个参数组合为一个正则匹配器Read 中通过labels.MustNewMatcher(labels.MatchRegexp, c.filter.label, c.filter.labelValue)构造 matcher只选取标签值匹配正则的 series。单独设置--prom-filter-label-value而不设置--prom-filter-label时matcher 的标签名为空串等效于不过滤默认.*也是全匹配常用组合是按指标名前缀选择要迁移的指标例如--prom-filter-label__name__ --prom-filter-label-valuepromhttp.*只迁移promhttp_开头的指标注意标签过滤发生在series 级Explore 阶段的 block 统计samples/series 数并不体现标签过滤的结果因此只看 Explore 输出不能推断标签过滤后的最终数据量。2.4 --prom-concurrency并发读取快照默认值为1即单 worker 串行读取 block。从 processBlocks 的实现看它启动cc即--prom-concurrency个 goroutine从blockReadersCh通道领取 block 并行处理任一 block 读取出错会通过errCh立即终止整个迁移。由于快照读取主要受磁盘 IO 与 Prometheus TSDB 库性能约束官方迁移指南 建议把--prom-concurrency设置为 vmctl 可用 CPU 核心数以充分利用 NVMe 等高性能存储的并行读能力。3. 目标端参数--vm-* 如何写入 VictoriaMetrics--vm-*参数组在 flags.go 的 vmFlags 中定义由 initConfigVM 解析为 vm.Config最终驱动Importer。完整参数表如下参数默认值说明--vm-addrhttp://localhost:8428接收导入请求的 VictoriaMetrics 地址。单节点版本应为--httpListenAddr同值集群版本应为 vminsert 的地址--vm-user空支持环境变量VM_USERNAMEBasic Auth 用户名--vm-password空支持环境变量VM_PASSWORDBasic Auth 密码--vm-headers无附加到每个请求的 HTTP 头多个头之间用^^分隔如--vm-headersheader1:value1^^header2:value2--vm-bearer-token无用于--vm-addr的 Bearer Token--vm-account-id无租户标识格式accountID或accountID:projectIDprojectID 缺省为 0。导入集群版时必须设置--vm-concurrency2并发执行导入请求的 worker 数--vm-compresstrue是否对导入请求应用 gzip 压缩--vm-batch-size200000单个导入请求前累计的样本数--vm-significant-figures0导入前保留的有效数字位数0 表示保留全部可用于提升存储压缩率--vm-round-digits100保留的小数位数100 表示实际不截断可用于提升存储压缩率--vm-extra-label无为所有导入时序追加的标签格式keyvalue可重复设置与源标签冲突时以该参数值为准--vm-rate-limit0不限制数据传输速率上限字节/秒用于限制对目标端的压力--vm-cert-file无连接--vm-addr使用的客户端 TLS 证书路径--vm-key-file无连接--vm-addr使用的客户端 TLS 密钥路径--vm-CA-file系统 CA用于校验--vm-addr连接的 CA 文件路径--vm-server-name取自--vm-addr连接--vm-addr时使用的 TLS ServerName--vm-insecure-skip-verifyfalse是否跳过对--vm-addr的 TLS 证书校验--vm-backoff-retries10导入请求失败时的最大重试次数--vm-backoff-factor1.8每次重试后基础等待时间的放大因子必须大于 1.0--vm-backoff-min-duration2s首次重试前的最小等待时间其后每次乘以--vm-backoff-factor3.1 --vm-addr地址校验、健康检查与导入路径构造--vm-addr是整个目标端配置的核心它在源码中经历三道处理URL 合法性校验initConfigVM 先调用httputil.CheckURL(addr)校验格式就绪检查NewImporter在启动 worker 前先执行im.Ping()见 vm.go#L163-L165对应参数说明中vmctl performs initial readiness check for the given address by checking /health endpoint。目标端不健康时会立即以ping to ... failed报错而不是在迁移中途失败导入路径拼接vm.go#L126-L134// if single version importPath : addr /api/v1/import if cfg.AccountID ! { // if cluster version importPath fmt.Sprintf(%s/insert/%s/prometheus/api/v1/import, addr, cfg.AccountID) }也就是说单节点版本请求{vm-addr}/api/v1/import设置--vm-account-id后自动切换为集群 URL 格式{vm-addr}/insert/{accountID}/prometheus/api/v1/importaccountID可写为accountID:projectID形式。这正是参数说明中集群版务必追加--vm-account-id的原因——它不只是元数据而是直接决定请求 URL。3.2 认证相关--vm-user / --vm-password / --vm-headers / --vm-bearer-token四个认证参数由 auth.Generate 统一组装authCfg, err : auth.Generate( auth.WithBasicAuth(c.String(vmUser), c.String(vmPassword)), auth.WithBearer(c.String(vmBearerToken)), auth.WithHeaders(c.String(vmHeaders)))--vm-user/--vm-password支持环境变量VM_USERNAME/VM_PASSWORDflags.go#L107-L116适合在脚本中避免明文密码出现在命令行--vm-headers中的多个头必须以^^分隔例如--vm-headersMy-Auth:foobar会向每次请求附加My-Auth: foobar头常经 vmauth 等代理转发时使用--vm-bearer-token适用于以 JWT/OIDC 方式鉴权的部署。TLS 相关五个参数--vm-cert-file、--vm-key-file、--vm-CA-file、--vm-server-name、--vm-insecure-skip-verify通过promauth.NewTLSTransportmain.go#L590-L599构造http.Transport与源端 prom 模式的只读磁盘访问不同目标端是唯一走网络的方向因此 HTTPS 与 mTLS 场景下这组参数缺一不可缺省使用系统 CA 与地址中的 ServerName。3.3 --vm-concurrency / --vm-batch-size吞吐与内存的平衡--vm-concurrency默认 2决定Importer中并行发送导入请求的 worker 数量。NewImporter 为每个 worker 创建进度条并调用startWorker(ctx, bar, cfg.BatchSize, ...)每个 worker 独立从输入通道取时序、攒批、发送--vm-batch-size默认 200000 样本决定单个导入请求携带的样本数。样本攒够一个批次才发出一次 HTTP 请求批次太小会增加请求开销太大则会增加单 worker 内存占用。若设置小于 1NewImporter 会回退到 1e5二者共同决定迁移吞吐调优时建议先固定--vm-concurrency观察目标端 CPU/网络再逐步放大。3.4 --vm-significant-figures / --vm-round-digits数值降精度换压缩率两个参数都作用于写入前的指标值用于主动降低存储基数、提升磁盘压缩率--vm-significant-figuresN每个浮点值只保留 N 位有效数字N0 为默认保留全部--vm-round-digitsN只保留小数点后 N 位默认 100等效不截断。迁移历史数据时若下游只关心趋势而非原始精度例如以 4 位有效数字导入可显著减小目标端数据体积。二者语义不同——有效数字与数值量级相关小数位与量级无关可按指标特征选择。3.5 --vm-extra-label追加标签的实现方式--vm-extra-label支持重复设置以追加多个标签冲突时以参数值覆盖源标签。其实现不是逐条改写时序而是在 AddExtraLabelsToImportPath 中把每个标签编码进 import URL 的 query 参数dst fmt.Sprintf(%sextra_label%s, separator, url.QueryEscape(extraLabel))即最终请求形如/api/v1/import?extra_labelsource%3Dprometheusextra_labeldc%3Dfoo由 VictoriaMetrics 服务端在导入时统一附加。注意该函数会校验每个标签必须包含否则返回bad format for extra_label flag, it must be keyvalue错误。3.6 --vm-rate-limit按 worker 计的限速--vm-rate-limit单位为字节/秒0 表示不限速。从 vm.Config 的注释 可以确认// RateLimit defines a data transfer speed in bytes per second. // Is applied to each worker (see Concurrency) independently. RateLimit int64即限速是每 worker 独立生效的整体实际限速约为--vm-rate-limit × --vm-concurrency。在迁移高峰期保护生产 VictoriaMetrics 实例时需要按此换算设置合理值并配合 app/vmctl/limiter 中的令牌桶限速器实现平滑限速。3.7 重试退避--vm-backoff-* 三个参数导入请求失败时Importer按 backoff 策略重试首次等待至少--vm-backoff-min-duration默认 2s之后每次等待时间乘以--vm-backoff-factor默认 1.8最多重试--vm-backoff-retries次默认 10。三个参数在 initConfigVM 中通过backoff.New(bfRetries, bfFactor, bfMinDuration)组装。迁移窗口长、目标端偶发过载时可适当增大重试次数与退避因子若目标是快速失败暴露问题则可减小重试次数。4. 全局参数交互、日志与自监控prometheus子命令除上述两组参数外还合并了一组所有子命令共享的全局参数flags.go 的 globalFlags参数默认值说明-sfalse静默模式。设置后不再出现确认提示直接开始导入。适合放进 cron/CI 等非交互环境--verbosefalse打开日志的详细输出--disable-progress-barfalse关闭导入过程中的进度条避免在日志文件中产生刷屏的控制字符--pushmetrics.url无可重复把 vmctl 自身指标导入请求数、样本数、字节数、错误数等定时推送到指定地址--pushmetrics.interval10s向每个--pushmetrics.url推送指标的间隔--pushmetrics.extraLabel无可重复附加到推送指标上的标签如-pushmetrics.extraLabelinstancefoo冲突时以参数值优先--pushmetrics.header无可重复推送指标时附加的 HTTP 头--pushmetrics.disableCompressionfalse推送指标时是否禁用压缩几个结合源码的要点确认提示来自 prometheusProcessor.runExplore 结束后打印Found N blocks to import. Continue?并等待Y/n输入回答n会直接退出返回 nil非错误。-s使 prompt 跳过交互直接通过进度条由 barpool 统一管理每个Importerworker 各有一条模板见 vm.go#L183--disable-progress-bar会全局禁用自监控指标在beforeFnmain.go#L48-L65中初始化vmctl 会暴露如vmctl_importer_requests_total、vmctl_importer_samples_total、vmctl_prometheus_migration_blocks_totalprometheus.go#L195-L199等计数器。把--pushmetrics.url指向一个 VictoriaMetrics 实例后可以在迁移期间观察导入速率与错误数这也是判断是否需要调整--vm-concurrency/--vm-rate-limit的直接依据。5. 完整迁移流程与输出解读把参数落到一次真实命令上示例改编自 prometheus 迁移指南 的官方输出# 第一步在 Prometheus 上生成快照得到 /path/to/snapshot 目录 # 第二步执行迁移 ./vmctl prometheus \ --vm-addrvictoriametrics-addr:8428 \ --prom-snapshot/path/to/snapshot典型输出Prometheus import mode Prometheus snapshot stats: blocks found: 14; blocks skipped: 0; min time: 1581288163058 (2020-02-09T22:42:43Z); max time: 1582409128139 (2020-02-22T22:05:28Z); samples: 32549106; series: 27289. Found 14 blocks to import. Continue? [Y/n] y 14 / 14 [----------------------------------------] 100.00% 0 p/s Import finished! VictoriaMetrics importer stats: idle duration: 6.152953029s; time spent while importing: 44.908522491s; total samples: 32549106; samples/s: 724786.84; total bytes: 669.1 MB; bytes/s: 14.9 MB; import requests: 323; import requests retries: 0; Total time: 51.077451066s输出中的两段统计分别对应参数作用点上半段Prometheus snapshot stats由 Explore 打印blocks skipped直接反映--prom-filter-time-start/end的 block 级筛选结果下半段VictoriaMetrics importer stats由 Importer.Stats 打印import requests次数与--vm-batch-size、--vm-concurrency相关import requests retries则反映--vm-backoff-*的实际触发情况长期为 0 说明目标端稳定。若只迁移某时间段的部分数据并叠加标签过滤./vmctl prometheus --prom-snapshot/path/to/snapshot \ --prom-filter-label__name__ \ --prom-filter-label-valuepromhttp.* \ --prom-filter-time-start2020-02-07T00:07:01Z \ --prom-filter-time-end2020-02-11T00:07:01Z从源码看这条命令的筛选路径是时间窗口先裁掉 12 个不相关 blockblocks skipped: 12再对保留 block 的每个 series 应用__name__ ~ promhttp.*匹配器最终只把命中的样本送入 Importer。6. 调优与排障要点结合参数定义与 processBlocks 的错误处理给出几条实操建议磁盘 IO 受限提高--prom-concurrency建议等于可用 CPU 核数因为快照读取是本地磁盘行为worker 越多越能吃满并行读带宽目标端压力大调低--vm-concurrency默认 2设置--vm-rate-limit记得它按 worker 计必要时加大--vm-backoff-min-duration让失败请求更温和地重试目标数据体积敏感使用--vm-significant-figures或--vm-round-digits主动降低精度换取更高的存储压缩率多源数据合并用--vm-extra-label为不同迁移批次打标记如sourceprom-prod便于在 VictoriaMetrics 中区分与回溯非交互运行脚本化执行必须加-s否则命令会阻塞在Continue? [Y/n]提示上重定向日志到文件时建议加--disable-progress-bar失败定位任一 block 读取失败或导入重试耗尽都会终止整个迁移并打印具体错误cannot read block ULID: ...配合--verbose可得到更详细的日志迁移前用 Explore 阶段的 stats 输出核对 block 数与样本量可提前发现快照路径错误如指向了未包含 block 的目录会报found no blocks to import。7. 相关文档与源码索引内容路径本文参数清单来源自动生成随二进制同步docs/victoriametrics/vmctl/vmctl_prometheus_flags.mdvmctl prometheus 迁移指南含过滤与调优建议docs/victoriametrics/vmctl/prometheus.mdvmctl 总览docs/victoriametrics/vmctl/vmctl.md、app/vmctl/README.md参数定义global/prom/vm 三组 flagapp/vmctl/flags.go子命令装配与 --vm-* 配置解析app/vmctl/main.goPrometheus 快照读取客户端过滤逻辑app/vmctl/prometheus/prometheus.goblock 级时间过滤单元测试app/vmctl/prometheus/prometheus_test.go迁移主流程Explore → 并发读取 → 导入app/vmctl/prometheus.go目标端 Importer路径拼接、限速、重试app/vmctl/vm/vm.go需要注意的是vmctl_prometheus_flags.md 文件头注明其内容来自真实二进制输出Run make docs-update-flags while preparing a new release to sync flags in docs from actual binaries因此文中的所有默认值与参数语义均以当前仓库源码为准确认过与文档一致在实际部署前仍建议用vmctl prometheus --help核对所用版本的最新参数集。【免费下载链接】VictoriaMetricsVictoriaMetrics: fast, cost-effective monitoring solution and time series database项目地址: https://gitcode.com/GitHub_Trending/vi/VictoriaMetrics创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考