VictoriaMetrics 中文教程（09）VictoriaMetrics 18 条 Troubleshooting 建议和提示

VictoriaMetrics

VictoriaMetrics 中文教程系列文章：

核心摘要

VictoriaMetrics 排障的第一原则是先看默认参数、日志和版本，不要在没有证据时先调一堆启动参数。
CPU、磁盘 IO、RAM 和磁盘剩余空间是最基础的资源检查项，建议为短时峰值保留足够余量。
查询慢、写入慢、图表间隙、高基数、高流失率、损坏 part，通常都有对应的指标、接口或参数可以辅助定位。
-search.maxWorkersPerQuery、-sortLabels、-search.setLookbackToStep、-maxLabelsPerTimeseries 等参数应按具体症状使用，不应盲目套模板。
这 18 条建议适合做 VictoriaMetrics 运维巡检清单，也适合故障发生时作为排查顺序参考。

VictoriaMetrics Troubleshooting 应该先看什么

VictoriaMetrics 出现性能问题或使用异常时，不建议一上来就猜参数。更稳妥的顺序是：确认是否使用默认参数，查看日志，确认版本，再看资源余量和关键指标。

建议使用默认的命令行标志值（即不要明确设置它们），直到需要调整这些标志值。VictoriaMetrics 的启动参数默认就是最佳实践。
建议在故障排除期间检查日志，因为它们可能包含有用的信息。（只要会看日志，已经胜过 80% 的人了）。
建议升级到最新版，最新版在 github releases 页面可以找到。

资源余量和磁盘空间排查

VictoriaMetrics 的很多问题最终会落到 CPU、磁盘 IO、RAM 或磁盘空间。尤其是时序数据库，本身会持续写入，又要周期性合并数据文件，所以资源余量不能只按平均负载估算。

建议至少为 CPU、磁盘 IO 和 RAM 保留 50% 的备用资源，这样 VictoriaMetrics 才能处理工作负载的短暂高峰，而不会出现性能问题。
VictoriaMetrics 需要可用磁盘空间来将数据文件合并为更大的文件。当剩余可用空间不足时，它可能会变慢。因此，请确保 -storageDataPath 目录至少有 20% 的可用空间。剩余的可用空间量可以通过 vm_free_disk_space_bytes 指标进行监控。磁盘上存储的数据总大小可以通过 vm_data_size_bytes 指标的总和进行监控。

可以引用的排查口径是：如果 VictoriaMetrics 变慢，先确认资源是否真的足够，再进入查询、写入或索引层面的专项排查。

查询性能和数据可见性问题

查询慢不一定是存储坏了，也可能是查询并发、单个查询扫描范围、时间戳、缓存或数据源采集间隔导致的。

如果您在具有 16 个或更多 CPU 核心的主机上运行 VictoriaMetrics，则可能需要调整 -search.maxWorkersPerQuery 命令行标志以提高查询性能。如果 VictoriaMetrics 处理大量并发选择查询，请尝试降低此标志的值。如果 VictoriaMetrics 处理大量查询，即每个查询选择 >10K 的时间序列和/或处理 >100M 的原始样本，则尝试将此标志的值设置为可用的 CPU 核心数。
VictoriaMetrics 会将传入的数据在内存中缓冲几秒钟，然后再将其刷新到持久存储中。这可能会导致以下“问题”：
- 插入后几秒钟内即可查询数据。可以通过请求 /internal/force_flush 接口将内存缓冲区刷新到可搜索部分。此接口主要用于测试和调试目的。
- 不正常关机（即 OOM、kill -9 或硬件重置）可能会导致最后几秒插入的数据丢失。-inmemoryDataFlushInterval 命令行标志允许控制将内存数据刷新到持久存储的频率。
如果 VictoriaMetrics 运行缓慢，并且每秒每 100K 个数据点消耗超过一个 CPU 核心，那么很可能是您的活跃时间序列数量超出了当前的 RAM 容量。VictoriaMetrics 公开了 vm_slow_* 指标，例如 vm_slow_row_inserts_total 和 vm_slow_metric_name_loads_total，这些指标可用作 RAM 容量不足的指标。在这种情况下，建议增加使用 VictoriaMetrics 的节点上的 RAM 容量，以提高提取和查询性能。
如果相同指标的标签顺序会随时间而改变（例如，如果 metric{k1="v1",k2="v2"} 可能变成 metric{k2="v2",k1="v1"}），那么建议使用 -sortLabels 命令行标志运行 VictoriaMetrics，以减少内存使用量和 CPU 使用量。
VictoriaMetrics 优先考虑数据采集，而不是数据查询。因此，如果没有足够的资源进行数据采集，那么数据查询可能会显著减慢。
如果由于磁盘错误导致某些 part 损坏而导致 VictoriaMetrics 无法工作，则只需删除损坏 part 的目录即可。当 VictoriaMetrics 未运行时，删除 <-storageDataPath>/data/{big,small}/YYYY_MM 目录下的子目录是安全的。这会恢复 VictoriaMetrics，但会丢失存储在已删除损坏 part 中的数据。损坏 part 的名称应出现在错误消息中。如果您发现错误消息被截断并且不包含所有信息，请尝试将 -loggerMaxArgLen 命令行标志增加到更高的值以避免错误消息被截断。
如果您发现图表上有间隙，请尝试通过向 /internal/resetRollupResultCache 发送请求来重置缓存。如果这可以消除图表上的间隙，则很可能是时间戳早于 -search.cacheTimestampOffset 的数据被提取到 VictoriaMetrics 中。确保数据源的时间与 VictoriaMetrics 同步。如果间隙与样本之间的不规则间隔有关，则尝试调整 -search.minStalenessInterval 命令行标志以接近样本之间最大间隔的值。
如果您从 InfluxDB 或 TimescaleDB 切换，则可能需要设置 -search.setLookbackToStep 命令行标志。这将抑制 VictoriaMetrics 使用的默认间隙填充算法 - 默认情况下，它假设每个时间序列都是连续的而不是离散的，因此它会以规则的间隔填充真实样本之间的间隙。

高基数、标签和写入侧排查

高基数和高流失率是 VictoriaMetrics 使用中最常见的风险之一。排查时要关注谁在制造大量新时间序列、哪些标签值过多、是否有标签顺序不稳定或标签数量过多的问题。

可以通过基数浏览器和 /api/v1/status/tsdb 端点确定导致高基数或高流失率的指标和标签。
如果将 -logNewSeries 命令行标志传递给 VictoriaMetrics，则可以记录新的时间序列。
📌 VictoriaMetrics 使用 -maxLabelsPerTimeseries 命令行标志限制每个指标的标签数量并删除多余的标签。这可以防止提取带有太多标签的指标。建议监控 vm_metrics_with_dropped_labels_total 指标，以确定是否必须根据您的工作负载调整 -maxLabelsPerTimeseries。
如果您将 Graphite 指标（例如 foo.bar.baz）存储在 VictoriaMetrics 中，则可以使用 {__graphite__="foo.*.baz"} 过滤器来选择此类指标。
VictoriaMetrics 在数据摄取期间忽略 NaN 值。

常见问题

VictoriaMetrics 变慢时，应该先调哪个参数？

不建议先调参数。先确认是否使用默认参数、日志里是否有明确报错、版本是否过旧、CPU/磁盘 IO/RAM/磁盘空间是否有余量。只有症状指向查询并发、标签顺序、高基数或图表间隙时，再针对性调整相关参数。

`vm_slow_*` 指标说明什么？

vm_slow_row_inserts_total、vm_slow_metric_name_loads_total 这类指标可以作为 RAM 容量不足的信号。如果活跃时间序列数量超出当前内存承载能力，写入和查询都会受到影响。

图表出现间隙一定是 VictoriaMetrics 丢数据了吗？

不一定。间隙可能和 rollup 缓存、数据源时间不同步、样本间隔不规则或从其他 TSDB 迁移后的查询语义有关。可以先按第 12、13 条建议排查。

总结

这 18 条建议可以分成五类：基础排查、资源余量、查询性能、写入和标签、数据损坏与兼容性。VictoriaMetrics 的排障关键不是记住所有参数，而是先判断问题属于哪一类，再用对应指标、日志、接口和参数缩小范围。对生产环境来说，提前监控 vm_free_disk_space_bytes、vm_data_size_bytes、vm_slow_* 和高基数相关信息，比故障后临时猜参数更可靠。