Prometheus Rubyクライアントライブラリ - Prometheusドキュメント

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

Prometheus Ruby Client

Prometheus Rubyクライアントは、HTTPインターフェースを通してexpose出来るRuby用のメトリクスプリミティブ一式である。 Prometheusサーバーと共に利用されることを意図している。

利用方法

概要

require 'prometheus/client'

# デフォルトのレジストリを返す
prometheus = Prometheus::Client.registry

# 新規カウンターメトリックを作成する
http_requests = Prometheus::Client::Counter.new(:http_requests, 'A counter of HTTP requests made')
# 作成したメトリックを登録する
prometheus.register(http_requests)

# 同等のヘルパー関数
http_requests = prometheus.counter(:http_requests, 'A counter of HTTP requests made')

# カウンターの利用を開始する
http_requests.increment

Rack middleware

2つのRackミドルウェアが利用可能である。 Prometheusサーバー(Exporter)にscrapeされるHTTPエンドポイントをexposeするもの、および、全てのHTTPリクエストを追跡するもの(Collector)である。

Rack::Deflaterミドルウェアを使うなどして、メトリクスのエンドポイントをgzip圧縮可能にすることが強く推奨されている。

# config.ru

require 'rack'
require 'prometheus/middleware/collector'
require 'prometheus/middleware/exporter'

use Rack::Deflater
use Prometheus::Middleware::Collector
use Prometheus::Middleware::Exporter

run ->(_) { [200, {'Content-Type' => 'text/html'}, ['OK']] }

サーバーを起動して、エンドポイントhttp://localhost:5000/metricsを確認する。

さらなる手順や手始めとなる他のスクリプトが必要な場合、サンプルアプリケーションを見ること。

Pushgateway

Rubyクライアントは、収集したメトリクスをPushgatewayにpushするためにも利用できる。 これは、バッチジョブや、PrometheusサーバーがRubyプロセスをscrapeするのが不可能または非現実的な場合に便利である。 TLSBasic認証がサポートされている。

注意: Pushgatewayの古いAPIを利用して実装されている。

require 'prometheus/client'
require 'prometheus/client/push'

registry = Prometheus::Client.registry
# ... メトリクスを登録し、その値をset/increment/observeなどする

# デフォルtのgatewayにレジストリの状態をpushする
Prometheus::Client::Push.new('my-batch-job').add(registry)

# optional: (IPではなく)インスタンス名とgatewayを指定する
Prometheus::Client::Push.new('my-batch-job', 'foobar', 'https://example.domain:1234').add(registry)

# 以前にpushしたメトリクスを置き換えたい場合は、#replaceメソッドを利用する
Prometheus::Client::Push.new('my-batch-job').replace(registry)

# 以前にpushしたメトリクスを削除したい場合、#deleteメソッドを利用する
Prometheus::Client::Push.new('my-batch-job').delete

Metrics

現状、以下のメトリクス型がサポートされている。

Counter

カウンターは、単なる物事の合計や計数をexposeするメトリックである。

counter = Prometheus::Client::Counter.new(:service_requests_total, '...')

# ラベル集合を指定してカウンターをインクリメントする
counter.increment({ service: 'foo' })

# 指定された値でインクリメントする
counter.increment({ service: 'bar' }, 5)

# 指定されたラベル集合に対する値を取得する
counter.get({ service: 'bar' })
# => 5

Gauge

ゲージは、単なる瞬間的な値またはそのスナップショットをexposeするメトリックである。

gauge = Prometheus::Client::Gauge.new(:room_temperature_celsius, '...')

# 値をセットする
gauge.set({ room: 'kitchen' }, 21.534)

# 指定されたラベル集合に対する値を取得する
gauge.get({ room: 'kitchen' })
# => 21.534

# 値をインクリメントする(デフォルトは1)
gauge.increment({ room: 'kitchen' })
# => 22.534

# 指定された値でデクリメントする
gauge.decrement({ room: 'kitchen' }, 5)
# => 17.534

Histogram

ヒストグラムは、観測値(普通は、リクエスト持続時間やレスポンスサイズのようなもの)を採取およびバケット単位での計数をする。 また、全ての観測値の合計も提供する。

histogram = Prometheus::Client::Histogram.new(:service_latency_seconds, '...')

# 値を記録する
histogram.observe({ service: 'users' }, Benchmark.realtime { service.call(arg) })

# 現在のバケットの値を取得する
histogram.get({ service: 'users' })
# => { 0.005 => 3, 0.01 => 15, 0.025 => 18, ..., 2.5 => 42, 5 => 42, 10 = >42 }

Summary

サマリーは、ヒストグラムと同じように、サンプルを累積するものである。 数値的なデータを記録し、パーセンタイルを計算する効率的な仕組みを提供する。

summary = Prometheus::Client::Summary.new(:service_latency_seconds, '...')

# 値を記録する
summary.observe({ service: 'database' }, Benchmark.realtime { service.call() })

# 現在の分位数を取得する
summary.get({ service: 'database' })
# => { 0.5 => 0.1233122, 0.9 => 3.4323, 0.99 => 5.3428231 }

Tests

bundle installで、開発に必要なgemをインストールし、rspecでテストを実行する

rake

参考リンク

おすすめ書籍

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

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

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

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

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

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

和訳活動の支援

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

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