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 模式迁移 PromscalePromscale 是基于 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-streamfalse。迁移前置准备执行迁移前请确认以下几点获取 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-addrhttp://promscale:9201/read \ --remote-read-step-intervalday \ --vm-addrhttp://victoriametrics:8428 \ --remote-read-filter-time-start2023-08-21T00:00:00Z \ --remote-read-disable-path-appendtrue # 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-appendtrue禁用自动路径拼接。从源码看当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-streamfalse关闭流式模式Promscale不支持Remote Read API 的流式传输STREAMED_XOR_CHUNKS模式因此在迁移时必须保持默认的SAMPLES模式即显式传入--remote-read-use-streamfalse或直接省略该参数因其默认值即为false。从 app/vmctl/remoteread/remoteread.go 的实现可以看出两种模式的差异非流式模式SAMPLES请求头Content-Type: application/x-protobuf响应为整体返回的ReadResponsesnappy 压缩的 protobuf流式模式STREAMED_XOR_CHUNKS请求头变为Content-Type: application/x-streamed-protobuf; protoprometheus.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 durationimporter 等待数据填满批次的空闲时间所有 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-valuecpu_.*只会选择指标名匹配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 label1value1 --vm-extra-label label2value2若与序列已有标签冲突flag 值优先--vm-significant-figures/--vm-round-digits限制数值的有效数字位数或将数值四舍五入到指定小数位可提升磁盘压缩率适合以聚合结果如avg、rate为主的指标。迁移是回填过程迁移本质上是向 VictoriaMetrics 回填历史数据。建议阅读仓库根目录 README 中关于 backfilling 的说明并注意vmctl不提供 relabel 等标签管理能力如需标签改写应使用 VictoriaMetrics 自身的 relabeling 能力。数据一致性提示如果在开启流式模式--remote-read-use-streamtrue仅适用于 Mimir 等支持流式协议的数据库时观察到写入 VictoriaMetrics 的样本数多于源库这通常源于源库底层 chunk 存储结构开启 VictoriaMetrics 的去重deduplication功能即可在查询与存储层面消除重复样本。Promscale 迁移使用非流式模式一般不会遇到该问题。常见问题排查现象原因与对策请求超时 /context canceled错误大数据量迁移时远端读取客户端超时默认 5 分钟增大--remote-read-http-timeout即可返回 404 / 路径错误未设置--remote-read-disable-path-appendtrue导致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-appendtrue以及关闭流式模式的--remote-read-use-streamfalse。在此基础上通过--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），仅供参考
