出力フォーマット - Prometheusドキュメント

Prometheus

このページはPrometheus公式ドキュメント和訳+αの一部です。

EXPOSITION FORMATS

メトリクスは、単純なテキストベースの出力フォーマットを利用してPrometheusに出力することができる。 このフォーマットを実装した様々なクライアントライブラリがある。 好みの言語にクライアントライブラリがなければ、自分で実装することができる。

注意：古いバージョンのPrometheusには、現在のテキストベースのフォーマットに加えて、Protocol Buffers（Protobuf）をベースにした出力フォーマットをサポートしているバージョンもあるが、 バージョン2.0からは、PrometheusはProtobufベースのフォーマットをサポートしない。 この変更の背後にある理由については、このドキュメントで読むことができる。

Text-based format

Prometheusバージョン2.0から、Prometheusにメトリクスを出力する全てのプロセスは、テキストベースのフォーマットを利用しなければならない。 ここでは、フォーマットの詳細に加えて、このフォーマットの基本情報を示す。

基本情報

  • Inception: April 2014
  • Supported in: Prometheus version >=0.4.0
  • Transmission: HTTP
  • Encoding: UTF-8, \n line endings
  • HTTP Content-Type: text/plain; version=0.0.4 (A missing version value will lead to a fall-back to the most recent text format version.)
  • Optional HTTP Content-Encoding: gzip
  • Advantages:
    • Human-readable
    • Easy to assemble, especially for minimalistic cases (no nesting required)
    • Readable line by line (with the exception of type hints and docstrings)
  • Limitations:
    • Verbose
    • Types and docstrings not integral part of the syntax, meaning little-to-nonexistent metric contract validation
    • Parsing cost
  • Supported metric primitives
    • Counter
    • Gauge
    • Histogram
    • Summary
    • Untyped

テキストフォーマット詳細

Prometheusのテキストベースフォーマットは、行指向である。 行は、line feed文字（\n）で分割される。 最後の行は、line feed文字で終わらなければならない。 空行は無視される。

行のフォーマット

行の中で、トークンは、任意の数の空白やタブで分割することができる（最低1つ以上、さもなければ直前のトークンにまとめられる）。 最初や最後のホワイトスペースは無視される。

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

最初のホワイトスペース以外の文字が#の行は、コメントである。 それらは、#の直後のトークンが、HELPやTYPEでなければ、無視される。 そうである行は、次のように処理される。 そのトークンがHELPなら、少なくとももう1つのトークン（メトリック名）が期待されている。 残り全てのトークンは、そのメトリック名に対するdocstringと見なされる。 HELP行は、メトリック名の後ろに、UTF-8の文字の任意の並びを含んで良いが、バックスラッシュとline feedは、それぞれ\\や\nのようにエスケープする必要がある。 どのメトリック名に対しても、1つのHELP行だけ存在して良い。

そのトークンがTYPEなら、ちょうど2つのトークンが期待されている。 1つ目がメトリック名、2つ目はounter、gauge、histogram、summary、untypedのいずれかでそのメトリック名の型を定義する。 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文字の任意の並びで良いが、バックスラッシュ、ダブルクオート、line feed文字は、それぞれ\\、\"、\nのようにエスケープしなければならない
  • valueは、Goの関数ParseFloat()の仕様に従ったfloatである。標準的な数値に加えて、Nan、+Inf、-Infが有効な値で、それぞれ数値でない、正の無限、負の無限を表す
  • timestampは、Goの関数ParseInt()の仕様に従ったint64（エポック、つまり1970-01-01 00:00:00 UTCからの、うるう秒を除く、ミリ秒）である

Grouping and sorting

あるメトリックのための全ての行は、オプションでHELPとTYPEの行を伴って、1つのグループとして提供されていなければならない。 さらに、繰り返して出力される際に、再現性のある並び順になっていることが望ましいが、必須ではない。言い換えると、計算コストが高価な場合にはソートしないこと。

各行は、メトリック名とラベルのユニークな組み合わせになっていなければならない。 そうでなければ、それを取り込む際の振る舞いは定義されていない。

ヒストグラムとサマリー

ヒストグラムとサマリーはテキストフォーマットで表すのが難しい。 以下の慣例を適用する。

  • 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

過去のバージョン

過去のフォーマットのバージョンの詳細は、Client Data Exposition Formatを参照すること。

参考リンク

おすすめ書籍

入門 Prometheus ―インフラとアプリケーションのパフォーマンスモニタリング

入門 Prometheus ―インフラとアプリケーションのパフォーマンスモニタリング

入門 監視 ―モダンなモニタリングのためのデザインパターン

入門 監視 ―モダンなモニタリングのためのデザインパターン

SRE サイトリライアビリティエンジニアリング ―Googleの信頼性を支えるエンジニアリングチーム

SRE サイトリライアビリティエンジニアリング ―Googleの信頼性を支えるエンジニアリングチーム

和訳活動の支援

Prometheusドキュメント和訳が役に立った方は、以下QRコードからPayPayで活動を支援して頂けるとありがたいです。

PayPayによる支援用QRコード
上のQRコードからPayPayによる支援