promtool

Prometheus監視システム用のツール。

フラグ

フラグ	説明
-h, --help	状況に応じたヘルプを表示します（--help-long と --help-man も試してください）。
--version	アプリケーションのバージョンを表示します。
--experimental	実験的コマンドを有効にします。
--enable-feature ...	有効にする機能名をカンマ区切りで指定します。有効なオプション：promql-experimental-functions, promql-delayed-name-removal。詳細は https://prometheus.dokyumento.jp/docs/prometheus/latest/feature_flags/ を参照してください。

コマンド

コマンド	説明
help	ヘルプを表示します。
check	リソースの有効性をチェックします。
query	Prometheusサーバーに対してクエリを実行します。
debug	デバッグ情報を取得します。
push	Prometheusサーバーにプッシュします。
test	単体テスト。
tsdb	tsdbコマンドを実行します。
promql	PromQLのフォーマットと編集。--experimentalフラグが必要です。

promtool help

ヘルプを表示します。

引数

引数	説明
command	コマンドのヘルプを表示します。

promtool check

リソースの有効性をチェックします。

フラグ

フラグ	説明	デフォルト
--query.lookback-delta	サーバーの最大クエリ参照期間。	5分
--extended	メトリックのカーディナリティに関連する拡張情報を表示します。

promtool check service-discovery

指定されたジョブ名に対してサービスディスカバリを実行し、リラベルを含む結果をレポートします。

フラグ

フラグ	説明	デフォルト
--timeout	ディスカバリ結果を待機する時間。	30秒

引数

引数	説明	必須
config-file	Prometheus設定ファイル。	はい
job	サービスディスカバリを実行するジョブ。	はい

promtool check config

設定ファイルが有効かどうかをチェックします。

フラグ

フラグ	説明	デフォルト
--syntax-only	設定ファイル構文のみをチェックし、設定で参照されているファイルとコンテンツの検証は無視します。
--lint	設定で指定されたルール/スクレイプ設定に適用するリンティングチェック。利用可能なオプション：all, duplicate-rules, none, too-long-scrape-interval。リンティングを無効にするには --lint=none を使用します。	duplicate-rules
--lint-fatal	リンティングエラーを終了コード3で終了させます。	false
--ignore-unknown-fields	設定ファイルで読み込まれたルールグループ内の不明なフィールドを無視します。これは、カスタムメタデータでルールファイルを拡張したい場合に便利です。Prometheusサーバーはデフォルトで厳密なチェックを実行するため、それらをPrometheusサーバーにロードする前に、これらのフィールドが削除されていることを確認してください。	false
--agent	AgentモードのPrometheusの設定ファイルをチェックします。

引数

引数	説明	必須
config-files	チェックする設定ファイル。	はい

promtool check web-config

ウェブ設定ファイルが有効かどうかをチェックします。

引数

引数	説明	必須
web-config-files	チェックする設定ファイル。	はい

promtool check healthy

Prometheusサーバーが正常であるかどうかをチェックします。

フラグ

フラグ	説明	デフォルト
--http.config.file	promtoolがPrometheusに接続するためのHTTPクライアント設定ファイル。
--url	PrometheusサーバーのURL。	https://:9090

promtool check ready

Prometheusサーバーが準備完了であるかどうかをチェックします。

フラグ

フラグ	説明	デフォルト
--http.config.file	promtoolがPrometheusに接続するためのHTTPクライアント設定ファイル。
--url	PrometheusサーバーのURL。	https://:9090

promtool check rules

ルールファイルが有効かどうかをチェックします。

フラグ

フラグ	説明	デフォルト
--lint	適用するリンティングチェック。利用可能なオプション：all, duplicate-rules, none。リンティングを無効にするには --lint=none を使用します。	duplicate-rules
--lint-fatal	リンティングエラーを終了コード3で終了させます。	false
--ignore-unknown-fields	ルールファイル内の不明なフィールドを無視します。これは、カスタムメタデータでルールファイルを拡張したい場合に便利です。Prometheusサーバーはデフォルトで厳密なチェックを実行するため、それらをPrometheusサーバーにロードする前に、これらのフィールドが削除されていることを確認してください。	false

引数

引数	説明
rule-files	チェックするルールファイル。デフォルトは標準入力から読み込まれます。

promtool check metrics

標準入力からPrometheusメトリックを渡し、一貫性と正確性をリンティングします。

例

$ cat metrics.prom | promtool check metrics

$ curl -s https://:9090/metrics | promtool check metrics

promtool query

Prometheusサーバーに対してクエリを実行します。

フラグ

フラグ	説明	デフォルト
-o, --format	クエリの出力形式。	promql
--http.config.file	promtoolがPrometheusに接続するためのHTTPクライアント設定ファイル。

promtool query instant

即時クエリを実行します。

フラグ

フラグ	説明
--time	クエリ評価時刻（RFC3339またはUnixタイムスタンプ）。

引数

引数	説明	必須
server	クエリ対象のPrometheusサーバー。	はい
式	PromQLクエリ式。	はい

promtool query range

範囲クエリを実行します。

フラグ

フラグ	説明
--header	サーバーに送信する追加ヘッダー。
--start	クエリ範囲の開始時刻（RFC3339またはUnixタイムスタンプ）。
--end	クエリ範囲の終了時刻（RFC3339またはUnixタイムスタンプ）。
--step	クエリのステップサイズ（期間）。

引数

引数	説明	必須
server	クエリ対象のPrometheusサーバー。	はい
式	PromQLクエリ式。	はい

promtool query series

時系列クエリを実行します。

フラグ

フラグ	説明
--match ...	時系列セレクター。複数回指定できます。
--start	開始時刻（RFC3339またはUnixタイムスタンプ）。
--end	終了時刻（RFC3339またはUnixタイムスタンプ）。

引数

引数	説明	必須
server	クエリ対象のPrometheusサーバー。	はい

promtool query labels

ラベルクエリを実行します。

フラグ

フラグ	説明
--start	開始時刻（RFC3339またはUnixタイムスタンプ）。
--end	終了時刻（RFC3339またはUnixタイムスタンプ）。
--match ...	時系列セレクター。複数回指定できます。

引数

引数	説明	必須
server	クエリ対象のPrometheusサーバー。	はい
name	ラベル値を提供するラベル名。	はい

promtool query analyze

特定のメトリックの使用パターンを分析するためにPrometheusに対してクエリを実行します。

フラグ

フラグ	説明	デフォルト
--server	クエリ対象のPrometheusサーバー。
--type	メトリックのタイプ：histogram。
--duration	分析する期間。	1時間
--time	クエリ時刻（RFC3339またはUnixタイムスタンプ）。デフォルトは現在時刻。
--match ...	時系列セレクター。複数回指定できます。

promtool debug

デバッグ情報を取得します。

promtool debug pprof

プロファイリングデバッグ情報を取得します。

引数

引数	説明	必須
server	pprofファイルを取得するPrometheusサーバー。	はい

promtool debug metrics

メトリックデバッグ情報を取得します。

引数

引数	説明	必須
server	メトリックを取得するPrometheusサーバー。	はい

promtool debug all

すべてのデバッグ情報を取得します。

引数

引数	説明	必須
server	すべてのデバッグ情報を取得するPrometheusサーバー。	はい

promtool push

Prometheusサーバーにプッシュします。

フラグ

フラグ	説明
--http.config.file	promtoolがPrometheusに接続するためのHTTPクライアント設定ファイル。

promtool push metrics

Prometheusリモート書き込みにメトリックをプッシュします（テスト目的のみ）。

フラグ

フラグ	説明	デフォルト
--label	メトリックに添付するラベル。複数回指定できます。	job=promtool
--timeout	メトリックをプッシュするのを待機する時間。	30秒
--header	Prometheusリモート書き込みヘッダー。

引数

引数	説明	必須
remote-write-url	メトリックをプッシュするPrometheusリモート書き込みURL。	はい
metric-files	プッシュするメトリックファイル。デフォルトは標準入力から読み込まれます。

promtool test

単体テスト。

フラグ

フラグ	説明
--junit	JUnit XMLテスト結果を保存するファイルパス。

promtool test rules

ルールに対する単体テスト。

フラグ

フラグ	説明	デフォルト
--run ...	設定されている場合、名が正規表現に一致するテストグループのみを実行します。複数回指定できます。
--debug	単体テストのデバッグを有効にします。	false
--diff	[実験的] 予想される出力と受信した出力の間に色の付いた差分を出力します。	false
--ignore-unknown-fields	テストファイル内の不明なフィールドを無視します。これは、カスタムメタデータでルールファイルを拡張したい場合に便利です。Prometheusサーバーはデフォルトで厳密なチェックを実行するため、それらのフィールドをPrometheusサーバーにロードする前に削除してください。	false

引数

引数	説明	必須
test-rule-file	単体テストファイル。	はい

promtool tsdb

tsdbコマンドを実行します。

promtool tsdb bench

ベンチマークを実行します。

promtool tsdb bench write

書き込みパフォーマンスベンチマークを実行します。

フラグ

フラグ	説明	デフォルト
--out	出力パスを設定します。	benchout
--metrics	読み込むメトリックの数。	10000
--scrapes	シミュレートするスクレイプの数。	3000

引数

引数	説明	デフォルト
ファイル	サンプルデータを含む入力ファイル。デフォルトは (../../tsdb/testdata/20kseries.json) です。	../../tsdb/testdata/20kseries.json

promtool tsdb analyze

チャーン、ラベルペアのカーディナリティ、および圧縮効率を分析します。

フラグ

フラグ	説明	デフォルト
--limit	各リストに表示する項目数。	20
--extended	拡張分析を実行します。
--match	分析するシリーズセレクタ。現在、1つのマッチャーセットのみがサポートされています。

引数

引数	説明	デフォルト
dbパス	データベースパス (デフォルトは data/) です。	data/
ブロックID	分析するブロック (デフォルトは最後のブロック) です。

promtool tsdb list

tsdbブロックをリスト表示します。

フラグ

フラグ	説明
-r, --human-readable	人間が読める形式で値を出力します。

引数

引数	説明	デフォルト
dbパス	データベースパス (デフォルトは data/) です。	data/

promtool tsdb dump

TSDBからサンプルをダンプします。

フラグ

フラグ	説明	デフォルト
--sandbox-dir-root	サンドボックスディレクトリが作成されるルートディレクトリ。このサンドボックスは、WALリプレイがチャンクを生成する場合に使用されます (デフォルトはデータベースパス)。サンドボックスは終了時にクリーンアップされます。
--min-time	ダンプする最小タイムスタンプ (Unixエポックからのミリ秒単位)。	-9223372036854775808
--max-time	ダンプする最大タイムスタンプ (Unixエポックからのミリ秒単位)。	9223372036854775807
--match ...	時系列セレクター。複数回指定できます。	{__name__=~'(?s:.*)'}

引数

引数	説明	デフォルト
dbパス	データベースパス (デフォルトは data/) です。	data/

promtool tsdb dump-openmetrics

[実験的] TSDBからOpenMetricsテキスト形式にサンプルをダンプします。ネイティブヒストグラムと古さのマーカーはOpenMetricsでは表現できないため、除外されます。

フラグ

フラグ	説明	デフォルト
--sandbox-dir-root	サンドボックスディレクトリが作成されるルートディレクトリ。このサンドボックスは、WALリプレイがチャンクを生成する場合に使用されます (デフォルトはデータベースパス)。サンドボックスは終了時にクリーンアップされます。
--min-time	ダンプする最小タイムスタンプ (Unixエポックからのミリ秒単位)。	-9223372036854775808
--max-time	ダンプする最大タイムスタンプ (Unixエポックからのミリ秒単位)。	9223372036854775807
--match ...	時系列セレクター。複数回指定できます。	{__name__=~'(?s:.*)'}

引数

引数	説明	デフォルト
dbパス	データベースパス (デフォルトは data/) です。	data/

promtool tsdb create-blocks-from

[実験的] 入力からサンプルをインポートし、TSDBブロックを生成します。詳細については、ストレージドキュメントを参照してください。

フラグ

フラグ	説明
-r, --human-readable	人間が読める形式で値を出力します。
-q, --quiet	作成されたブロックを表示しません。

promtool tsdb create-blocks-from openmetrics

OpenMetrics入力からサンプルをインポートし、TSDBブロックを生成します。詳細については、ストレージドキュメントを参照してください。

フラグ

フラグ	説明
--label	メトリックに添付するラベル。複数回指定できます。例: --label=label_name=label_value

引数

引数	説明	デフォルト	必須
入力ファイル	サンプルを読み込むOpenMetricsファイル。		はい
出力ディレクトリ	生成されたブロックの出力ディレクトリ。	data/

promtool tsdb create-blocks-from rules

新しい記録ルール用のデータブロックを作成します。

フラグ

フラグ	説明	デフォルト
--http.config.file	promtoolがPrometheusに接続するためのHTTPクライアント設定ファイル。
--url	ルールがバックフィルされるデータのPrometheus APIのURL。	https://:9090
--start	新しいルールのバックフィルを開始する時刻。RFC3339形式の日付またはUnixタイムスタンプである必要があります。必須です。
--end	終了時刻が指定されている場合、提供されたルールファイル内のすべての記録ルールは終了時刻までバックフィルされます。デフォルトでは、3時間前までバックフィルされます。RFC3339形式の日付またはUnixタイムスタンプである必要があります。
--output-dir	生成されたブロックの出力ディレクトリ。	data/
--eval-interval	記録ルールファイルに値が設定されていない場合、バックフィル時にルールを評価する頻度。	60s

引数

引数	説明	必須
rule-files	バックフィルされる記録ルールを含む1つ以上のファイルのリスト。ファイルにリストされているすべての記録ルールがバックフィルされます。アラートルールは評価されません。	はい

promtool promql

PromQLの書式設定と編集。--experimentalフラグが必要です。

promtool promql format

PromQLクエリをきれいに整形します。

引数

引数	説明	必須
query	PromQLクエリ。	はい

promtool promql label-matchers

既存のPromQLクエリに含まれるラベルマッチャーを編集します。

promtool promql label-matchers set

クエリにラベルマッチャーを設定します。

フラグ

フラグ	説明	デフォルト
-t, --type	設定するラベルマッチャーのタイプ。	=

引数

引数	説明	必須
query	PromQLクエリ。	はい
name	設定するラベルマッチャーの名前。	はい
値	設定するラベルマッチャーの値。	はい

promtool promql label-matchers delete

クエリからラベルを削除します。

引数

引数	説明	必須
query	PromQLクエリ。	はい
name	削除するラベルの名前。	はい