VictoriaMetrics vmctl 命令行参考子命令结构、全局选项与 Flags 文档的生成机制【免费下载链接】VictoriaMetricsVictoriaMetrics: fast, cost-effective monitoring solution and time series database项目地址: https://gitcode.com/GitHub_Trending/vi/VictoriaMetrics本文围绕docs/victoriametrics/vmctl/vmctl_flags.md这份由二进制自动生成的 vmctl 帮助输出一一展开说明 vmctl 提供的 8 个子命令prometheus、influx、opentsdb、remote-read、mimir、thanos、vm-native、verify-block与全局选项的完整清单并结合 app/vmctl/main.go 与 app/vmctl/flags.go 的源码印证每个命令的实际执行入口以及 docs/Makefile 中docs-update-flags目标如何将真实二进制的帮助信息同步进文档。读完后你可以准确理解 vmctl 命令行的结构、各迁移模式的代码入口以及如何查阅每个子命令的完整参数。文档来源从真实二进制自动生成的帮助信息vmctl_flags.md顶部有一行显眼的注释!-- The file should not be updated manually. Run make docs-update-flags while preparing a new release to sync flags in docs from actual binaries. --也就是说这份文档不是手写维护的而是在准备新发布版本时由 docs/Makefile 中的docs-update-flags目标 checkout 对应 release tag、编译出真实二进制后把其--help输出回填到文档里。该目标还会用sed做规范化处理例如删除Total time:行、去掉VERSION:行以减少 diff 噪音。这个机制保证了文档中的命令与选项清单和发布二进制严格一致不会漂移。从引用方式看vmctl_flags.md本身设置了render: never它由 vmctl 主文档 通过 Hugo 的{{% content vmctl_flags.md %}}短代码内嵌到 Command-line flags 小节中读者在 vmctl 总览文档中即可看到完整的顶层帮助输出。顶层帮助输出名称、用法与子命令清单vmctl_flags.md收录的完整顶层帮助输出如下NAME: vmctl - VictoriaMetrics command-line tool USAGE: vmctl [global options] command [command options] COMMANDS: opentsdb Migrate time series from OpenTSDB influx Migrate time series from InfluxDB remote-read Migrate time series via Prometheus remote-read protocol prometheus Migrate time series from Prometheus mimir Migrate time series from Mimir object storage or local filesystem thanos Migrate time series from Thanos blocks (supports raw and downsampled data) vm-native Migrate time series between VictoriaMetrics installations verify-block Verifies exported block with VictoriaMetrics Native format help, h Shows a list of commands or help for one command GLOBAL OPTIONS: --help, -h show help --version, -v print the version逐条对照源码这些命令与 app/vmctl/main.go 中cli.App{Commands: ...}的注册完全一一对应。该工具基于github.com/urfave/cli/v2框架实现Name为vmctl、Usage为VictoriaMetrics command-line tool版本号取自 lib/buildinfo 中的buildinfo.Version因此--version, -v输出的是编译期注入的版本号。8 个子命令与源码入口的对应关系如下子命令帮助文本中的用途说明源码位置数据源opentsdbMigrate time series from OpenTSDBmain.goOpenTSDB HTTP APIinfluxMigrate time series from InfluxDBmain.goInfluxDB1.x/2.xremote-readMigrate time series via Prometheus remote-read protocolmain.go任意支持 Prometheus remote-read 的存储Thanos、Cortex、Mimir、PromscaleprometheusMigrate time series from Prometheusmain.goPrometheus snapshot 文件mimirMigrate time series from Mimir object storage or local filesystemmain.goMimir 对象存储/本地目录中的 blockthanosMigrate time series from Thanos blocks (supports raw and downsampled data)main.goThanos block 目录支持降采样数据vm-nativeMigrate time series between VictoriaMetrics installationsmain.go另一个 VictoriaMetrics 实例的 native/JSON 导出接口verify-blockVerifies exported block with VictoriaMetrics Native formatmain.go本地导出的数据块文件其中help, h是 urfave/cli 框架自带的帮助命令并非项目代码显式注册。各子命令的完整参数清单并不在这份文档里而是分别维护在同目录下的兄弟文档中例如 vmctl_prometheus_flags.md、vmctl_influx_flags.md、vmctl_opentsdb_flags.md、vmctl_remote-read_flags.md、vmctl_mimir_flags.md、vmctl_thanos_flags.md、vmctl_vm-native_flags.md同样由二进制帮助输出生成。全局选项与隐藏在子命令里的通用标志顶层帮助中GLOBAL OPTIONS只列出了--help, -h和--version, -v。结合源码可以解释这一现象cli.App本身没有注册额外的 app 级 flag而--help/--version是框架内置行为。真正通用的一批标志静默模式、日志、进度条、指标推送等定义在 flags.go 的globalFlags中并通过mergeFlags合并进每个子命令的 Flags 列表因此它们在vmctl command --help中可见而不是在顶层。这是阅读 vmctl 帮助输出时的一个重要结构特点。globalFlags包括标志类型/默认值作用-sbool默认 false静默模式跳过导入前的用户确认提示--verbosebool默认 false开启更详细的日志输出--disable-progress-barbool默认 false禁用导入过程中的进度条--pushmetrics.urlstringSlice将 vmctl 内部指标推送到指定地址用于监控迁移进度--pushmetrics.intervalduration默认 10s向每个--pushmetrics.url推送指标的间隔--pushmetrics.extraLabelstringSlice附加到推送指标的额外标签可多次设置--pushmetrics.headerstringSlice推送指标请求附加的 HTTP 头可多次设置--pushmetrics.disableCompressionbool推送指标时是否禁用压缩这些标志的实际生效点在 main.go 的beforeFn钩子中每个命令执行前都会依次调用flag.Parse()、initSecretFlags()初始化敏感标志、logger.Init()读取-s与--disable-progress-bar调用netutil.EnableIPv6()并通过pushmetrics.InitWith构建指标推送器。这解释了为什么各迁移模式文档中都有 pushmetrics 相关的监控用法示例。除通用标志外每个子命令还有两类参数源端参数按模式前缀区分如influx-addr、prom-snapshot、otsdb-addr、thanos-snapshot、mimir-path、remote-read-src-addr等定义在 flags.go 中各模式的xxxFlags变量里目标端参数vm-前缀如--vm-addr默认http://localhost:8428、--vm-account-id、--vm-concurrency默认 2、--vm-batch-size默认 200000、--vm-compress默认 true等定义在 flags.go 的vmFlags中被合并进除vm-native/verify-block外的所有命令。vm-native模式由于源端也是 VictoriaMetrics不使用vmFlags而是使用独立的vm-native-src-*/vm-native-dst-*标志对同样定义在 flags.go并支持--vm-intercluster集群对集群迁移模式。各子命令的执行流程源码视角从源码结构看所有迁移类命令遵循同一套骨架解析源端配置 → 创建源端 client →initConfigVM构建目标端配置 →vm.NewImporter创建导入器 → 启动对应的 processor。几个值得注意的实现细节prometheus 与 mimir、thanos共享 snapshot 读取管线prometheus命令要求--prom-snapshot指向一个必填的 Prometheus snapshot 目录通过 app/vmctl/prometheus 中的 client 读取 blockmimir与thanos复用同一个prometheusProcessor见 main.go 中 mimir 分支同样实例化prometheusProcessor因为 Mimir/Thanos 的 block 与 Prometheus block 格式同源。thanos额外支持--thanos-aggr-typescount、sum、min、max、counter用于从降采样 block 中导入指定聚合类型每个聚合会被导入为带后缀的独立指标。remote-read默认过滤__name__支持流式块remote-read客户端在用户未显式指定--remote-read-filter-label/--remote-read-filter-label-value时默认使用__name__/.*作为过滤条件见 main.go 中的向后兼容默认值。--remote-read-use-stream决定使用 SAMPLES 还是 STREAMED_XOR_CHUNKS 模式--remote-read-step-interval必填控制把迁移切分为 month/week/day/hour/minute 级别的多个时间区间配合--remote-read-filter-time-reverse可倒序迁移。vm-nativeVM 实例间迁移含完整重试与连接池vm-native是文档中between VictoriaMetrics installations模式的实现。它要求--vm-native-src-addr、--vm-native-dst-addr与--vm-native-filter-time-start三个必填项--vm-native-filter-match默认为{__name__!}。源码中的几个细节main.go通过backoff.New构建指数退避重试器默认 10 次重试、1.8 倍因子、最小等待 2 秒源端与目标端各自创建独立的 HTTP TransportMaxIdleConnsPerHost设置为并发数cc以保持每个 worker 一条空闲连接、减少连接抖动--vm-native-disable-binary-protocol为 false 时使用 VictoriaMetrics 的二进制 native 导出协议网络与资源开销更小置 true 则退回 JSON-line 格式后者支持源端已配置去重deduplication的场景--vm-intercluster模式下vmctl 会自动发现源集群的租户并逐个迁移tenantID 自动拼接在 URL 中。这些端到端行为在 apptest/tests 下有多条集成测试覆盖例如 vmctl_native_migration_test.go、vmctl_prometheus_migration_test.go、vmctl_mimir_migration_test.go、vmctl_thanos_migration_test.go、vmctl_opentsdb_migration_test.go、vmctl_remote_read_mogration_test.go可以作为各模式调用关系的验证依据。verify-block校验 native 格式导出块verify-block是唯一带位置参数的命令块文件路径作为c.Args().First()传入未提供时直接以错误退出you must provide path for exported data block。可选的--gunzip标志表示导出块经过 GNU zip 压缩解析时使用gzip编码。校验逻辑调用 lib/protoparser 的stream.Parse流式遍历块中的每个stream.Block并计数最终打印successfully verified block at path..., blockCount...见 main.go。典型用法是先用curl localhost:8428/api/v1/export/native把数据导出到本地再在上传前校验完整性这正是 vmctl 总览文档 中 Verifying exported blocks from VictoriaMetrics 小节描述的运维场景。运行期行为信号处理、指标推送与收尾顶层帮助没有展示、但影响每次运行的还有 main.go 中的运行期逻辑中断处理signal.Notify监听SIGINT与SIGTERM。收到信号时打印 Execution cancelled若导入器已创建则调用importer.Close()收尾再取消上下文保证 Ctrl-C 能优雅退出而非留下半成品请求指标推送收尾app.Run返回后调用pushmetrics.StopAndPush()确保最后一批指标也被推送出去耗时统计无论成功与否程序最后打印Total time: duration。这也解释了为什么 docs/Makefile 的docs-update-vmctl-flags流程要用sed把各 flags 文档中的Total time:行删掉——帮助输出捕获自真实运行需要剔除这类运行时噪音。如何获取并查看全部标志获取二进制官方发布包中的vmutils-*归档包含vmctl也可在仓库根目录执行make vmctl开发构建或make vmctl-prod生产构建输出到bin目录make package-vmctl构建 Docker 镜像相关说明见 vmctl 总览文档 的 How to build 小节顶层帮助vmctl --help对应本文开头的vmctl_flags.md输出子命令完整参数vmctl command --help对应各vmctl_command_flags.md文档的内容例如vmctl influx --help会列出influx-*源端参数与vm-*目标端参数的完整集合集群版注意向 Cluster 版本导入时--vm-addr应指向 vminsert 的地址默认端口 8480并额外设置--vm-account-id可写成accountID:projectID形式。小结vmctl_flags.md虽然只是一份简短的帮助输出但它准确刻画了 vmctl 的顶层命令面7 个数据迁移/校验子命令opentsdb、influx、remote-read、prometheus、mimir、thanos、vm-native加verify-block与框架内置的--help/--version全局选项。结合 app/vmctl/main.go 的命令注册结构、app/vmctl/flags.go 的三组标志定义通用globalFlags、目标端vmFlags、各源端专属标志以及 docs/Makefile 的docs-update-flags生成流程可以确认这份文档与源码之间是严格同步的文档描述什么命令main.go就注册什么命令每个子命令的完整参数则散见于各vmctl_*_flags.md兄弟文档与对应的xxxFlags变量中按需查阅即可。【免费下载链接】VictoriaMetricsVictoriaMetrics: fast, cost-effective monitoring solution and time series database项目地址: https://gitcode.com/GitHub_Trending/vi/VictoriaMetrics创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 VictoriaMetrics vmctl 命令行参考：子命令结构、全局选项与 Flags 文档的生成机制
VictoriaMetrics vmctl 命令行参考子命令结构、全局选项与 Flags 文档的生成机制【免费下载链接】VictoriaMetricsVictoriaMetrics: fast, cost-effective monitoring solution and time series database项目地址: https://gitcode.com/GitHub_Trending/vi/VictoriaMetrics本文围绕docs/victoriametrics/vmctl/vmctl_flags.md这份由二进制自动生成的 vmctl 帮助输出一一展开说明 vmctl 提供的 8 个子命令prometheus、influx、opentsdb、remote-read、mimir、thanos、vm-native、verify-block与全局选项的完整清单并结合 app/vmctl/main.go 与 app/vmctl/flags.go 的源码印证每个命令的实际执行入口以及 docs/Makefile 中docs-update-flags目标如何将真实二进制的帮助信息同步进文档。读完后你可以准确理解 vmctl 命令行的结构、各迁移模式的代码入口以及如何查阅每个子命令的完整参数。文档来源从真实二进制自动生成的帮助信息vmctl_flags.md顶部有一行显眼的注释!-- The file should not be updated manually. Run make docs-update-flags while preparing a new release to sync flags in docs from actual binaries. --也就是说这份文档不是手写维护的而是在准备新发布版本时由 docs/Makefile 中的docs-update-flags目标 checkout 对应 release tag、编译出真实二进制后把其--help输出回填到文档里。该目标还会用sed做规范化处理例如删除Total time:行、去掉VERSION:行以减少 diff 噪音。这个机制保证了文档中的命令与选项清单和发布二进制严格一致不会漂移。从引用方式看vmctl_flags.md本身设置了render: never它由 vmctl 主文档 通过 Hugo 的{{% content vmctl_flags.md %}}短代码内嵌到 Command-line flags 小节中读者在 vmctl 总览文档中即可看到完整的顶层帮助输出。顶层帮助输出名称、用法与子命令清单vmctl_flags.md收录的完整顶层帮助输出如下NAME: vmctl - VictoriaMetrics command-line tool USAGE: vmctl [global options] command [command options] COMMANDS: opentsdb Migrate time series from OpenTSDB influx Migrate time series from InfluxDB remote-read Migrate time series via Prometheus remote-read protocol prometheus Migrate time series from Prometheus mimir Migrate time series from Mimir object storage or local filesystem thanos Migrate time series from Thanos blocks (supports raw and downsampled data) vm-native Migrate time series between VictoriaMetrics installations verify-block Verifies exported block with VictoriaMetrics Native format help, h Shows a list of commands or help for one command GLOBAL OPTIONS: --help, -h show help --version, -v print the version逐条对照源码这些命令与 app/vmctl/main.go 中cli.App{Commands: ...}的注册完全一一对应。该工具基于github.com/urfave/cli/v2框架实现Name为vmctl、Usage为VictoriaMetrics command-line tool版本号取自 lib/buildinfo 中的buildinfo.Version因此--version, -v输出的是编译期注入的版本号。8 个子命令与源码入口的对应关系如下子命令帮助文本中的用途说明源码位置数据源opentsdbMigrate time series from OpenTSDBmain.goOpenTSDB HTTP APIinfluxMigrate time series from InfluxDBmain.goInfluxDB1.x/2.xremote-readMigrate time series via Prometheus remote-read protocolmain.go任意支持 Prometheus remote-read 的存储Thanos、Cortex、Mimir、PromscaleprometheusMigrate time series from Prometheusmain.goPrometheus snapshot 文件mimirMigrate time series from Mimir object storage or local filesystemmain.goMimir 对象存储/本地目录中的 blockthanosMigrate time series from Thanos blocks (supports raw and downsampled data)main.goThanos block 目录支持降采样数据vm-nativeMigrate time series between VictoriaMetrics installationsmain.go另一个 VictoriaMetrics 实例的 native/JSON 导出接口verify-blockVerifies exported block with VictoriaMetrics Native formatmain.go本地导出的数据块文件其中help, h是 urfave/cli 框架自带的帮助命令并非项目代码显式注册。各子命令的完整参数清单并不在这份文档里而是分别维护在同目录下的兄弟文档中例如 vmctl_prometheus_flags.md、vmctl_influx_flags.md、vmctl_opentsdb_flags.md、vmctl_remote-read_flags.md、vmctl_mimir_flags.md、vmctl_thanos_flags.md、vmctl_vm-native_flags.md同样由二进制帮助输出生成。全局选项与隐藏在子命令里的通用标志顶层帮助中GLOBAL OPTIONS只列出了--help, -h和--version, -v。结合源码可以解释这一现象cli.App本身没有注册额外的 app 级 flag而--help/--version是框架内置行为。真正通用的一批标志静默模式、日志、进度条、指标推送等定义在 flags.go 的globalFlags中并通过mergeFlags合并进每个子命令的 Flags 列表因此它们在vmctl command --help中可见而不是在顶层。这是阅读 vmctl 帮助输出时的一个重要结构特点。globalFlags包括标志类型/默认值作用-sbool默认 false静默模式跳过导入前的用户确认提示--verbosebool默认 false开启更详细的日志输出--disable-progress-barbool默认 false禁用导入过程中的进度条--pushmetrics.urlstringSlice将 vmctl 内部指标推送到指定地址用于监控迁移进度--pushmetrics.intervalduration默认 10s向每个--pushmetrics.url推送指标的间隔--pushmetrics.extraLabelstringSlice附加到推送指标的额外标签可多次设置--pushmetrics.headerstringSlice推送指标请求附加的 HTTP 头可多次设置--pushmetrics.disableCompressionbool推送指标时是否禁用压缩这些标志的实际生效点在 main.go 的beforeFn钩子中每个命令执行前都会依次调用flag.Parse()、initSecretFlags()初始化敏感标志、logger.Init()读取-s与--disable-progress-bar调用netutil.EnableIPv6()并通过pushmetrics.InitWith构建指标推送器。这解释了为什么各迁移模式文档中都有 pushmetrics 相关的监控用法示例。除通用标志外每个子命令还有两类参数源端参数按模式前缀区分如influx-addr、prom-snapshot、otsdb-addr、thanos-snapshot、mimir-path、remote-read-src-addr等定义在 flags.go 中各模式的xxxFlags变量里目标端参数vm-前缀如--vm-addr默认http://localhost:8428、--vm-account-id、--vm-concurrency默认 2、--vm-batch-size默认 200000、--vm-compress默认 true等定义在 flags.go 的vmFlags中被合并进除vm-native/verify-block外的所有命令。vm-native模式由于源端也是 VictoriaMetrics不使用vmFlags而是使用独立的vm-native-src-*/vm-native-dst-*标志对同样定义在 flags.go并支持--vm-intercluster集群对集群迁移模式。各子命令的执行流程源码视角从源码结构看所有迁移类命令遵循同一套骨架解析源端配置 → 创建源端 client →initConfigVM构建目标端配置 →vm.NewImporter创建导入器 → 启动对应的 processor。几个值得注意的实现细节prometheus 与 mimir、thanos共享 snapshot 读取管线prometheus命令要求--prom-snapshot指向一个必填的 Prometheus snapshot 目录通过 app/vmctl/prometheus 中的 client 读取 blockmimir与thanos复用同一个prometheusProcessor见 main.go 中 mimir 分支同样实例化prometheusProcessor因为 Mimir/Thanos 的 block 与 Prometheus block 格式同源。thanos额外支持--thanos-aggr-typescount、sum、min、max、counter用于从降采样 block 中导入指定聚合类型每个聚合会被导入为带后缀的独立指标。remote-read默认过滤__name__支持流式块remote-read客户端在用户未显式指定--remote-read-filter-label/--remote-read-filter-label-value时默认使用__name__/.*作为过滤条件见 main.go 中的向后兼容默认值。--remote-read-use-stream决定使用 SAMPLES 还是 STREAMED_XOR_CHUNKS 模式--remote-read-step-interval必填控制把迁移切分为 month/week/day/hour/minute 级别的多个时间区间配合--remote-read-filter-time-reverse可倒序迁移。vm-nativeVM 实例间迁移含完整重试与连接池vm-native是文档中between VictoriaMetrics installations模式的实现。它要求--vm-native-src-addr、--vm-native-dst-addr与--vm-native-filter-time-start三个必填项--vm-native-filter-match默认为{__name__!}。源码中的几个细节main.go通过backoff.New构建指数退避重试器默认 10 次重试、1.8 倍因子、最小等待 2 秒源端与目标端各自创建独立的 HTTP TransportMaxIdleConnsPerHost设置为并发数cc以保持每个 worker 一条空闲连接、减少连接抖动--vm-native-disable-binary-protocol为 false 时使用 VictoriaMetrics 的二进制 native 导出协议网络与资源开销更小置 true 则退回 JSON-line 格式后者支持源端已配置去重deduplication的场景--vm-intercluster模式下vmctl 会自动发现源集群的租户并逐个迁移tenantID 自动拼接在 URL 中。这些端到端行为在 apptest/tests 下有多条集成测试覆盖例如 vmctl_native_migration_test.go、vmctl_prometheus_migration_test.go、vmctl_mimir_migration_test.go、vmctl_thanos_migration_test.go、vmctl_opentsdb_migration_test.go、vmctl_remote_read_mogration_test.go可以作为各模式调用关系的验证依据。verify-block校验 native 格式导出块verify-block是唯一带位置参数的命令块文件路径作为c.Args().First()传入未提供时直接以错误退出you must provide path for exported data block。可选的--gunzip标志表示导出块经过 GNU zip 压缩解析时使用gzip编码。校验逻辑调用 lib/protoparser 的stream.Parse流式遍历块中的每个stream.Block并计数最终打印successfully verified block at path..., blockCount...见 main.go。典型用法是先用curl localhost:8428/api/v1/export/native把数据导出到本地再在上传前校验完整性这正是 vmctl 总览文档 中 Verifying exported blocks from VictoriaMetrics 小节描述的运维场景。运行期行为信号处理、指标推送与收尾顶层帮助没有展示、但影响每次运行的还有 main.go 中的运行期逻辑中断处理signal.Notify监听SIGINT与SIGTERM。收到信号时打印 Execution cancelled若导入器已创建则调用importer.Close()收尾再取消上下文保证 Ctrl-C 能优雅退出而非留下半成品请求指标推送收尾app.Run返回后调用pushmetrics.StopAndPush()确保最后一批指标也被推送出去耗时统计无论成功与否程序最后打印Total time: duration。这也解释了为什么 docs/Makefile 的docs-update-vmctl-flags流程要用sed把各 flags 文档中的Total time:行删掉——帮助输出捕获自真实运行需要剔除这类运行时噪音。如何获取并查看全部标志获取二进制官方发布包中的vmutils-*归档包含vmctl也可在仓库根目录执行make vmctl开发构建或make vmctl-prod生产构建输出到bin目录make package-vmctl构建 Docker 镜像相关说明见 vmctl 总览文档 的 How to build 小节顶层帮助vmctl --help对应本文开头的vmctl_flags.md输出子命令完整参数vmctl command --help对应各vmctl_command_flags.md文档的内容例如vmctl influx --help会列出influx-*源端参数与vm-*目标端参数的完整集合集群版注意向 Cluster 版本导入时--vm-addr应指向 vminsert 的地址默认端口 8480并额外设置--vm-account-id可写成accountID:projectID形式。小结vmctl_flags.md虽然只是一份简短的帮助输出但它准确刻画了 vmctl 的顶层命令面7 个数据迁移/校验子命令opentsdb、influx、remote-read、prometheus、mimir、thanos、vm-native加verify-block与框架内置的--help/--version全局选项。结合 app/vmctl/main.go 的命令注册结构、app/vmctl/flags.go 的三组标志定义通用globalFlags、目标端vmFlags、各源端专属标志以及 docs/Makefile 的docs-update-flags生成流程可以确认这份文档与源码之间是严格同步的文档描述什么命令main.go就注册什么命令每个子命令的完整参数则散见于各vmctl_*_flags.md兄弟文档与对应的xxxFlags变量中按需查阅即可。【免费下载链接】VictoriaMetricsVictoriaMetrics: fast, cost-effective monitoring solution and time series database项目地址: https://gitcode.com/GitHub_Trending/vi/VictoriaMetrics创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考