Go 애플리케이션 계측하기

Go 애플리케이션 계측하기 (Instrumenting a Go application)

이 문서는 Go 애플리케이션에 Prometheus 계측(instrumentation)을 추가하는 방법을 보여줘요. 공식 Go 클라이언트 라이브러리(client_golang)를 사용해 서버에 /metrics 엔드포인트를 노출하고, 히스토그램·카운터·게이지 같은 메트릭을 기록하는 예시를 다룹니다.

Go 애플리케이션에 메트릭을 넣으면 애플리케이션 내부 동작(요청 수, 지연, 오류 등)을 Prometheus에서 모니터링할 수 있어요. 가장 간단한 시작은 promhttp 핸들러를 등록해 HTTP 서버가 기본 Go 런타임·프로세스 메트릭과 함께 /metrics를 제공하게 하는 것입니다.

출처: 문서

본문

클라이언트 라이브러리 가져오기

Go 클라이언트 라이브러리 client_golang을 사용합니다:

go get github.com/prometheus/client_golang/prometheus
go get github.com/prometheus/client_golang/prometheus/promhttp

기본 HTTP 서버에 /metrics 노출

가장 단순한 형태는 기본 핸들러에 promhttp.Handler()를 등록하는 것입니다:

package main

import (
	"net/http"

	"github.com/prometheus/client_golang/prometheus/promhttp"
)

func main() {
	http.Handle("/metrics", promhttp.Handler())
	http.ListenAndServe(":2112", nil)
}

이 서버를 실행하고 http://localhost:2112/metrics에 접근하면 Go 런타임(go_*)과 프로세스(process_*) 메트릭을 포함한 기본 메트릭을 볼 수 있습니다. promhttp.Handler()는 등록된 모든 수집기(collector)를 노출합니다.

사용자 정의 메트릭 추가

prometheus 패키지로 카운터·게이지·히스토그램을 정의합니다.

package main

import (
	"net/http"

	"github.com/prometheus/client_golang/prometheus"
	"github.com/prometheus/client_golang/prometheus/promauto"
	"github.com/prometheus/client_golang/prometheus/promhttp"
)

var (
	opsProcessed = promauto.NewCounter(prometheus.CounterOpts{
		Name: "myapp_processed_ops_total",
		Help: "The total number of processed events",
	})
)

func main() {
	http.Handle("/metrics", promhttp.Handler())
	http.ListenAndServe(":2112", nil)
}

promauto는 메트릭을 자동으로 기본 레지스트리에 등록해 줍니다. 카운터를 증가시키려면 코드 어디에서든:

opsProcessed.Inc()

히스토그램 (지연 측정)

요청 지연을 측정하려면 히스토그램을 사용합니다:

var (
	requestDuration = promauto.NewHistogram(prometheus.HistogramOpts{
		Name:    "myapp_request_duration_seconds",
		Help:    "Histogram of request durations",
		Buckets: prometheus.DefBuckets,
	})
)

func handler(w http.ResponseWriter, r *http.Request) {
	start := time.Now()
	// ... 요청 처리 ...
	requestDuration.Observe(time.Since(start).Seconds())
}

히스토그램 메트릭은 _bucket, _sum, _count 접미사로 노출되며, PromQL의 histogram_quantile()로 백분위를 계산할 수 있습니다.

서버에 등록

HTTP 서버를 만들고 /metrics에 promhttp.Handler()를 등록하면, 등록된 모든 메트릭이 노출됩니다.

더 알아보기 (Learn more)