メトリックは、シンプルなテキストベースのエクスポジション形式を使用してPrometheusに公開できます。クライアントライブラリは、この形式を実装しています。お使いの言語にクライアントライブラリがない場合は、独自に作成できます。
Prometheusバージョン2.0以降、Prometheusにメトリックを公開するすべてのプロセスは、テキストベースの形式を使用する必要があります。このセクションでは、この形式に関する基本情報と、形式のより詳細な説明を見つけることができます。
| 側面 | 説明 |
|---|---|
| 開始時期 | 2014年4月 |
| サポートされているバージョン | Prometheusバージョン>=0.4.0 |
| 送信方法 | HTTP |
| エンコーディング | UTF-8、\n改行 |
HTTP Content-Type |
text/plain; version=0.0.4（version値がない場合、最新のテキスト形式バージョンに戻ります。） |
オプションのHTTP Content-Encoding |
gzip |
| 利点 |
|
| 制限事項 |
|
| サポートされているメトリックプリミティブ |
|
Prometheusのテキストベース形式は、行指向です。行は改行文字（\n）で区切られています。最後の行は改行文字で終わる必要があります。空行は無視されます。
1行内では、トークンは任意の数の空白やタブで区切ることができます（前のトークンとマージされる場合は、少なくとも1つ区切りが必要です）。先頭と末尾の空白は無視されます。
最初の非空白文字が#である行はコメントです。最初のトークンがHELPまたはTYPEでない限り、無視されます。これらの行は次のように処理されます。トークンがHELPの場合、少なくともあと1つのトークン（メトリック名）が必要です。残りのトークンはすべて、そのメトリック名のdocstringとみなされます。HELP行には任意のUTF-8文字列を含めることができます（メトリック名以降）。ただし、バックスラッシュと改行文字は\\と\nとしてエスケープする必要があります。任意のメトリック名に対して、HELP行は1つだけ存在できます。
トークンがTYPEの場合、正確にあと2つのトークンが必要です。最初のトークンはメトリック名で、2番目のトークンはcounter、gauge、histogram、summary、またはuntypedのいずれかで、その名前のメトリックの型を定義します。任意のメトリック名に対して、TYPE行は1つだけ存在できます。メトリック名のTYPE行は、そのメトリック名の最初のサンプルが報告される前に表示する必要があります。メトリック名のTYPE行がない場合、型はuntypedに設定されます。
残りの行は、次の構文（EBNF）を使用してサンプル（行ごとに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年1月1日00:00:00 UTC、うるう秒を除く）で、GoのParseInt()関数で必要なように表現されます。特定のメトリックのすべての行は、オプションのHELP行とTYPE行を最初に（特定の順序はありません）1つのグループとして提供する必要があります。それ以外では、繰り返しエクスポジションでの再現可能なソートが優先されますが、必須ではありません。つまり、計算コストが高すぎる場合はソートしないでください。
各行には、メトリック名とラベルの一意の組み合わせが必要です。そうでない場合、取り込み動作は定義されていません。
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は、Prometheusテキスト形式に基づいて構築された、メトリックのワイヤフォーマットを標準化するための取り組みです。ターゲットをスクレイプすることも、少なくともv2.23.0以降はメトリックのフェデレーションにも使用できます。
OpenMetrics形式を使用すると、Exemplarsのエクスポジションとクエリが可能になります。Exemplarsは、要約されたMetricFamilyに対して、メトリックセットに関連付けられた時点のスナップショットを提供します。さらに、トレースIDを添付することもでき、トレースシステムと併用することで、特定のサービスに関連する詳細な情報を提供できます。
この実験的機能を有効にするには、少なくともバージョンv2.26.0が必要で、引数に--enable-feature=exemplar-storageを追加する必要があります。
以前のバージョンのPrometheusは、現在のテキストベース形式に加えて、Protocol Buffers（別名Protobuf）に基づいたエクスポジション形式をサポートしていました。Prometheus 2.0では、Protobuf形式は非推奨とされ、Prometheusはそのエクスポジション形式からのサンプルの取り込みを停止しました。
ただし、Protobuf形式が最も実現可能なオプションと見なされた実験的機能がPrometheusに追加されました。これにより、Prometheusは再びProtocol Buffersを受け入れるようになりました。
有効にすると、PrometheusがProtobufエクスポジション形式を優先するように構成される実験的機能のリストを以下に示します。
| 機能フラグ | 導入されたバージョン |
|---|---|
| native-histograms | 2.40.0 |
| created-timestamp-zero-ingestion | 2.50.0 |
過去の形式バージョンの詳細については、レガシーのクライアントデータエクスポジション形式ドキュメントを参照してください。
元のProtobuf形式の現在のバージョン（ネイティブヒストグラムの最新の拡張機能を含む）は、prometheus/client_modelリポジトリで保守されています。
このドキュメントはオープンソースです。問題点の報告やプルリクエストによって、改善にご協力ください。