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	サーバーの最大クエリルックバック期間。	5m
--extended	メトリックのカーディナリティに関連する拡張情報を表示します。

promtool check service-discovery

指定されたジョブ名のサービスディスカバリを実行し、リレーリングを含む結果を報告します。

フラグ

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

引数

引数	説明	必須
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サーバーはデフォルトで厳密なチェックを行うため、ロードする前にこれらのフィールドを削除するようにしてください。	false
--agent	エージェントモードでのPrometheusの設定ファイルをチェックします。

引数

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

promtool check web-config

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

引数

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

promtool check healthy

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

フラグ

フラグ	説明	デフォルト
--http.config.file	HTTPクライアント設定ファイル。詳細はhttps://prometheus.dokyumento.jp/docs/prometheus/latest/configuration/promtoolで確認してください。
--url	PrometheusサーバーのURL。	https://:9090

promtool check ready

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

フラグ

フラグ	説明	デフォルト
--http.config.file	HTTPクライアント設定ファイル。詳細はhttps://prometheus.dokyumento.jp/docs/prometheus/latest/configuration/promtoolで確認してください。
--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サーバーはデフォルトで厳密なチェックを行うため、ロードする前にこれらのフィールドを削除するようにしてください。	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	HTTPクライアント設定ファイル。詳細はhttps://prometheus.dokyumento.jp/docs/prometheus/latest/configuration/promtoolで確認してください。

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	メトリックのタイプ：ヒストグラム。
--duration	分析する期間。	1h
--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	HTTPクライアント設定ファイル。詳細はhttps://prometheus.dokyumento.jp/docs/prometheus/latest/configuration/promtoolで確認してください。

promtool push metrics

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

フラグ

フラグ	説明	デフォルト
--label	メトリックにアタッチするラベル。複数回指定できます。	job=promtool
--timeout	メトリックをプッシュするまでの待機時間。	30s
--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サーバーはデフォルトで厳密なチェックを行うため、ロードする前にこれらのフィールドを削除するようにしてください。	false

引数

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

promtool tsdb

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

promtool tsdb bench

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

promtool tsdb bench write

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

フラグ

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

引数

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

promtool tsdb analyze

チャーン、ラベルペアのカーディナリティ、コンパクション効率を分析します。

フラグ

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

引数

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

promtool tsdb list

tsdbブロックを一覧表示します。

フラグ

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

引数

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

promtool tsdb dump

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

フラグ

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

引数

引数	説明	デフォルト
db path	データベースパス (デフォルトは 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 path	データベースパス (デフォルトは 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

引数

引数	説明	デフォルト	必須
input file	サンプルを読み取るOpenMetricsファイル。		はい
output directory	生成されるブロックの出力ディレクトリ。	data/

promtool tsdb create-blocks-from rules

新しいレコーディングルールのためのデータブロックを作成します。

フラグ

フラグ	説明	デフォルト
--http.config.file	HTTPクライアント設定ファイル。詳細はhttps://prometheus.dokyumento.jp/docs/prometheus/latest/configuration/promtoolで確認してください。
--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	設定するラベルマッチャーの名前。	はい
value	設定するラベルマッチャーの値。	はい

promtool promql label-matchers delete

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

引数

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