mcpField
V
victoriametrics-docs

victoriametrics-docs

github.com/victoriametricsクラウド・DevOps5948 回インストール2 週間前に更新
リポジトリ

victoriametrics-docs について

VictoriaMetrics製品を扱う開発者やエージェント向けのドキュメント検索スキルです。公開ドキュメントを完全一致で調べ、確認済み、未掲載、検索未完了を区別します。

主な機能

  1. 01フラグ・APIパス・クエリ語の検索
  2. 02文書化されたトピックで検索を限定
  3. 03節アンカー付きの根拠を表示
  4. 04未掲載と検索失敗を区別
  5. 05取得ページを6時間キャッシュ

活用シーン

  1. 01引用前にVictoriaMetricsのフラグを確認
  2. 02APIパスの文書化状況を確認
  3. 03LogsQLやMetricsQLの構文を検証
  4. 04未掲載または不確かな用語を調査

インストール

コマンドをコピーしてターミナルで実行します。

$npx skills add https://github.com/victoriametrics/skills --skill victoriametrics-docs

インストール後、Claude Code で/victoriametrics-docsを入力して読み込まれたか確認します。

同梱ファイルscripts/vmdocs.py

詳細

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 と一致しません。フラグやパスの場合は、類似する記載済み用語が最大 3 件、引用付きで続けて表示されます。最初に入力した用語で始まる長い用語が表示され、その後に綴りが近い用語が表示されます。

ページにルーティング用のプレフィックスやサブパス付きで記載されていても、パスは一致します。ページ上のパスが検索語より長い場合は、matched in 行にそのパスが表示されます。したがって、/api/v1/query 内で見つかった /query は、単独のエンドポイントではなく、そのパスとして扱われます。

言及箇所よりも定義が優先されます。たとえば、#common-flags のようなフラグのセクションや、#rate、#stats-pipe のように用語名を付けたセクションです。

終了コード 1 と NOT FOUND は、その用語がドキュメント内に存在しないことを意味します。 終了コード 2 は、topics に表示されないトピックを指定するなど、使用方法に誤りがあることを意味します。 終了コード 3 と UNKNOWN は、一部のページを取得できず、用語が存在しないと証明できないことを意味します。スクリプトには、取得に失敗したページが表示されます。

検索結果の読み方

検索結果は、セクションへのリンクと、一致する行およびその前後 1 行で構成されます。リンクを引用し、行を引用してください（長い行はここでは短縮されています）。

$ 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. 質問で製品が指定されている場合は、topics の製品セクションを使い、各用語について find を実行します。
  3. 検索結果に表示された行だけを根拠に回答し、それぞれの行の上にあるリンクを引用します。NOT FOUND と表示された用語は、回答に含めません。

スクリプトの動作

ドキュメントページの公開インデックスである https://docs.victoriametrics.com/llms.txt を読み込み、VictoriaLogs や VictoriaTraces のルートページなど、sitemap.xml にのみ記載されているページを追加します。それらのページを並行して読み込み、テキストに変換して、一行分の前後の文脈とともに一致した行を出力します。検索は90秒後に読み込みを停止し、到達できなかったページを UNKNOWN として報告するため、エージェントのシェルの制限時間内に必ず応答します。一致した箇所は、その上にある見出しアンカーから作成した該当セクションへのリンクの下に表示されます。最初の見出しより前のテキストにはアンカーがないため、一致した箇所にはページのURLそのものが付けられます。

取得したページは、ユーザーごとにシステムの一時ディレクトリに6時間キャッシュされるため、最初の検索は遅く、次回以降は速くなります。リポジトリやユーザーのプロジェクトには何も書き込みません。

標準ライブラリのみを使用します。インストールは不要です。

得意な用途

VictoriaMetrics、VictoriaLogs、VictoriaTraces、operator、vmanomaly、Helm チャート、VictoriaMetrics Cloud におけるフラグ、HTTP API パス、MetricsQL／LogsQL の構文要素に対応します。用語は完全一致で照合されるため、省略された名前や作られた名前は NOT FOUND のままとなり、実在する長い名前との一致によって確認されることはありません。

制限事項

  • 検索には docs.victoriametrics.com へのネットワークアクセスが必要です。
  • 公開ドキュメントに記載されている内容を報告します。ドキュメントに誤りや不備があれば、回答にも誤りや不備が生じます。
  • 最新リリースを説明している現在のドキュメントを検索します。古いインスタンスでは、検索で見つかったフラグが存在しない場合があります。
  • キャッシュされたページは、最大で6時間前の内容である場合があります。

コメント

Markdown 対応