Prometheus로 Go HTTP 서비스 모니터링하기
Go 런타임 메트릭을 노출하고 promhttp로 라우트별 요청 수, 처리 중인 요청 수, 지연 시간을 기록합니다. 수집 설정과 PromQL 예제도 제공합니다.
주문 API에서 /orders/123은 200을, /orders/missing은 404를 반환한다고 가정해 보겠습니다. 둘 다 같은 라우트의 처리 결과입니다. 원본 URL을 라벨로 쓰면 주문 ID마다 시계열이 나뉘어, 정작 이 라우트의 오류나 처리 시간이 늘었는지 파악하기 어렵습니다.
이 글에서는 client_golang으로 Go HTTP 핸들러를 계측하고 Prometheus가 가져갈 수 있도록 /metrics에 노출합니다. 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_* 메트릭은 운영체제마다 다릅니다. 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이 핸들러 밖까지 전파되면 두 지표는 갱신되지 않지만, defer로 등록한 게이지 감소는 실행됩니다. 측정값은 서버가 핸들러에서 보낸 시간입니다. Go ServeMux 라우팅(영어) · promhttp 계측 미들웨어(영어)
수집 대상을 설정하고 지연 분포 확인하기
이 설정은 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를 유지하고 인스턴스 간 버킷 경계를 맞춥니다. 목표가 300ms라면 트래픽이 있는 시간대에 0.3초 버킷의 증가율을 전체 관측 횟수의 증가율로 나눠 목표 시간 안에 처리한 요청의 비율을 구할 수 있습니다. Prometheus 쿼리 함수(영어)
Guance의 DataKit Prom 수집기(영어)로도 같은 엔드포인트를 수집할 수 있습니다. urls에 접근 가능한 메트릭 URL을 설정하고, 쿼리나 알림을 옮기기 전에 저장된 이름과 태그, 단위를 확인합니다. 요청 측 지표와 리소스 부하를 함께 보는 방법은 RED와 USE 메트릭에 이어서 설명합니다.
