Prometheus로 Go HTTP 서비스 모니터링하기

Go 런타임 메트릭을 노출하고 promhttp로 라우트별 요청 수, 처리 중인 요청 수, 지연 시간을 기록합니다. 수집 설정과 PromQL 예제도 제공합니다.

모범 사례
Prometheus 모니터링과 대시보드 일러스트

주문 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 메트릭에 이어서 설명합니다.

맞춤형 플랜 상담

문의하기

커뮤니티 가입

WeChat으로 스캔하여
커뮤니티에 가입하세요

Guance 사용해 보기

온라인에서 바로 시작하고 사용한 만큼만 결제하세요.

시작하기

Guance 요금제 선택

코드 저장소