victoriametrics-docs

VictoriaMetrics 文档查询

在写出某个标志、API 路径或查询结构之前，请先根据已发布的文档确认。虚构的标志看起来和真实标志一模一样，读者不检查就无法分辨。

关键规则

• 先检查，再写出。不要先写出标志或端点，再去验证。
• NOT FOUND 是一种答案。报告该术语未在文档中记载。查询结果可能会列出与之相似的已记录术语。每个都是不同的术语：只有附上各自的引用，才能将其作为更正项写出；绝不要把它说成用户询问的术语。
• UNKNOWN 不是答案。有些页面或页面索引未能加载，因此该术语可能出现在其中。请先调查再回答：确认 docs.victoriametrics.com 可以访问，然后重新运行查询。如果只有部分页面加载失败，请直接打开这些页面；脚本会列出每个页面及其错误。绝不要报告该术语未在文档中记载。
• 带有主题的 NOT FOUND 只涵盖该部分。在称某个术语未在文档中记载前，请确认主题是否正确，或不指定主题重新运行查询。
• 引用查询输出的行，并引用其上方的链接。该链接包含章节锚点，会跳转到相关说法所在的章节。没有该链接的说法只是猜测。如果查询提供了带锚点的链接，切勿只引用页面 URL。
• 运行中实例的 /flags 不是可用标志列表。它只会返回操作员明确设置的标志，因此只能说明此实例的配置，不能说明其他内容。
• 如果某个技能已经包含 API 参考，则该技能对自身的端点拥有优先权。此处用于查询标志、这些技能未覆盖的产品，以及其参考文档未提及的内容。

用法

find 会在指向相应章节的链接下方，打印包含指定术语的行。topics 会列出可用于限定查询范围的章节。

# Which sections can a lookup be limited to?
python3 <skill_base_dir>/scripts/vmdocs.py topics

# Does this flag exist, and what does it do?
python3 <skill_base_dir>/scripts/vmdocs.py find "-retentionPeriod"

# Does this API path exist?
python3 <skill_base_dir>/scripts/vmdocs.py find "/select/logsql/hits"

# A LogsQL pipe, limited to the VictoriaLogs section
python3 <skill_base_dir>/scripts/vmdocs.py find "block_stats" "victorialogs"

主题必须是 topics 打印的名称，例如 victorialogs 或 operator。任何其他主题都会以状态码 2 退出并打印主题列表，因此切勿猜测主题名称。

以 - 或 / 开头的术语会被视为标志或 API 路径。查询判定为 NOT FOUND 前，会搜索该主题下的所有页面；若未指定主题，则会搜索整个网站的所有页面。

许多标志会出现在多个产品中。要查询其中一个，请将该产品的章节作为主题；否则，排在前面的 VictoriaMetrics 页面会填满输出：

python3 <skill_base_dir>/scripts/vmdocs.py find "-storageNode" "victorialogs"

术语必须完全匹配。-search.maxUnique 不会匹配 -search.maxUniqueTimeseries，因此截断或虚构的名称仍会显示为 NOT FOUND。标志和路径也区分大小写：-storagenode 不等于 -storageNode。对于标志或路径，结果最多会附上三个相似的已记录术语及其引用：先列出以输入内容开头的较长术语，再列出拼写相近的术语。

即使页面上打印的路径带有路由前缀或子路径，查询仍会匹配该路径。如果页面上的路径比查询的术语更长，结果会显示一行 matched in，因此，在 /api/v1/query 中找到的 /query 表示匹配到了该路径，而不是一个独立的端点。

定义优先于提及：标志可在 #common-flags 这类标志章节中定义，也可在以术语命名的章节中定义，例如 #rate 或 #stats-pipe。

退出代码为 1 且显示 NOT FOUND，表示该术语未出现在文档中。 退出代码为 2 表示用法错误，例如指定的主题未列在 topics 中。 退出代码为 3 且显示 UNKNOWN，表示部分页面无法获取，因此查询无法证明该术语不存在。脚本会列出加载失败的页面。

阅读输出

命中结果包含指向章节的链接，随后是匹配行及其前后各一行。引用该链接，并引用这些行（此处会截短较长的行）：

$ vmdocs.py find "-retentionPeriod" victorialogs
https://docs.victoriametrics.com/victorialogs/#common-flags
The maximum allowed disk usage percentage (1-100) for the filesystem that contains ...
-retentionPeriod value
Log entries with timestamps older than now-retentionPeriod are automatically deleted; ...

未命中结果会说明搜索范围，并列出任何相近的已记录术语。每个都是不同的术语：

$ vmdocs.py find "-retentionPeriods" victorialogs
NOT FOUND: -retentionPeriods is on none of the 39 pages of the victorialogs section.
Similar documented terms, each a different term:
-retentionPeriod https://docs.victoriametrics.com/victorialogs/#common-flags

失败结果会说明答案未知、应采取的操作，以及加载失败的页面和对应错误：

UNKNOWN: 15 of 15 pages could not be fetched, and the term may be on one of them.
Do not report the term as undocumented. Check that docs.victoriametrics.com is
reachable, then run the lookup again. If only some pages fail, open them directly.
https://docs.victoriametrics.com/victoriatraces/  (HTTP Error 503: Service Unavailable)

回答问题

该脚本匹配的是术语，而不是问题。请将问题拆解为相关术语：

1. 选出字面术语：标志、HTTP 路径、组件名称、LogsQL 或 MetricsQL 关键字。
2. 对每个术语运行 find；如果问题提到了某个产品，还要使用 topics 中该产品对应的部分。
3. 只根据查找结果打印的行作答，并引用每行上方的链接。若某个术语返回 NOT FOUND，则它不属于答案。

脚本的工作方式

脚本会读取 https://docs.victoriametrics.com/llms.txt（已发布的文档页面索引），并补充仅列在 sitemap.xml 中的页面，例如 VictoriaLogs 和 VictoriaTraces 的根页面。它会并行加载这些页面，将其转换为文本，并打印匹配行及一行上下文。查找会在 90 秒后停止加载，并将未能访问的页面报告为 UNKNOWN，因此始终能在 Agent 的 shell 时间限制内给出结果。每条命中内容都会显示在其所在章节的链接下方；该链接由匹配内容上方的标题锚点生成。第一个标题之前的文本没有锚点，因此对应的命中内容会附带不含锚点的页面 URL。

抓取的页面会按用户缓存到系统临时目录中，缓存时长为六小时，因此首次查找较慢，之后会很快。脚本不会向仓库或用户的项目中写入任何内容。

仅使用标准库。无需安装。

适用场景

适用于 VictoriaMetrics、VictoriaLogs、VictoriaTraces、operator、vmanomaly、Helm chart 和 VictoriaMetrics Cloud 中的标志、HTTP API 路径以及 MetricsQL/LogsQL 结构。术语必须完整匹配，因此截断或虚构的名称会返回 NOT FOUND，不会因更长的真实名称而被确认。

限制

• 查找需要访问 docs.victoriametrics.com 网络。
• 它只报告已发布文档中的内容。如果文档有误或不完整，答案也会如此。
• 它搜索的是当前文档，描述的是最新版本。较旧的实例可能没有查找结果中出现的标志。
• 缓存页面可能长达六小时未更新。