Prometheus logo

Prometheus

ドキュメントダウンロードコミュニティサポート＆トレーニングブログ

Ctrl + K

GitHub Logo

エクスポジション フォーマット

メトリックは、シンプルなテキストベースのエクスポジション フォーマットを使用してPrometheusに公開できます。このフォーマットを実装したクライアントライブラリがいくつかあります。お好みの言語にクライアントライブラリがない場合は、ご自身で作成できます。

テキストベース形式

Prometheusバージョン2.0以降、Prometheusにメトリックを公開するすべてのプロセスはテキストベースのフォーマットを使用する必要があります。このセクションでは、このフォーマットに関する基本情報と、より詳細な説明を見つけることができます。

基本情報

側面説明
開始2014年4月
対応Prometheus バージョン >=0.4.0
伝送HTTP
エンコーディングUTF-8、\n改行コード
HTTP Content-Typetext/plain; version=0.0.4（version値が指定されていない場合、最新のテキスト形式バージョンにフォールバックします。）
オプションのHTTP Content-Encodinggzip
メリット
  • 人間が読める
  • 特に最小限のケースで組み立てが簡単（ネスト不要）
  • 行ごとに読み取り可能（型ヒントとドキュメント文字列を除く）
制限事項
  • 冗長
  • 型とドキュメント文字列が構文に不可欠な部分ではないため、メトリック契約の検証がほとんど存在しない
  • 解析コスト
サポートされているメトリックプリミティブ
  • カウンタ
  • ゲージ
  • ヒストグラム
  • サマリー
  • 型なし

テキスト形式の詳細

Prometheusのテキストベースの形式は行指向です。行は改行文字（\n）で区切られます。最終行は改行文字で終わる必要があります。空行は無視されます。

行形式

行内では、トークンは任意の数の空白やタブで区切ることができます（前のトークンと結合しないように、少なくとも1つで区切る必要があります）。先頭と末尾の空白は無視されます。

コメント、ヘルプテキスト、および型情報

最初の非空白文字が#の行はコメントです。#の後の最初のトークンがHELPまたはTYPEのいずれかでない限り、それらは無視されます。これらの行は次のように扱われます: トークンがHELPの場合、少なくとも1つのトークンがさらに期待され、それがメトリック名です。残りのすべてのトークンは、そのメトリック名のドキュメント文字列と見なされます。HELP行には、任意のUTF-8文字のシーケンス（メトリック名の後）を含めることができますが、バックスラッシュと改行文字はそれぞれ\\と\nとしてエスケープする必要があります。任意のメトリック名に対して、HELP行は1つだけ存在できます。

トークンがTYPEの場合、正確に2つのトークンがさらに期待されます。最初のトークンはメトリック名であり、2番目のトークンはcounter、gauge、histogram、summary、またはuntypedのいずれかであり、その名前のメトリックの型を定義します。指定されたメトリック名に対して、TYPE行は1つだけ存在できます。メトリック名のTYPE行は、そのメトリック名に対して最初のサンプルが報告される前に表示される必要があります。メトリック名にTYPE行がない場合、型はuntypedに設定されます。

残りの行は、以下の構文 (EBNF) を使用してサンプルを記述します (1行に1つのサンプル)。

metric_name [
  "{" label_name "=" `"` label_value `"` { "," label_name "=" `"` label_value `"` } [ "," ] "}"
] value [ timestamp ]

サンプル構文において

  • metric_nameとlabel_nameは、通常のPrometheus表現言語の制限を持ちます。
  • label_valueは任意のUTF-8文字のシーケンスですが、バックスラッシュ（\）、二重引用符（"）、および改行（\n）文字は、それぞれ\\、\"、および\nとしてエスケープする必要があります。
  • valueは、GoのParseFloat()関数で要求される形式の浮動小数点数です。標準の数値に加えて、NaN、+Inf、および-Infは、それぞれ非数、正の無限大、および負の無限大を表す有効な値です。
  • timestampはint64（エポックからのミリ秒、つまり1970-01-01 00:00:00 UTC（うるう秒を除く））で、GoのParseInt()関数で要求される形式で表されます。

グループ化とソート

特定のメトリックに関するすべての行は、オプションのHELPおよびTYPE行が最初に（特定の順序なしで）配置された単一のグループとして提供されなければなりません。それ以外は、繰り返し公開する際に再現可能なソートが望ましいですが、必須ではありません。つまり、計算コストが非常に高くなる場合はソートしないでください。

各行は、メトリック名とラベルの一意な組み合わせを持つ必要があります。そうでない場合、取り込み動作は未定義です。

ヒストグラムとサマリー

histogramとsummaryのタイプはテキスト形式で表現するのが難しいです。以下の規則が適用されます。

  • 名前がxのサマリーまたはヒストグラムのサンプル合計は、x_sumという別のサンプルとして与えられます。
  • 名前がxのサマリーまたはヒストグラムのサンプルカウントは、x_countという別のサンプルとして与えられます。
  • 名前がxのサマリーの各クォンタイルは、同じ名前xとラベル{quantile="y"}を持つ別のサンプル行として与えられます。
  • 名前がxのヒストグラムの各バケットカウントは、名前x_bucketとラベル{le="y"}（yはバケットの上限）を持つ別のサンプル行として与えられます。
  • ヒストグラムは、{le="+Inf"}を持つバケットを持たなければなりません。その値は、x_countの値と同じでなければなりません。
  • ヒストグラムのバケットとサマリーのクォンタイルは、それぞれのラベル値（leまたはquantileラベル）の数値順に昇順で表示されなければなりません。

テキスト形式の例

以下は、コメント、HELPおよびTYPE式、ヒストグラム、サマリー、文字エスケープの例などを含む、本格的なPrometheusメトリックのエクスポジションの例です。

# HELP http_requests_total The total number of HTTP requests.
# TYPE http_requests_total counter
http_requests_total{method="post",code="200"} 1027 1395066363000
http_requests_total{method="post",code="400"}    3 1395066363000

# Escaping in label values:
msdos_file_access_time_seconds{path="C:\\DIR\\FILE.TXT",error="Cannot find file:\n\"FILE.TXT\""} 1.458255915e9

# Minimalistic line:
metric_without_timestamp_and_labels 12.47

# A weird metric from before the epoch:
something_weird{problem="division by zero"} +Inf -3982045

# A histogram, which has a pretty complex representation in the text format:
# HELP http_request_duration_seconds A histogram of the request duration.
# TYPE http_request_duration_seconds histogram
http_request_duration_seconds_bucket{le="0.05"} 24054
http_request_duration_seconds_bucket{le="0.1"} 33444
http_request_duration_seconds_bucket{le="0.2"} 100392
http_request_duration_seconds_bucket{le="0.5"} 129389
http_request_duration_seconds_bucket{le="1"} 133988
http_request_duration_seconds_bucket{le="+Inf"} 144320
http_request_duration_seconds_sum 53423
http_request_duration_seconds_count 144320

# Finally a summary, which has a complex representation, too:
# HELP rpc_duration_seconds A summary of the RPC duration in seconds.
# TYPE rpc_duration_seconds summary
rpc_duration_seconds{quantile="0.01"} 3102
rpc_duration_seconds{quantile="0.05"} 3272
rpc_duration_seconds{quantile="0.5"} 4773
rpc_duration_seconds{quantile="0.9"} 9001
rpc_duration_seconds{quantile="0.99"} 76656
rpc_duration_seconds_sum 1.7560473e+07
rpc_duration_seconds_count 2693

OpenMetrics テキスト形式

OpenMetricsは、Prometheusのテキスト形式をベースにしたメトリックのワイヤフォーマットを標準化するための取り組みです。ターゲットのスクレイピングが可能であり、少なくともv2.23.0以降ではメトリックのフェデレーションにも利用できます。

エグゼンプラー（実験的）

OpenMetrics形式を利用することで、エグゼンプラーの公開とクエリが可能になります。エグゼンプラーは、集約されたMetricFamilyに関連するメトリックセットの時間スナップショットを提供します。さらに、トレースシステムと組み合わせて使用することで、特定のサービスに関連する詳細情報を提供できるTrace IDを付加できます。

この実験的機能を有効にするには、少なくともv2.26.0のバージョンが必要で、引数に--enable-feature=exemplar-storageを追加する必要があります。

Protobuf形式

以前のバージョンのPrometheusでは、現在のテキストベースの形式に加えて、Protocol Buffers（Protobufとも呼ばれる）に基づくエクスポジション形式をサポートしていました。Prometheus 2.0では、Protobuf形式は非推奨とされ、Prometheusはそのエクスポジション形式からのサンプルの取り込みを停止しました。

しかし、Prometheusに新しい実験的な機能が追加され、Protobuf形式が最も実現可能な選択肢と見なされました。これにより、Prometheusは再びProtocol Buffersを受け入れるようになりました。

PrometheusがProtobufのエクスポジション形式を優先するように設定される、有効にすると利用可能な実験的機能のリストを以下に示します。

機能フラグ導入されたバージョン
ネイティブヒストグラム2.40.0
created-timestamp-zero-ingestion2.50.0

過去のバージョン

以前のフォーマットバージョンの詳細については、レガシーなクライアントデータ公開フォーマットドキュメントを参照してください。

オリジナルのProtobuf形式の現在のバージョン（ネイティブヒストグラムの最近の拡張機能を含む）は、prometheus/client_model リポジトリで管理されています。

このページの内容