promql-cli

promql-cli — Prometheus クエリ CLI スキル

promql-cli (github.com/nalbury/promql-cli) は、Prometheus メトリクスのクエリ、分析、可視化と、PromQL の基礎知識を扱う Go 製 CLI です。

リファレンスファイル

タスクを実行する前に、関連するリファレンスファイルを読んでください。

ファイル	読むタイミング
references/installation.md	ユーザーが promql-cli のインストールや設定（ホスト、認証、トークン、パスワード、複数ホスト）を必要としている場合
references/usage.md	ユーザーがメトリクス、エクスポーター、ラベルを調べたり、クエリを実行したり、出力形式を選択したりする場合
references/graphing.md	ユーザーが Prometheus データをターミナル内の ASCII チャートで可視化したい場合
references/debugging.md	ユーザーがパフォーマンスの問題、レイテンシ、エラー、飽和、データの欠落、クエリコストの問題を調査する場合
references/promql-reference.md	ユーザーが PromQL の記述、メトリクスの種類、関数、集計についてサポートを必要としている場合

ほとんどのタスクでは、references/usage.md を読んでください。PromQL のサポートが必要な場合は、references/promql-reference.md を読んでください。デバッグする場合は、references/debugging.md と references/promql-reference.md の両方を読んでください。

セットアップの確認

クエリを実行する前に、ホストが設定されていることを確認してください。

promql 'up'   # succeeds if host is reachable; fails with connection error if not configured
# or
promql --host xxx 'up'

次のエラーは設定／認証の問題として認識し、references/installation.md を参照してください。

エラー	原因
dial tcp ... connection refused	設定されたアドレスでホストが稼働していません
dial tcp ... no such host	ホスト名を解決できません — 設定のホストが間違っています
error querying prometheus: ...401...	Bearer トークンがないか、無効です
error querying prometheus: ...403...	トークンは有効ですが、権限が不足しています
please specify an authentication type	認証フラグが一部しか設定されていません — 代わりに設定ファイルを使用してください

これらのエラーが表示された場合、ユーザーに代わって設定ファイルを作成しないでください — 設定ファイルには認証情報（トークン、パスワード）が含まれる可能性があり、LLM を経由させてはなりません。代わりに、ユーザー自身で設定するよう案内してください。

"Prometheus ホスト（必要に応じて認証情報も）を記載した ~/.promql-cli.yaml を手動で作成してください。正確な形式は references/installation.md を参照してください。準備ができたらお知らせください。"

ユーザーが設定ファイルの準備完了を確認した後にのみ、クエリを実行してください。

クイックコマンドリファレンス

promql 'up'                                          # instant query
promql 'rate(http_requests_total[5m])' --start 1h    # range query (ASCII graph)
promql 'up' --output csv                             # CSV output
promql 'up' --output json                            # JSON output
promql metrics                                       # list all metric names
promql labels <metric>                               # list labels for a metric
promql meta <metric>                                 # show metric type and help
promql --config ~/.promql-cli-prod.yaml 'up'         # target a specific host

重要な原則

1. カウンターには必ず rate() を使い、生の値は使わないでください — 生のカウンターは増加し続けるだけなので、絶対値に意味はありません。rate() は 1 秒あたりの変化率を返します。実際に知りたいのはこの値です。
2. デバッグ時は、単一のインスタンスに絞り込んでください — レプリカ全体で集計すると、インスタンスごとの異常が隠れてしまいます。健全なピアの背後に隠れた過負荷の Pod は、平均値には現れません。
3. 最も内側のセレクターでラベルマッチャーを使い、早い段階でフィルターしてください — Prometheus は関数より先にセレクターを評価するため、フィルターが遅いとすべての時系列をスキャンすることになります。早期にフィルターすれば、スキャンするデータ量とクエリのレイテンシを削減できます。
4. ヒストグラムでは、histogram_quantile() の前に by 句で le を保持してください — この関数はパーセンタイルを補間するためにすべての le バケットを必要とします。早い段階で le を削除すると、NaN または誤った結果が生じます。
5. 範囲クエリでは --output graph を優先してください — ASCII スパークラインは傾向（上昇、下降、急増）をコンパクトな形式で表現し、LLM が適切に解析できます。生のタイムスタンプテーブルは、頭の中でのモデル化が必要です。数千行の生の JSON／CSV を LLM のコンテキストに送らないでください — 代わりに --output graph を使うか、まず --output graph を実行し、狭い範囲を調べる場合に限って --output table を使ってください。
6. 認証情報は ~/.promql-cli.yaml と ~/.promql_token に保存し、chmod 600 を設定してください — CLI 引数としてトークンを渡すと、シェルの履歴やプロセス一覧に表示されます。

クエリコストのルール

クエリセッションの前と最中には、必ず次のルールを適用してください。

0. 必ず promql CLI を使用してください — Python スクリプトやシェルの curl から Prometheus HTTP API を呼び出さないでください。CLI は認証、フォーマット、出力を一貫して処理します。Python から API を呼び出すと、これらすべてを迂回し、解析が必要な生の JSON が出力されるため、コンテキストが肥大化し、モデルが最も適切に解釈できるグラフ出力が見えにくくなります。
1. まずカーディナリティを確認してください — 見慣れないメトリクスをクエリする前に、その時系列数を数えてください（count(metric_name)）。ラベルフィルターのない高カーディナリティのメトリクスは、タイムアウトしたり、出力が大量になったりします。パターンについては references/debugging.md を参照してください。
2. 最初に時間範囲を確認してください — 範囲クエリを実行する前に、必ず確認してください。長い期間はコストがかかるため、1 回の長いクエリよりも、短い間隔で複数回クエリすることを優先してください。
3. 過去か最近かを明確にしてください — 新たな調査では、特定のタイムスタンプの過去のイベントを確認したいのか、最近の傾向を確認したいのかを尋ねてください。最近の傾向であれば、過去 1 時間、過去 1 日、過去 1 週間、過去 1 か月といった具体的な選択肢を提示してください。
4. Prometheus で集計してください — 集計のために生の時系列を Python やシェルに取り込まないでください。sum by(...)、avg by(...)、topk() を PromQL 式に含め、Prometheus 側で時系列を集約してください。
5. タイムアウトしたら、クエリの範囲が広すぎます — クエリに 15 秒を超える場合は、ラベルフィルターを追加する、--start を短くする、集約ラッパーを追加するといった方法で範囲を絞ってください。セッション内の後続のクエリにも、同じように絞った範囲を適用してください。
6. データが欠落している場合は up を確認してください — メトリクスにデータがない場合、アプリケーションを診断する前に up{job="...", instance="..."} を実行してください。値が 0 であれば、エクスポーターが停止していたことを確認できます。詳細は references/debugging.md を参照してください。

このスキルは網羅的なものではありません。最新情報については、公式 promql-cli ドキュメントとサンプルを参照してください。Context7 は情報を見つけやすくするプラットフォームとして役立ちます。

promql-cli 自体にバグや予期しない動作が見つかった場合は、https://github.com/nalbury/promql-cli/issues で Issue を作成してください。