Go の HTTP サービスを Prometheus で監視する
Go ランタイムの指標を公開し、promhttp でルート別のリクエスト数、処理中の件数、処理時間を計測します。収集設定と PromQL の例付き。
注文 API の /orders/123 が 200 を返し、/orders/missing が 404 を返したとします。どちらも同じルートの処理結果です。URL をそのままラベルにすると注文 ID ごとに時系列が分かれ、ルート全体でエラーや処理時間が増えたかを調べづらくなります。
ここでは Go の HTTP ハンドラーに client_golang で計測を追加し、/metrics を Prometheus で収集します。まず Go ランタイムの指標を公開し、次にルート単位のリクエスト数、処理中の件数、処理時間を記録します。
まず Go の標準メトリクスを公開する
この例で固定しているクライアントライブラリには Go 1.23 以降が必要です。空のディレクトリでモジュールを作り、ライブラリを追加します。
go mod init example.com/go-metrics
go get github.com/prometheus/client_golang/prometheus/promhttp@v1.23.2
次のコードを main.go に保存し、go run . で起動します。
package main
import (
"log"
"net/http"
"github.com/prometheus/client_golang/prometheus/promhttp"
)
func main() {
mux := http.NewServeMux()
mux.Handle("/metrics", promhttp.Handler())
log.Fatal(http.ListenAndServe("127.0.0.1:8080", mux))
}
http://127.0.0.1:8080/metrics を開くと、go_goroutines や go_memstats_* などを確認できます。デフォルトのレジストリには Go ランタイムとプロセスのコレクターが登録されています。公開される process_* 指標は OS によって異なります。prometheus.NewRegistry() で独自レジストリを作った場合は、必要なコレクターを登録し、promhttp.HandlerFor にそのレジストリを渡します。Prometheus の Go 計測ガイド(英語)
リクエスト数、同時処理数、処理時間を測る
| メトリクス | 記録する値 | 見るときの観点 |
|---|---|---|
http_requests_total |
ハンドラーから戻った呼び出しの累計。ルート、メソッド、ステータスコードで区分 | 同じルートでリクエストレートや応答の内訳が変わったか |
http_active_requests |
このプロセスでハンドラー内にある呼び出しの件数 | 同時に処理するリクエストが増えているか |
http_request_duration_seconds |
ハンドラー内で経過した時間の分布。単位は秒 | 遅い側の分位点や、所定の時間内に収まった件数 |
処理を終えるリクエストのレートが横ばいでも、処理中の件数は増えることがあります。件数だけでは、データベースの待ち時間が延びたのか、処理量が増えたのかは分かりません。処理時間の分布と応答の内訳を合わせて確認します。
登録したルートのハンドラーを計測する
最初のサーバーを止め、main.go を次のコードに差し替えます。ルートの登録時に確定するテンプレートをラベルに使い、注文 ID はハンドラー内で使います。
package main
import (
"fmt"
"log"
"net/http"
"github.com/prometheus/client_golang/prometheus"
"github.com/prometheus/client_golang/prometheus/promhttp"
)
func main() {
const route = "/orders/{id}"
requests := prometheus.NewCounterVec(prometheus.CounterOpts{
Name: "http_requests_total",
Help: "Completed calls to the instrumented handler.",
}, []string{"route", "method", "code"})
active := prometheus.NewGauge(prometheus.GaugeOpts{
Name: "http_active_requests",
Help: "Calls currently executing in the instrumented handler.",
})
duration := prometheus.NewHistogramVec(prometheus.HistogramOpts{
Name: "http_request_duration_seconds",
Help: "Time spent in the instrumented handler in seconds.",
Buckets: []float64{0.01, 0.05, 0.1, 0.3, 0.5, 1, 2.5, 5},
}, []string{"route"})
prometheus.MustRegister(requests, active, duration)
orders := http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
id := r.PathValue("id")
if id == "missing" {
http.NotFound(w, r)
return
}
fmt.Fprintln(w, "order", id)
})
labels := prometheus.Labels{"route": route}
instrumented := promhttp.InstrumentHandlerInFlight(active,
promhttp.InstrumentHandlerCounter(requests.MustCurryWith(labels),
promhttp.InstrumentHandlerDuration(duration.MustCurryWith(labels), orders),
),
)
mux := http.NewServeMux()
mux.Handle("GET "+route, instrumented)
mux.Handle("/metrics", promhttp.Handler())
log.Fatal(http.ListenAndServe("127.0.0.1:8080", mux))
}
再び go run . を実行し、/orders/123 と /orders/missing にアクセスしてから /metrics を確認します。両方とも route="/orders/{id}" で、code はそれぞれ 200 と 404 です。別の注文 ID を指定しても、そのラベルの組み合わせが同じなら既存の時系列に加算されます。ルーターが返す未一致の 404 やメソッド不一致の 405、メトリクス取得リクエストは、このラッパーを通りません。
カウンターとヒストグラムは、ラップしたハンドラーから処理が戻った後で更新します。panic が外まで伝わった呼び出しでは両方とも更新されず、遅延実行された Gauge の減算は行われます。計測するのはサーバー側のハンドラーに費やした時間です。Go の ServeMux ルーティング(英語) · promhttp の計測ミドルウェア(英語)
Prometheus で収集して遅いリクエストを調べる
この設定は、アプリと Prometheus が同じネットワーク名前空間で動く場合に使えます。別のホストやコンテナから収集するときは、収集側から到達できるアドレスを使い、メトリクスの公開先を制限します。
scrape_configs:
- job_name: go-app
scrape_interval: 15s
static_configs:
- targets: ['127.0.0.1:8080']
何度かスクレイプが成功した後、最初のクエリでルートとステータス別の毎秒リクエスト数を、二つ目でルート別の P99 推定値を確認します。P99 の単位は秒です。
sum by (route, code) (rate(http_requests_total{job="go-app"}[5m]))
histogram_quantile(
0.99,
sum by (le, route) (rate(http_request_duration_seconds_bucket{job="go-app"}[5m]))
)
インスタンスを集計する前に、カウンターごとに rate() を適用します。観測できたリセットは補正されますが、スクレイプ間に失われた増分は復元できません。クラシックヒストグラムの集計では le を残し、インスタンス間でバケット境界をそろえます。300 ミリ秒を目標にするなら、リクエストがある時間帯に 0.3 秒以下のバケットと全観測件数それぞれの増加率を比べ、目標内に収まった割合を求められます。Prometheus のクエリ関数(英語)
同じ公開先を Guance の DataKit Prom コレクター(英語) で収集することもできます。urls に到達可能なメトリクス URL を指定し、クエリやアラートを移す前に、保存された指標名、タグ、単位を確認します。RED と USE の指標 では、リクエスト側の変化をリソース側の状況と照らし合わせる手順を説明しています。
