victoriametrics-docs

VictoriaMetrics documentation lookup

Confirm a flag, an API path or a query construct against the published documentation before naming it. An invented flag reads exactly like a real one, so a reader cannot tell the difference without checking.

Critical rules

• Check before you name. Do not write a flag or an endpoint and then verify it.
• NOT FOUND is an answer. Report that the term is undocumented. The lookup may list similar documented terms under it. Each one is a different term: name it as a correction only with its own citation, and never present it as the term the user asked about.
• UNKNOWN is not an answer. Some pages, or the page index, did not load, so the term may be on one of them. Investigate before you answer: check that docs.victoriametrics.com is reachable and run the lookup again. If only some pages fail, open those pages directly; the script lists each one with its error. Never report the term as undocumented.
• NOT FOUND with a topic covers only that section. Before you call a term undocumented, make sure the topic was right, or run the lookup again without one.
• Quote the lines the lookup printed, and cite the link above them. That link carries the section anchor, so it opens at the section the claim came from. A claim without it is a guess. Do not cite a bare page URL when the lookup gave you an anchored one.
• /flags on a running instance is not a list of available flags. It returns only the flags an operator set explicitly, so it answers how this instance is configured and nothing more.
• A skill that already carries an API reference wins for its own endpoints. Use this one for flags, for products those skills do not cover, and for anything their reference omits.

Usage

find prints the lines that contain a term, under a link to their section. topics lists the sections a lookup can be limited to.

# 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"

A topic must be a name that topics prints, such as victorialogs or operator. Any other topic exits 2 and prints the list, so never guess one.

A term starting with - or / is treated as a flag or an API path. Every page of the topic, or of the whole site without one, is searched before the lookup says NOT FOUND.

Many flags exist in more than one product. Pass the product's section as the topic to check one of them, or the VictoriaMetrics pages, which come first, fill the output:

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

Terms match whole. -search.maxUnique does not match -search.maxUniqueTimeseries, so a truncated or invented name stays NOT FOUND. Flags and paths also match case: -storagenode is not -storageNode. For a flag or a path, up to three similar documented terms follow, with citations: longer terms that start with the input first, then near spellings.

A path still matches when the page prints it with a routing prefix or a sub-path. When the path on the page is longer than the term, a matched in line shows it, so /query found inside /api/v1/query reads as that path and not as an endpoint of its own.

A definition comes before mentions: a flag in a flags section such as #common-flags, or a section named after the term, such as #rate or #stats-pipe.

Exit code 1 with NOT FOUND means the term does not appear in the documentation. Exit code 2 means a usage error, such as a topic that topics does not list. Exit code 3 with UNKNOWN means some pages could not be fetched, so the lookup cannot prove the term is absent. The script lists the pages that failed.

Reading the output

A hit is a link to the section, then the matching line with one line on each side. Cite the link, quote the lines (long lines shortened here):

$ 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; ...

A miss states what was searched, then any close documented terms. Each is a different term:

$ 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

A failure says the answer is unknown, what to do, and which pages failed with which error:

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)

To answer a question

The script matches terms, not questions. Turn the question into the terms it depends on:

1. Pick the literal terms: flags, HTTP paths, component names, LogsQL or MetricsQL keywords.
2. Run find for each term, with the product's section from topics when the question names a product.
3. Answer only from the lines the lookup printed, and cite the link above each one. A term that comes back NOT FOUND is not part of the answer.

What the script does

It reads https://docs.victoriametrics.com/llms.txt, the published index of documentation pages, and adds the pages that only sitemap.xml lists, such as the VictoriaLogs and VictoriaTraces root pages. It loads those pages in parallel, converts them to text and prints the matching lines with one line of context. A lookup stops loading after 90 seconds and reports the pages it did not reach as UNKNOWN, so it always answers inside an agent's shell time limit. Each hit is printed under the link to the section it came from, built from the heading anchor above the match. Text above the first heading has no anchor, so its hit carries the bare page URL.

Fetched pages are cached under the system temporary directory, per user, for six hours, so the first lookup is slow and later ones are fast. Nothing is written into the repository or the user's project.

Standard library only. No installation step.

What it is good for

Flags, HTTP API paths and MetricsQL/LogsQL constructs, across VictoriaMetrics, VictoriaLogs, VictoriaTraces, the operator, vmanomaly, the Helm charts and VictoriaMetrics Cloud. A term matches whole, so a truncated or invented name stays NOT FOUND and is not confirmed by a longer real one.

Limits

• The lookup needs network access to docs.victoriametrics.com.
• It reports what the published documentation says. Where the documentation is wrong or incomplete, so is the answer.
• It searches the current documentation, which describes the latest release. An older instance may not have a flag the lookup finds.
• A cached page can be up to six hours old.