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つの追加トークンが期待されます。1つ目はメトリック名、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は、GoのParseInt()関数で必要とされる形式のint64（エポックからのミリ秒、つまり1970-01-01 00:00:00 UTC、うるう秒を除く）です。

グループ化とソート

指定されたメトリックのすべての行は、オプションのHELPおよびTYPE行を先頭（順不同）にして、1つの単一グループとして提供する必要があります。それ以外の場合は、再現可能なソートが推奨されますが必須ではありません。つまり、計算コストが prohibitive な場合はソートしないでください。

各行には、メトリック名とラベルのユニークな組み合わせが必要です。それ以外の場合、取り込み動作は未定義です。

ヒストグラムとサマリー

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以降、メトリックのフェデレーションにも利用できます。

Exemplars（実験的）

OpenMetricsフォーマットを利用することで、Exemplarsの公開とクエリが可能になります。Exemplarsは、サマリーされたMetricFamilyとは対照的に、メトリックセットに関連する時点のスナップショットを提供します。さらに、Exemplarsには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公開フォーマットを優先するように設定される実験的機能のリストです。

フィーチャーフラグ導入されたバージョン
native-histograms2.40.0
created-timestamp-zero-ingestion2.50.0

過去のバージョン

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

ネイティブヒストグラムの最新拡張機能を含む、元のProtobufフォーマットの現在のバージョンは、prometheus/client_modelリポジトリで管理されています。

このページの内容