Prometheus のあらゆる部分、つまりスクレイピング、ストレージ、PromQL、アラートは、同じ基底の構造の上で動作します。名前とラベルのセットで識別され、タイムスタンプ付きの値のストリームでできた時系列です。このガイドでは、その構造と、ターゲットがそれを公開するために使うプレーンテキスト形式を説明します。

時系列は、名前、ラベルのセット、サンプルのストリーム

メトリクス名は、何が測定されているかを記述します。http_requests_total、process_open_fds、node_memory_available_bytes などです。メトリクス名だけでは、まだ単一の時系列ではなく、ラベルが個々の系列に細分化するファミリーです。ラベルは、メトリクスに付けられるキーと値のペアです。method="GET"、status="500"、path="/api/users" などです。メトリクス名と特定のラベル値のセットの組み合わせが、ちょうど 1 つの時系列を識別します。

http_requests_total{method="GET", status="200", path="/api/users"}
http_requests_total{method="GET", status="500", path="/api/users"}
http_requests_total{method="POST", status="200", path="/api/orders"}

これらは、1 つのメトリクス名を共有する、3 つの異なる時系列です。Prometheus は、アプリケーション自身が公開することを選んだラベルに加えて、系列がどのターゲットとジョブから来たかを識別する独自のラベルも自動的に付与します。

サンプルは系列内の 1 つの点です。64 ビットのミリ秒のタイムスタンプ（通常はスクレイプの瞬間）と、64 ビットの浮動小数点の値の組です。系列は、スクレイプごとに 1 つずつ、時間とともに蓄積されるこれらのサンプルの継続的なストリームです。

4 つのメトリクスの種類

Prometheus のクライアントライブラリは、4 種類のメトリクスを公開しており、クエリするときにそれぞれ意味が異なります。

• Counter：増える一方の値（または再起動時にゼロにリセットされる値）で、処理したリクエストの累計のようなものです。counter の生の値を読むことはほとんどありません。その上の変化率を計算します。これは PromQL のガイドで説明します。
• Gauge：上がることも下がることもある値で、現在のメモリ使用量や処理中のリクエスト数のようなものです。counter と異なり、直接読みます。
• Histogram：観測値（リクエストの所要時間、レスポンスのサイズ）を設定可能なバケットにサンプリングし、それらと並んでカウントと合計を公開します。これにより、保存されたバケットデータから、後で分位数（「95 パーセンタイルのレイテンシー」など）を計算できます。
• Summary：histogram に似ていますが、バケットからではなく、観測時にクライアント側で分位数を計算します。クエリのコストは低いですが、summary の分位数は、histogram のバケットのようにインスタンス間で集約できません。そのため、フリート全体で集約するものには、histogram のほうがよく選ばれます。

ネイティブな histogram の型は、従来のバケット形式よりも効率的に完全な解像度の histogram データを保存するもので、しばらく活発に開発されてきました。それに依存する前に、現在の成熟度について、Prometheus の最新のドキュメントを確認してください。最近のリリースを通じて、どの程度公式にサポートされているかが変化してきたためです。

公開形式

Prometheus がターゲットからスクレイプできるように、そのターゲットは、現在の値を、特定の意図的にシンプルなレイアウトのプレーンテキストとして、HTTP で提供します。

# HELP http_requests_total Total number of HTTP requests handled.
# TYPE http_requests_total counter
http_requests_total{method="GET", status="200"} 8420
http_requests_total{method="GET", status="500"} 12

# HELP process_open_fds Number of open file descriptors.
# TYPE process_open_fds gauge
process_open_fds 27

# HELP と # TYPE の行は、ドキュメントとメトリクスの種類を提供するコメントです。コメント以外の他のすべての行は、1 つの系列の現在の値で、メトリクス名、波括弧内のラベル、値そのものです。これは単なるスナップショットで、系列ごとに現在の値を示す 1 行にすぎないため、スクレイプのレスポンスに履歴はありません。履歴が存在するのは、Prometheus が同じ系列を時間にわたって繰り返しスクレイプし、各結果を保存した後だけです。

この形式のシンプルさは意図的なものです。クライアントライブラリがなくても生成するのが簡単になるように作られており、これが、公式のライブラリサポートのあるソフトウェアだけでなく、ほとんどあらゆるものから Prometheus のメトリクスを取り出せる現実性を生んでいます。

自分で見てみる

スクレイピングは単なる HTTP GET なので、Prometheus サーバーなしに、ブラウザや curl で任意のターゲットの現在のメトリクスを直接見られます。

curl http://localhost:9100/metrics   # たとえば node_exporter のインスタンス

その出力は、Prometheus 自身がスクレイプのたびに受け取るものとまったく同じで、これは本当に有用な、最初のトラブルシューティングの手順になります。ターゲットが Prometheus に正しく表示されない場合、その生の /metrics 出力を直接確認すれば、問題がターゲットにあるのか、Prometheus 自身のスクレイプ設定の何かにあるのかが分かります。

ラベルはどこから来て、なぜ後で重要になるのか

ターゲット自身のラベル（どのエンドポイント、どのメソッド、どのステータスコード）は、アプリケーションや exporter が自分をどう計装したかから来ます。Prometheus は、系列がスクレイプされたジョブと特定のインスタンスを識別する独自のものを、その上に追加します。これらのラベルが合わさって、PromQL の集約とフィルタリングが操作する対象になります。これにより、同じ基底のデータに対して、「すべてのインスタンスにわたるエラー率」や「この 1 つのパスだけのリクエスト率」を尋ねることができ、それがまさに、このシリーズの次のガイドが扱う内容です。