Go에서 OpenTelemetry 메트릭 수집하기: 계측, View, OTLP
OpenTelemetry Go Metrics SDK로 HTTP 요청과 주문을 계측하고, View로 불필요한 스트림을 제거한 뒤 OTLP/gRPC 전송을 로컬에서 확인합니다.
주문 API가 느려져도 실제로 접수된 주문 수는 그대로일 수 있습니다. 응답 시간의 변화는 요청 시간 히스토그램에서 확인하고, 주문 생성 건수는 업무용 카운터로 따로 셉니다. Go용 OpenTelemetry Metrics SDK를 사용하면 같은 애플리케이션에서 두 신호를 계측하고 OTLP로 보낼 수 있습니다.
이 글에서는 성공 응답과 503 응답을 하나씩 만들어 Go SDK에서 로컬 OpenTelemetry Collector로 메트릭을 전송합니다. 두 요청으로 HTTP 자동 계측, 업무용 계측, 불필요한 스트림을 제거하는 View까지 확인합니다.
로컬 OTLP 수신기 실행하기
다음 설정을 collector.yaml에 저장하고 otelcol-contrib --config=collector.yaml을 실행합니다. gRPC 수신기는 루프백 주소에서 대기합니다. debug 익스포터가 데이터를 출력하므로 별도 백엔드 없이도 내용을 확인할 수 있습니다.
receivers:
otlp:
protocols:
grpc:
endpoint: 127.0.0.1:14317
exporters:
debug:
verbosity: detailed
service:
pipelines:
metrics:
receivers: [otlp]
exporters: [debug]
Go 1.26, OpenTelemetry Go SDK 1.47.0, Go contrib 계측 패키지 0.72.0, Collector Contrib 0.165.0에서 예제를 확인했습니다. 빈 디렉터리에서 의존성을 설치합니다.
go mod init example.com/otel-order-metrics
go get go.opentelemetry.io/otel/metric@v1.47.0 \
go.opentelemetry.io/otel/sdk@v1.47.0 \
go.opentelemetry.io/otel/sdk/metric@v1.47.0 \
go.opentelemetry.io/otel/exporters/otlp/otlpmetric/otlpmetricgrpc@v1.47.0 \
go.opentelemetry.io/contrib/instrumentation/net/http/otelhttp@v0.72.0 \
go.opentelemetry.io/contrib/instrumentation/runtime@v0.72.0
HTTP 핸들러에 MeterProvider 전달하기
MeterProvider에 애플리케이션의 리소스 이름, 주기적으로 수집하는 Reader, View를 설정합니다. Reader는 메트릭 데이터 포인트를 OTLP/gRPC로 내보냅니다. 30초는 프로세스가 실행 중일 때 적용하는 수집 간격입니다. 이 짧은 예제에서는 HTTP 테스트 서버를 닫은 다음 별도의 제한 시간을 둔 Shutdown으로 마지막 수집과 전송을 진행합니다. 코드를 main.go에 저장하고 go run .으로 실행합니다.
package main
import (
"context"
"errors"
"fmt"
"io"
"log"
"net/http"
"net/http/httptest"
"strings"
"time"
"go.opentelemetry.io/contrib/instrumentation/net/http/otelhttp"
otelruntime "go.opentelemetry.io/contrib/instrumentation/runtime"
"go.opentelemetry.io/otel/attribute"
"go.opentelemetry.io/otel/exporters/otlp/otlpmetric/otlpmetricgrpc"
"go.opentelemetry.io/otel/metric"
sdkmetric "go.opentelemetry.io/otel/sdk/metric"
"go.opentelemetry.io/otel/sdk/resource"
)
func orderHandler(meter metric.Meter) (http.Handler, error) {
created, err := meter.Int64Counter("orders.created", metric.WithUnit("{order}"))
if err != nil {
return nil, err
}
inFlight, err := meter.Int64UpDownCounter("orders.inflight", metric.WithUnit("{request}"))
if err != nil {
return nil, err
}
queueDepth, err := meter.Int64Gauge("orders.queue.depth", metric.WithUnit("{order}"))
if err != nil {
return nil, err
}
duration, err := meter.Float64Histogram("orders.process.duration", metric.WithUnit("s"),
metric.WithExplicitBucketBoundaries(0.05, 0.1, 0.25, 0.5, 1, 5))
if err != nil {
return nil, err
}
return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
ctx := r.Context()
started := time.Now()
inFlight.Add(ctx, 1)
defer inFlight.Add(ctx, -1)
defer func() { duration.Record(ctx, time.Since(started).Seconds()) }()
queueDepth.Record(ctx, 2)
if _, err := io.Copy(io.Discard, r.Body); err != nil {
w.WriteHeader(http.StatusBadRequest)
return
}
if r.URL.Query().Get("fail") == "1" {
w.WriteHeader(http.StatusServiceUnavailable)
return
}
created.Add(ctx, 1, metric.WithAttributes(attribute.String("channel", "app")))
w.WriteHeader(http.StatusCreated)
}), nil
}
func run() (err error) {
ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
defer cancel()
exporter, err := otlpmetricgrpc.New(ctx, otlpmetricgrpc.WithEndpoint("127.0.0.1:14317"),
otlpmetricgrpc.WithInsecure())
if err != nil {
return err
}
mp := sdkmetric.NewMeterProvider(
sdkmetric.WithResource(resource.NewSchemaless(attribute.String("service.name", "order-service"))),
sdkmetric.WithReader(sdkmetric.NewPeriodicReader(exporter, sdkmetric.WithInterval(30*time.Second))),
sdkmetric.WithView(sdkmetric.NewView(
sdkmetric.Instrument{Name: "http.server.request.body.size"},
sdkmetric.Stream{Aggregation: sdkmetric.AggregationDrop{}},
)),
)
defer func() {
shutdownCtx, stop := context.WithTimeout(context.Background(), 5*time.Second)
defer stop()
err = errors.Join(err, mp.Shutdown(shutdownCtx))
}()
if err := otelruntime.Start(otelruntime.WithMeterProvider(mp)); err != nil {
return err
}
const route = "/orders"
handler, err := orderHandler(mp.Meter("example.com/order-service"))
if err != nil {
return err
}
mux := http.NewServeMux()
mux.Handle("POST "+route, otelhttp.NewHandler(
handler, route, otelhttp.WithMeterProvider(mp),
))
server := httptest.NewServer(mux)
defer server.Close()
for _, suffix := range []string{"", "?fail=1"} {
req, err := http.NewRequestWithContext(ctx, http.MethodPost,
server.URL+route+suffix, strings.NewReader("demo"))
if err != nil {
return err
}
resp, err := server.Client().Do(req)
if err != nil {
return err
}
resp.Body.Close()
fmt.Println(resp.StatusCode)
}
return nil
}
func main() {
if err := run(); err != nil {
log.Fatal(err)
}
}
WithInsecure()는 전송 계층 보안을 끕니다. 여기서는 로컬 테스트 수신기에만 사용합니다. 원격으로 전송할 때는 배포 환경에 맞는 수신 주소, TLS 설정, 필요한 인증 정보를 사용합니다.
HTTP 관측 건수와 업무 건수를 나눠 보기
프로그램은 201과 503을 출력합니다. Collector에서 service.name=order-service와 http.server.request.duration을 찾아봅니다. 이 버전의 otelhttp는 계측한 요청이 완료될 때마다 히스토그램에 관측값을 하나씩 기록합니다. Count로 같은 속성 조합의 요청 수를 알 수 있습니다. 예제에서는 두 응답의 상태 코드 속성이 달라 각각 한 건이 됩니다. 업무 카운터 orders.created에는 실제로 생성된 주문만 들어가므로 channel=app의 값은 1입니다.
HTTP 미들웨어는 본문 크기도 기록합니다. SDK의 View가 http.server.request.body.size 스트림을 내보내기 전에 제거합니다. 응답 본문 크기와 요청 소요 시간은 남습니다. 메트릭을 유지하면서 차원을 줄이려면 View로 속성을 필터링하고 남은 속성만으로 필요한 쿼리를 만들 수 있는지 확인합니다.
측정할 값에 맞는 계측기 고르기
| 알고 싶은 것 | 계측기 | 기록 방식 |
|---|---|---|
| 주문이 몇 건 생성됐는가 | Counter | 0 이상의 증가분을 더합니다. 집계 쿼리에서는 시간성과 초기화를 고려합니다. |
| 처리 중인 요청이 몇 건인가 | UpDownCounter | 들어올 때 더하고, 끝날 때 같은 속성으로 뺍니다. 두 요청이 끝나면 0으로 돌아옵니다. |
| 현재 큐에 몇 건이 쌓였는가 | Gauge | 관측한 값을 기록합니다. 예제는 고정값 2를 사용합니다. 수집 시점에 읽으려면 ObservableGauge를 사용할 수 있습니다. |
| 처리 시간은 어떻게 분포하는가 | Histogram | 경과 시간을 초 단위로 기록합니다. 예제에는 250ms 버킷 경계가 있습니다. |
알림에 쓰는 지연 시간 기준 주변에 버킷 경계를 둡니다. 명시적 버킷으로 계산하는 P95 추정치는 버킷의 해상도에 영향을 받습니다. 복제본을 합산할 때는 버킷 구성이 호환되는지 확인하고, 백엔드에서 분포를 먼저 합친 뒤 분위수를 추정합니다.
메트릭 이름을 일정하게 유지하고 초는 s, 바이트는 By처럼 단위를 명시합니다. 속성에는 채널이나 리전처럼 쿼리에 쓰는 차원만 둡니다. 요청 ID나 URL 전체를 넣으면 요청마다 시계열이 생길 수 있습니다. 라우트는 /orders/{id} 같은 템플릿을 사용합니다. 메트릭 카디널리티가 늘어나는 이유
같은 메트릭을 Guance로 보내기
로컬 Collector에서는 백엔드가 변환하기 전의 OTLP 데이터를 볼 수 있습니다. DataKit을 사용하려면 OpenTelemetry 입력을 활성화한 다음 수신기 설정과 네트워크 경로를 확인합니다. gRPC 익스포터는 설정된 gRPC 수신 주소를 사용합니다. OTLP/HTTP를 사용한다면 HTTP/Protobuf 익스포터와 해당 메트릭 경로를 지정합니다. DataKit 문서의 기본 HTTP 포트는 9529이며 메트릭 경로는 /otel/v1/metrics입니다. DataKit OpenTelemetry 입력 설정
정해진 수만큼 요청을 보내고, 받은 메트릭의 이름, 단위, 속성과 히스토그램 표현을 확인한 뒤 모니터를 설정합니다. 트레이스를 함께 조사할 때는 서비스와 환경 값을 맞추고 대상 스팬이 수집됐는지 확인합니다. 집계된 포인트는 여러 관측값을 요약하므로 보통 하나의 트레이스를 바로 가리킬 수 없습니다. Guance 모니터 설정
운영할 때 자주 묻는 질문
서비스를 재시작하면 카운터는 어떻게 되나요?
누적 OTLP 포인트에는 시작 시각을 포함할 수 있습니다. 프로세스가 재시작하면 새 스트림에서 다시 누적합니다. 백엔드에서 초기화 전후의 처리율을 어떻게 계산하는지 확인합니다. Delta로 설정했다면 구간별 변화량이 전송되므로 백엔드도 같은 기준으로 해석해야 합니다.
복제본 여러 개의 Summary를 합칠 수 있나요?
클라이언트별로 계산한 분위수를 조합해 전체 분위수를 구하기는 일반적으로 어렵습니다. Go Metrics API에서 분포를 기록하는 계측기는 Histogram입니다. 백엔드에서 호환되는 히스토그램을 합산한 뒤 전체 분포의 분위수를 추정할 수 있습니다.
얼마나 자주 내보내는 게 좋나요?
예제는 30초로 설정했습니다. 알림의 평가 구간, 수신기의 처리 여유, 데이터가 얼마나 최신이어야 하는지에 맞춰 결정합니다. 주기를 줄이면 전송 배치가 늘어나므로 실제 데이터 규모로 영향을 측정합니다.
Go 런타임 메트릭은 어떻게 수집하나요?
예제는 같은 Provider에 runtime.Start를 호출합니다. 지정한 contrib 버전에서 go.goroutine.count, go.memory.gc.goal 같은 메트릭을 등록합니다. 스케줄링 대기 시간 히스토그램 go.schedule.duration이 필요하면 Reader에 runtime.NewProducer()를 추가합니다. 사용 중인 버전의 메트릭 이름과 지원 여부를 확인합니다. Go 런타임 계측 문서(영어)
