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 は同じ属性で集計したリクエスト件数として使えます。例の二件はステータスコードの属性が異なるため、それぞれの Count は一です。一方、業務用の orders.created には成立した注文だけが入り、channel=app の値は一になります。

HTTP ミドルウェアはボディーサイズも計測します。SDK の View は http.server.request.body.size を送信前に除外し、応答ボディーサイズとリクエスト時間のストリームは残します。メトリクスを残したまま次元を減らすには、View で属性を絞り、残った属性だけで必要なクエリが組めるか確認します。

測りたい値に合わせて計測器を選ぶ

知りたいこと 計測器 記録する値
成立した注文は何件か Counter 0 以上の増分を加算します。集計する側で時間性とリセットを考慮します。
処理中のリクエストは何件か UpDownCounter 開始時に加算し、終了時に同じ属性で減算します。二件の処理が終わるとゼロに戻ります。
現在のキューの深さは Gauge 実測値を記録します。例では固定値の二を使います。収集時に読み取るなら ObservableGauge も使えます。
処理時間はどう分布するか Histogram 経過時間を秒で記録します。例では 250 ms にもバケット境界を置いています。

しきい値を使ってアラートを出すなら、その前後にバケット境界を置きます。明示的なバケットを使う 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 のモニター設定

運用時によくある質問

サービスを再起動すると Counter はどうなりますか?

Cumulative の 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 ランタイム計装(英語)

参照資料

関連記事

最適なプランを相談する

お問い合わせ

コミュニティに参加

WeChatでスキャンして
コミュニティに参加

Guanceを試す

オンラインですぐに始めて、使った分だけお支払いください。

利用を開始

Guanceのプランを選択

コードリポジトリ