VictoriaMetrics导入与查询时的时间单位及step处理疑问

问题描述 #

我是Docker部署VictoriaMetrics的初学者，按官方文档操作时遇到异常：只能用mil-sec（毫秒）单位写入数据，查询时却只能用second（秒）单位。用秒单位写入的数据，不管用哪种时间单位查询都查不到。为什么导入和查询要用不同时间单位？是不是我在step参数上有遗漏？

以下是测试命令：

// try 1: 用毫秒写入
// 写入命令
curl -d '{"metric":{"__name__":"zoo2","job":"node_exporter"},"values":[0,1,2],"timestamps":[1686207845001,1686207846002,1686207848003]}' -X POST 'http://localhost:8428/api/v1/import'

// 查询失败（毫秒时间范围）
curl "http://localhost:8428/api/v1/query_range?query=zoo2&start=1686207845000&end=1686207850000&step=1"
// 查询成功（秒时间范围）
curl "http://localhost:8428/api/v1/query_range?query=zoo2&start=1686207845&end=1686207850&step=1"


// try 2: 用秒写入
curl -d '{"metric":{"__name__":"zoo3","job":"node_exporter"},"values":[0,1,2],"timestamps":[1686207845,1686207846,1686207848]}' -X POST 'http://localhost:8428/api/v1/import'

// 查询失败（毫秒时间范围）
curl "http://localhost:8428/api/v1/query_range?query=zoo3&start=1686207845000&end=1686207850000&step=1"
// 查询也失败（秒时间范围）
curl "http://localhost:8428/api/v1/query_range?query=zoo3&start=1686207845&end=1686207850&step=1"

原因分析与解决办法 #

1. 写入接口的时间单位规范 #

VictoriaMetrics的/api/v1/import接口强制要求时间戳为毫秒级（13位数字）。你用秒级（10位）时间戳写入的zoo3数据，会被解析成1970年左右的极早时间（因为1686207845毫秒仅对应约1.95天），自然在当前时间范围内查不到。

2. 查询接口的时间单位逻辑 #

查询接口/api/v1/query_range的start和end参数支持两种时间戳格式：

• 10位数字：识别为秒级时间戳
• 13位数字：识别为毫秒级时间戳

你用毫秒时间范围查询zoo2失败，核心问题在step参数：默认情况下step的单位是秒，当你用毫秒级时间范围（5000毫秒=5秒）+step=1（1秒）时，采样点是1686207845000、1686207846000等整秒时刻，而你的数据点是1686207845001、1686207846002等非整秒时刻，默认的采样逻辑（如取最近点）可能因时间差太小未匹配到。只需给step指定毫秒单位即可查询成功：

curl "http://localhost:8428/api/v1/query_range?query=zoo2&start=1686207845000&end=1686207850000&step=1ms"

3. 标准化操作建议 #

• 写入必用毫秒时间戳：所有通过/api/v1/import写入的数据，时间戳必须是13位毫秒数，避免数据写入错误时间区间。
• 查询统一时间单位：要么全程用秒级时间戳+秒级step，要么全程用毫秒级时间戳+毫秒级step，减少匹配误差。
• 验证数据写入状态：用/api/v1/series接口确认数据的时间范围，排查是否写入正确区间：

  curl "http://localhost:8428/api/v1/series?match[]=zoo2"
  

内容的提问来源于stack exchange，提问作者Xavier Z