VictoriaMetrics 迁移指南：使用 vmctl 将 Promscale 历史指标数据迁移到 VictoriaMetrics-创锋一号

VictoriaMetrics 迁移指南：使用 vmctl 将 Promscale 历史指标数据迁移到 VictoriaMetrics

【免费下载链接】VictoriaMetricsVictoriaMetrics: fast, cost-effective monitoring solution and time series database项目地址: https://gitcode.com/GitHub_Trending/vi/VictoriaMetrics

本文介绍如何利用 VictoriaMetrics 生态中的迁移工具vmctl，通过其remote-read（远程读取）模式，将 TimescaleDB 旗下的 Promscale 中存储的历史指标数据完整迁移到 VictoriaMetrics。读完本文，你将掌握 Promscale 与 VictoriaMetrics 兼容的迁移命令、关键参数（如自定义 Remote Read API 路径、时间分片、流式模式开关）的取舍依据，以及迁移完成后的统计指标解读与调优方法。

为什么选择 remote-read 模式迁移 Promscale

Promscale 是基于 PostgreSQL/TimescaleDB 构建的指标存储服务，它实现了 Prometheus 生态的Prometheus Remote Read API。这意味着任何支持该协议的客户端都可以按时间范围与标签选择器读取其中存储的时间序列数据，VictoriaMetrics 的vmctl恰好提供了基于该协议的remote-read迁移模式。

vmctl remote-read是vmctl内置的一种迁移模式，适用于从实现了 Prometheus Remote Read API 的远端数据库迁移历史数据。除 Promscale 外，该模式同样适用于 Cortex、Mimir 以及支持 Remote Read 协议的 Thanos（详见 remote-read 模式文档）。其优势在于：

无需停机导出：完全通过 HTTP API 拉取数据，不需要对源库做快照或停机操作；
通用协议：Remote Read API 是 Prometheus 生态的标准协议，兼容面广；
可按需过滤：支持按时间范围、标签（含正则）选择需要迁移的时间序列。

在开始迁移之前，需要先了解 Remote Read API 的两种实现形态：默认的SAMPLES模式和流式STREAMED_XOR_CHUNKS模式。流式模式对源库资源消耗更小，但普及度较低。Promscale 仅支持非流式的SAMPLES模式，因此在迁移命令中必须显式关闭流式模式（--remote-read-use-stream=false）。

迁移前置准备

执行迁移前，请确认以下几点：

获取 vmctl 二进制：vmctl的源码位于 app/vmctl，可通过构建产物获取，也可参考该目录下的 Makefile 自行构建；
确认 Promscale 可达：Promscale 的 Remote Read API 地址可达，且拥有相应读取权限；
确认 VictoriaMetrics 目标可用：单机版默认监听http://<victoriametrics>:8428，集群版需要指向vminsert服务（默认端口8480），并额外设置--vm-account-id；
评估时间范围：确定要迁移的历史数据起始时间（--remote-read-filter-time-start为必填项）。

完整迁移命令与参数逐项解析

Promscale 的迁移命令如下（摘自 promscale.md）：

./vmctl remote-read \ --remote-read-src-addr=http://<promscale>:9201/read \ --remote-read-step-interval=day \ --vm-addr=http://<victoriametrics>:8428 \ --remote-read-filter-time-start=2023-08-21T00:00:00Z \ --remote-read-disable-path-append=true # promscale has custom remote read API HTTP path

--remote-read-src-addr 与 --remote-read-disable-path-append

这是 Promscale 迁移中最关键的一组参数。

在默认的 remote-read 模式下，vmctl会自动向--remote-read-src-addr拼接标准路径/api/v1/read。这一行为定义在 app/vmctl/remoteread/remoteread.go 中（常量remoteReadPath = "/api/v1/read"），请求构造时通过url.JoinPath(c.addr, remoteReadPath)拼接出最终 URL。

Promscale 的 Remote Read API 路径与标准 Prometheus 不同（其读取端点位于/read而非/api/v1/read），因此必须：

将--remote-read-src-addr指定为Promscale 的完整读取路径，即http://<promscale>:9201/read；
通过--remote-read-disable-path-append=true禁用自动路径拼接。

从源码看，当disablePathAppend为真时，客户端直接使用--remote-read-src-addr提供的完整地址作为请求 URL，不再拼接/api/v1/read：

// we should use full address from the remote-read-src-addr flag if c.disablePathAppend { u = c.addr }

这一点也可以在 flags.go 中看到该参数的官方说明：“Whether to disable automatic appending of the /api/v1/read suffix to --remote-read-src-addr”。

--remote-read-step-interval：时间分片

该参数将选定的时间范围按固定步长切分为多个子区间，逐段拉取，以降低对源库（Promscale）的单次请求压力。合法取值为month、day、hour、minute（部分版本还支持week）。

以day为例，vmctl会把2023-08-21T00:00:00Z至当前时刻切分为按天划分的多个区间。分片逻辑实现在 app/vmctl/stepper/split.go 的SplitDateRange函数中，其中month粒度会按自然月对齐到每月 1 号，以提升底层块级导出的效率。

迁移启动时vmctl会打印将要处理的分片数量并请求确认，例如：

Selected time range "2023-08-21 00:00:00 +0000 UTC" - "2023-08-21 14:11:41.561979 +0000 UTC" will be split into 1 ranges according to "day" step. Continue? [Y/n] y

若不确定历史数据规模，建议从day或hour起步，观察源库负载后再决定是否加大；
如果希望从最新数据往旧数据迁移，可配合--remote-read-filter-time-reverse反转分片顺序。

--remote-read-filter-time-start / --remote-read-filter-time-end

--remote-read-filter-time-start：必填项，以 RFC3339 格式（如2023-08-21T00:00:00Z）指定迁移数据的起始时间；
--remote-read-filter-time-end：可选项，指定迁移数据的结束时间。未设置时默认为当前时间，该逻辑在 app/vmctl/remoteread.go 的run函数中实现。

--remote-read-use-stream=false：关闭流式模式

Promscale不支持Remote Read API 的流式传输（STREAMED_XOR_CHUNKS）模式，因此在迁移时必须保持默认的SAMPLES模式，即显式传入--remote-read-use-stream=false（或直接省略该参数，因其默认值即为false）。

从 app/vmctl/remoteread/remoteread.go 的实现可以看出两种模式的差异：

非流式模式（SAMPLES）：请求头Content-Type: application/x-protobuf，响应为整体返回的ReadResponse（snappy 压缩的 protobuf）；
流式模式（STREAMED_XOR_CHUNKS）：请求头变为Content-Type: application/x-streamed-protobuf; proto=prometheus.ChunkedReadResponse，响应按块流式解析。

由于 Promscale 只能处理非流式请求，若误开流式模式将导致请求失败。

--vm-addr：配置 VictoriaMetrics 目标

--vm-addr指定数据导入的目标地址（vmctl会先通过/health端点做就绪检查）：

单机版：http://<victoriametrics>:8428，与单机版--httpListenAddr一致；
集群版：指向vminsert，形如http://<vminsert-addr>:8480，并必须额外添加--vm-account-id指定租户（格式为accountID或accountID:projectID）。

详细说明见 vmctl 主文档的 Configuring VictoriaMetrics 一节。若目标开启 Basic Auth、Bearer Token 或 TLS，可分别使用--vm-user/--vm-password、--vm-bearer-token、--vm-cert-file/--vm-key-file/--vm-CA-file/--vm-server-name/--vm-insecure-skip-verify等参数（定义见 flags.go）。

迁移过程的输出解读

一次成功的 Promscale 迁移输出如下：

Selected time range "2023-08-21 00:00:00 +0000 UTC" - "2023-08-21 14:11:41.561979 +0000 UTC" will be split into 1 ranges according to "day" step. Continue? [Y/n] y VM worker 0:↙ 82831 samples/s VM worker 1:↙ 54378 samples/s VM worker 2:↙ 121616 samples/s VM worker 3:↙ 59164 samples/s VM worker 4:↙ 59220 samples/s VM worker 5:↙ 102072 samples/s Processing ranges: 1 / 1 [████████████████████████████████████████████████████████████████████████████████████] 100.00% 2023/08/21 16:11:55 Import finished! 2023/08/21 16:11:55 VictoriaMetrics importer stats: idle duration: 0s; time spent while importing: 14.047045459s; total samples: 262111; samples/s: 18659.51; total bytes: 5.3 MB; bytes/s: 376.4 kB; import requests: 6; import requests retries: 0; 2023/08/21 16:11:55 Total time: 14.063458792s

需要关注的核心指标（详见 vmctl 主文档的 Importer stats 一节）：

指标	含义	关注点
`idle duration`	importer 等待数据填满批次的空闲时间（所有 worker 累加）	数值偏高说明源库（Promscale）拉取过慢或`--vm-concurrency`设置过高
`total samples`	导入的样本总数	可用于与源库数据量交叉核对迁移完整性
`samples/s`、`bytes/s`	导入吞吐	评估迁移耗时与调优效果的直接依据
`import requests`	发往 VictoriaMetrics 的导入请求数	与批大小`--vm-batch-size`（默认 200000）相关，批次偏大更高效
`import requests retries`	失败重试次数	非零通常意味着网络问题或目标 VM 过载

深入源码：remote-read 客户端的请求构造与数据处理

要准确理解 Promscale 迁移的行为，可以阅读 app/vmctl/remoteread/remoteread.go 中的Client.Read方法。它构造prompb.ReadRequest，包含：

StartTimestampMs/EndTimestampMs：当前分片的时间边界（注意结束时间戳会减 1 毫秒，避免区间重叠）；
Matchers：由--remote-read-filter-label/--remote-read-filter-label-value构造的标签正则匹配器（类型为LabelMatcher_RE），例如--remote-read-filter-label=__name__ --remote-read-filter-label-value="cpu_.*"只会选择指标名匹配cpu_.*正则的时间序列；
若启用流式模式，则在AcceptedResponseTypes中声明STREAMED_XOR_CHUNKS。

请求体经 protobuf 序列化后使用 snappy 压缩，并设置Content-Encoding: snappy、X-Prometheus-Remote-Read-Version: 0.1.0等头。响应侧的处理逻辑（processResponse/processStreamResponse）同时兼容 float 样本与原生直方图（native histogram）样本：原生直方图会被转换为<name>_count、<name>_sum及带vmrange标签的<name>_bucket序列，转换方式与 VictoriaMetrics 接收 Prometheus remote write 协议时的处理保持一致。

在迁移执行层面，app/vmctl/remoteread.go 中的remoteReadProcessor.run负责：按步长切分时间范围 → 向用户确认 → 启动--remote-read-concurrency（默认 1）个 worker 并发拉取各分片 → 数据经vm.Importer批量写入 VictoriaMetrics → 完成后打印导入统计。该模式还暴露了vmctl_remote_read_migration_ranges_total、vmctl_remote_read_migration_ranges_processed、vmctl_remote_read_migration_errors_total三个指标，可通过--pushmetrics.url推送监控。

迁移调优与实战技巧

以下技巧来自 vmctl 主文档的 Migration tips 一节，同样适用于 Promscale 迁移场景：

并发与批次调优

--remote-read-concurrency：控制并发的 remote read 拉取 worker 数（默认 1）。当 Promscale 响应较慢时，适当提高该值可显著改善吞吐；
--vm-concurrency：控制发往 VictoriaMetrics 的导入并发（默认 2）。注意每个 worker 在目标 VM 上最多可占满一个 vCPU 核心，应根据目标机的 CPU 配额设置，避免拖垮正在提供查询服务的 VictoriaMetrics；
--vm-batch-size：控制批量大小（默认 200000 样本），推荐 5 万到 50 万之间以兼顾内存与导入效率。

静默模式与进度条

默认情况下vmctl会在导入前等待用户确认（Continue? [Y/n]），在无人值守的自动化任务中可加-s跳过确认；
加--disable-progress-bar可关闭导入进度条。

限速与标签管理

--vm-rate-limit：按字节/秒限制数据传输速率（按 worker 生效），可在迁移时降低对目标磁盘或数据库的压力；
--vm-extra-label：为所有导入序列附加额外标签，可多次指定，如--vm-extra-label label1=value1 --vm-extra-label label2=value2；若与序列已有标签冲突，flag 值优先；
--vm-significant-figures/--vm-round-digits：限制数值的有效数字位数或将数值四舍五入到指定小数位，可提升磁盘压缩率，适合以聚合结果（如avg、rate）为主的指标。

迁移是回填过程

迁移本质上是向 VictoriaMetrics 回填历史数据。建议阅读仓库根目录 README 中关于 backfilling 的说明，并注意：vmctl不提供 relabel 等标签管理能力，如需标签改写，应使用 VictoriaMetrics 自身的 relabeling 能力。

数据一致性提示

如果在开启流式模式（--remote-read-use-stream=true，仅适用于 Mimir 等支持流式协议的数据库）时观察到写入 VictoriaMetrics 的样本数多于源库，这通常源于源库底层 chunk 存储结构，开启 VictoriaMetrics 的去重（deduplication）功能即可在查询与存储层面消除重复样本。Promscale 迁移使用非流式模式，一般不会遇到该问题。

常见问题排查

现象	原因与对策
请求超时 /`context canceled`错误	大数据量迁移时远端读取客户端超时（默认 5 分钟），增大`--remote-read-http-timeout`即可
返回 404 / 路径错误	未设置`--remote-read-disable-path-append=true`，导致`vmctl`向 Promscale 拼接了不存在的`/api/v1/read`路径
返回认证错误	源库开启认证时，使用`--remote-read-user`/`--remote-read-password`（也支持环境变量`REMOTE_READ_USERNAME`/`REMOTE_READ_PASSWORD`）或`--remote-read-headers`传递自定义认证头；TLS 场景使用`--remote-read-cert-file`、`--remote-read-CA-file`等参数
导入重试次数非零	检查网络与目标 VictoriaMetrics 负载，必要时降低`--vm-concurrency`或开启限速
确认提示阻塞自动化脚本	追加`-s`静默模式参数跳过交互确认

总结

将 Promscale 中的历史指标迁移到 VictoriaMetrics，核心是vmctl remote-read模式配合三个关键参数：指向完整读取路径的--remote-read-src-addr、关闭自动路径拼接的--remote-read-disable-path-append=true，以及关闭流式模式的--remote-read-use-stream=false。在此基础上，通过--remote-read-step-interval控制分片粒度、--remote-read-filter-time-start限定迁移范围，再结合并发、批次与限速参数，即可在控制源库与目标负载的前提下完成高效、可验证的历史数据迁移。更完整的参数列表可随时通过./vmctl remote-read --help查看，相关的模式文档与源码分别位于 remoteread.md 与 app/vmctl/remoteread。

【免费下载链接】VictoriaMetricsVictoriaMetrics: fast, cost-effective monitoring solution and time series database项目地址: https://gitcode.com/GitHub_Trending/vi/VictoriaMetrics

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

企业官网建设流程全解析