OpenTelemetry Collector サイドカーを使用して OTLP 指標を書き込む

このチュートリアルでは、Google が構築した OpenTelemetry Collector をサイドカーとして使用して、カスタム OTLP 指標を Google Cloud Managed Service for Prometheus に報告する Cloud Run サービスの作成、デプロイ、呼び出しを行う方法について説明します。Google が構築した Collector の詳細については、Google が構築した OpenTelemetry Collector の概要をご覧ください。

Prometheus 指標を報告する Cloud Run サービスがある場合は、代わりに Cloud Run の Prometheus サイドカーを使用します。

gcloud のデフォルトを設定する

Cloud Run サービスを gcloud のデフォルトに構成するには:

  1. デフォルト プロジェクトを設定します。

    gcloud config set project PROJECT_ID

    PROJECT_ID は、このチュートリアルで作成したプロジェクトの名前に置き換えます。

  2. 選択したリージョン向けに gcloud を構成します。

    gcloud config set run/region REGION

    REGION は、任意のサポートされている Cloud Run のリージョンに置き換えます。

Cloud Run のロケーション

Cloud Run はリージョナルです。つまり、Cloud Run サービスを実行するインフラストラクチャは特定のリージョンに配置され、そのリージョン内のすべてのゾーンで冗長的に利用できるように Google によって管理されます。

レイテンシ、可用性、耐久性の要件を満たしていることが、Cloud Run サービスを実行するリージョンを選択する際の主な判断材料になります。一般的には、ユーザーに最も近いリージョンを選択できますが、Cloud Run サービスで使用されている他の Google Cloudプロダクトのロケーションも考慮する必要があります。 Google Cloud プロダクトを複数のロケーションで使用すると、サービスのレイテンシだけでなく、コストにも影響を及ぼす可能性があります。

Cloud Run は、次のリージョンで利用できます。

ティア 1 料金を適用

  • asia-east1（台湾）
  • asia-northeast1（東京）
  • asia-northeast2（大阪）
  • asia-south1（ムンバイ、インド）
  • europe-north1（フィンランド） リーフアイコン 低 CO2
  • europe-north2（ストックホルム） リーフアイコン 低 CO2
  • europe-southwest1（マドリッド） リーフアイコン 低 CO2
  • europe-west1（ベルギー） リーフアイコン 低 CO2
  • europe-west4（オランダ） リーフアイコン 低 CO2
  • europe-west8（ミラノ）
  • europe-west9（パリ） リーフアイコン 低 CO2
  • me-west1（テルアビブ）
  • northamerica-south1（メキシコ）
  • us-central1（アイオワ） リーフアイコン 低 CO2
  • us-east1（サウスカロライナ）
  • us-east4（北バージニア）
  • us-east5（コロンバス）
  • us-south1（ダラス） リーフアイコン 低 CO2
  • us-west1（オレゴン） リーフアイコン 低 CO2

ティア 2 料金を適用

  • africa-south1（ヨハネスブルグ）
  • asia-east2（香港）
  • asia-northeast3（ソウル、韓国）
  • asia-southeast1（シンガポール）
  • asia-southeast2 （ジャカルタ）
  • asia-south2（デリー、インド）
  • australia-southeast1（シドニー）
  • australia-southeast2（メルボルン）
  • europe-central2（ワルシャワ、ポーランド）
  • europe-west10（ベルリン）
  • europe-west12（トリノ）
  • europe-west2（ロンドン、イギリス） リーフアイコン 低 CO2
  • europe-west3（フランクフルト、ドイツ）
  • europe-west6（チューリッヒ、スイス） リーフアイコン 低 CO2
  • me-central1（ドーハ）
  • me-central2（ダンマーム）
  • northamerica-northeast1（モントリオール） リーフアイコン 低 CO2
  • northamerica-northeast2（トロント） リーフアイコン 低 CO2
  • southamerica-east1（サンパウロ、ブラジル） リーフアイコン 低 CO2
  • southamerica-west1（サンティアゴ、チリ） リーフアイコン 低 CO2
  • us-west2（ロサンゼルス）
  • us-west3（ソルトレイクシティ）
  • us-west4（ラスベガス）

Cloud Run サービスをすでに作成している場合は、Google Cloud コンソールの Cloud Run ダッシュボードにリージョンが表示されます。

Artifact Registry イメージ リポジトリを作成する

サンプル サービス イメージをホストする Artifact Registry Docker リポジトリを作成します。

gcloud artifacts repositories create run-otel \
    --repository-format=docker \
    --location=REGION \
    --project=PROJECT_ID

次のように置き換えます。

  • PROJECT_ID は、このチュートリアルで作成したプロジェクトの名前に置き換えます。
  • REGION REGION は、サポートされている任意の Cloud Run のリージョンに置き換えます。

コードサンプルを取得する

使用するコードサンプルを取得するには:

  1. ローカルマシンにサンプルアプリのリポジトリのクローンを作成します。

    Go

    git clone https://github.com/GoogleCloudPlatform/golang-samples.git

    または、zip 形式のサンプルをダウンロードし、ファイルを抽出してもかまいません。

  2. Cloud Run のサンプルコードが含まれているディレクトリに移動します。

    Go

    cd golang-samples/run/custom-metrics/

コードの確認

このチュートリアルのコードは、次のものから構成されています。

  • 受信リクエストを処理し、sidecar_sample_counter_total という名前の指標を生成するサーバー。
package main

import (
	"context"
	"fmt"
	"log"
	"net/http"
	"os"

	"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"
	semconv "go.opentelemetry.io/otel/semconv/v1.24.0"
)

var counter metric.Int64Counter

func main() {
	ctx := context.Background()
	shutdown := setupCounter(ctx)
	defer shutdown(ctx)

	port := os.Getenv("PORT")
	if port == "" {
		port = "8080"
		log.Printf("defaulting to port %s", port)
	}

	http.HandleFunc("/", handler)
	log.Fatal(http.ListenAndServe(":"+port, nil))
}

func handler(w http.ResponseWriter, r *http.Request) {
	counter.Add(context.Background(), 100)
	fmt.Fprintln(w, "Incremented sidecar_sample_counter_total metric!")
}

func setupCounter(ctx context.Context) func(context.Context) error {
	serviceName := os.Getenv("K_SERVICE")
	if serviceName == "" {
		serviceName = "sample-cloud-run-app"
	}
	r, err := resource.Merge(
		resource.Default(),
		resource.NewWithAttributes(
			resource.Default().SchemaURL(),
			semconv.ServiceName(serviceName),
		),
	)
	if err != nil {
		log.Fatalf("Error creating resource: %v", err)
	}

	exporter, err := otlpmetricgrpc.New(ctx,
		otlpmetricgrpc.WithInsecure(),
	)
	if err != nil {
		log.Fatalf("Error creating exporter: %s", err)
	}
	provider := sdkmetric.NewMeterProvider(
		sdkmetric.WithReader(sdkmetric.NewPeriodicReader(exporter)),
		sdkmetric.WithResource(r),
	)

	meter := provider.Meter("example.com/metrics")
	counter, err = meter.Int64Counter("sidecar-sample-counter")
	if err != nil {
		log.Fatalf("Error creating counter: %s", err)
	}
	return provider.Shutdown
}
  • サービスの動作環境を定義する Dockerfile。
FROM golang:1.24 as builder
WORKDIR /app
COPY . .
RUN CGO_ENABLED=0 GOOS=linux go build -o sample-app

FROM alpine:3
RUN apk add --no-cache ca-certificates
COPY --from=builder /app/sample-app /sample-app
CMD ["/sample-app"]

このサンプルでは、カスタム コレクタをビルドするためのファイルが collector サブディレクトリに含まれています。

  • コレクタの構成ファイル。

    receivers:
  otlp:
    protocols:
      grpc:
      http:

processors:
  batch:
    # batch metrics before sending to reduce API usage
    send_batch_max_size: 200
    send_batch_size: 200
    timeout: 5s

  memory_limiter:
    # drop metrics if memory usage gets too high
    check_interval: 1s
    limit_percentage: 65
    spike_limit_percentage: 20

  # automatically detect Cloud Run resource metadata                                                                                                                                               
  resourcedetection:
    detectors: [env, gcp]
    timeout: 2s
    override: false

  resource:
    attributes:
    # add instance_id as a resource attribute
    - key: service.instance.id
      from_attribute: faas.id
      action: upsert
      # parse service name from K_SERVICE Cloud Run variable                                                                                                                                       
    - key: service.name
      value: ${env:K_SERVICE}
      action: insert

exporters:
  googlemanagedprometheus: # Note: this is intentionally left blank   

extensions:
  health_check:
    endpoint: 0.0.0.0:13133
service:
  extensions: [health_check]
  pipelines:
    metrics:
      receivers: [otlp]
      processors: [batch, memory_limiter, resourcedetection, resource]
      exporters: [googlemanagedprometheus]

  • 提供された構成をアップストリーム Collector イメージにバンドルする Dockerfile。

    FROM us-docker.pkg.dev/cloud-ops-agents-artifacts/google-cloud-opentelemetry-collector/otelcol-google:0.121.0

COPY collector-config.yaml /etc/otelcol-google/config.yaml

コードの配布

コードの配布は、Cloud Build でコンテナ イメージをビルドする、Artifact Registry にコンテナ イメージをアップロードする、Cloud Run にコンテナ イメージをデプロイするという 3 つのステップで構成されます。

コードを配布するには:

  1. サンプル サービス コンテナをビルドし、Artifact Registry に公開します。

    gcloud builds submit --tag REGION-docker.pkg.dev/PROJECT_ID/run-otel/sample-metrics-app

    ビルドが成功すると、ID、作成時間、イメージ名を含む SUCCESS メッセージが表示されます。イメージが Artifact Registry に保存されます。このイメージは必要に応じて再利用できます。

  2. Collector コンテナをビルドして、Artifact Registry に公開します。

    gcloud builds submit collector --tag REGION-docker.pkg.dev/PROJECT_ID/run-otel/otel-collector-metrics

    ビルドが成功すると、ID、作成時間、イメージ名を含む SUCCESS メッセージが表示されます。イメージが Artifact Registry に保存されます。このイメージは必要に応じて再利用できます。

  3. アプリケーションをデプロイします。

    YAML

    1. 次の内容の新しいファイルを service.yaml という名前で作成します。

      apiVersion: serving.knative.dev/v1
kind: Service
metadata:
  name: SERVICE-NAME
  annotations:
    run.googleapis.com/launch-stage: BETA
spec:
  template:
    metadata:
      annotations:
        run.googleapis.com/container-dependencies: "{app:[collector]}"
    spec:
      containers:
      - image: REGION-docker.pkg.dev/PROJECT_ID/run-otel/sample-metrics-app
        name: app
        ports:
        - containerPort: CONTAINER_PORT
        env:
        - name: "OTEL_EXPORTER_OTLP_ENDPOINT"
          value: "http://localhost:4317"
      - image: REGION-docker.pkg.dev/PROJECT_ID/run-otel/otel-collector-metrics
        name: collector
        startupProbe:
          httpGet:
            path: /
            port: 13133
    2. 次のように置き換えます。

  4. 次のコマンドを使用して新しいサービスを作成します。

    gcloud run services replace service.yaml

    このコマンドはサービスの URL を返します。この URL を使用して、試してみるのサンプル アプリケーションをお試しください。

試してみる

コードを配布するの gcloud run コマンドの URL を使用してサービスに接続し、サンプル指標を生成します。（このコマンドを複数回実行して、より興味深いデータを生成できます）。

curl -H \
"Authorization: Bearer $(gcloud auth print-identity-token)" \
SERVICE_URL

SERVICE_URL は、サービスの URL に置き換えます。

次に、 Google Cloud コンソールの [Cloud Monitoring] セクションで Metrics Explorer に移動し、sidecar_sample_counter_total 指標を選択します。

Metrics Explorer の UI に表示されたカスタム指標

PromQL を使用して指標をクエリすることもできます。たとえば、次のクエリは、Cloud Run インスタンス ID に基づいて指標をフィルタします。

sidecar_sample_counter_total{instance="INSTANCE_ID"}

INSTANCE_ID は、サービスの任意のインスタンス ID に置き換えます（インスタンス ログまたはメタデータ サーバーから使用可能）。

このクエリにより、次のようなグラフが生成されます。

PromQL によってクエリされるカスタム指標