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

このチュートリアルでは、OpenTelemetry サイドカーを使用して、カスタム OTLP 指標を Google Cloud Managed Service for Prometheus に報告する Cloud Run サービスの作成、デプロイ、呼び出しを行う方法について説明します。

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

目標

OpenTelemetry サイドカーを使用して、Cloud Run にサービスを作成、ビルド、デプロイする。
カスタム指標を生成し、Google Cloud Managed Service for Prometheus に報告する。

費用

このドキュメントでは、Google Cloud の次の課金対象のコンポーネントを使用します。

料金計算ツールを使うと、予想使用量に基づいて費用の見積もりを生成できます。新しい Google Cloud ユーザーは無料トライアルをご利用いただける場合があります。

始める前に

Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Go to project selector

Make sure that billing is enabled for your Google Cloud project.

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Go to project selector

Make sure that billing is enabled for your Google Cloud project.

Enable the Cloud Run, Cloud Monitoring, Artifact Registry, and Cloud Build APIs.
Enable the APIs

gcloud CLI をインストールして初期化します。
gcloud components update で Google Cloud CLI を更新します。

必要なロール

チュートリアルを完了するために必要な権限を取得するには、プロジェクトに対して次の IAM ロールを付与するよう管理者に依頼してください。

Cloud Build 編集者（roles/cloudbuild.builds.editor）
Cloud Run 管理者（roles/run.admin）
サービスアカウントの作成（roles/iam.serviceAccountCreator）
プロジェクト IAM 管理者（roles/resourcemanager.projectIamAdmin）
モニタリング指標の書き込み（roles/monitoring.metricWriter）
サービスアカウントユーザー（roles/iam.serviceAccountUser）
Service Usage ユーザー（roles/serviceusage.serviceUsageConsumer）
ストレージ管理者（roles/storage.admin）

ロールの付与については、プロジェクト、フォルダ、組織へのアクセスを管理するをご覧ください。

必要な権限は、カスタムロールや他の事前定義ロールから取得することもできます。

また、Cloud Run サービス ID にはモニタリング指標の書き込み（roles/monitoring.metricWriter）ロールが必要です。Compute Engine のデフォルトのサービスアカウントには、デフォルトでこのロールが付与されていますが、権限を変更したり、別のサービスアカウントを使用している場合は、このロールの追加が必要になる可能性があります。

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

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

デフォルトプロジェクトを設定します。
```
gcloud config set project PROJECT_ID
```
PROJECT_ID は、このチュートリアルで作成したプロジェクトの名前に置き換えます。
選択したリージョン向けに 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（大阪）
europe-north1（フィンランド）低 CO₂
europe-southwest1（マドリッド）低 CO₂
europe-west1（ベルギー）低 CO₂
europe-west4（オランダ）低 CO₂
europe-west8（ミラノ）
europe-west9（パリ）低 CO₂
me-west1（テルアビブ）
us-central1（アイオワ）低 CO₂
us-east1（サウスカロライナ）
us-east4（北バージニア）
us-east5（コロンバス）
us-south1（ダラス）低 CO₂
us-west1（オレゴン）低 CO₂

ティア 2 料金を適用

africa-south1（ヨハネスブルグ）
asia-east2（香港）
asia-northeast3（ソウル、韓国）
asia-southeast1（シンガポール）
asia-southeast2 （ジャカルタ）
asia-south1（ムンバイ、インド）
asia-south2（デリー、インド）
australia-southeast1（シドニー）
australia-southeast2（メルボルン）
europe-central2（ワルシャワ、ポーランド）
europe-west10（ベルリン）低 CO₂
europe-west12（トリノ）
europe-west2（ロンドン、イギリス）低 CO₂
europe-west3（フランクフルト、ドイツ）低 CO₂
europe-west6（チューリッヒ、スイス）低 CO₂
me-central1（ドーハ）
me-central2（ダンマーム）
northamerica-northeast1（モントリオール）低 CO₂
northamerica-northeast2（トロント）低 CO₂
southamerica-east1（サンパウロ、ブラジル）低 CO₂
southamerica-west1（サンティアゴ、チリ）低 CO₂
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 のリージョンに置き換えます。

コードサンプルの取得

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

ローカルマシンにサンプルアプリのリポジトリのクローンを作成します。
Go
```
git clone https://github.com/GoogleCloudPlatform/golang-samples.git
```
または、zip 形式のサンプルをダウンロードし、ファイルを抽出してもかまいません。
Cloud Run のサンプルコードが含まれているディレクトリに移動します。
Go
```
cd golang-samples/run/custom-metrics/
```

コードの確認

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

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

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 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(
			semconv.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.21 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"]

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

OpenTelemetry 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:

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

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

FROM otel/opentelemetry-collector-contrib:0.101.0

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

コードの配布

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

コードを配布するには:

サンプルサービスコンテナをビルドし、Artifact Registry に公開します。
```
gcloud builds submit --tag REGION-docker.pkg.dev/PROJECT_ID/run-otel/sample-metrics-app
```
ビルドが成功すると、ID、作成時間、イメージ名を含む SUCCESS メッセージが表示されます。イメージが Artifact Registry に保存されます。このイメージは必要に応じて再利用できます。
Collector コンテナをビルドして、Artifact Registry に公開します。
```
gcloud builds submit collector --tag REGION-docker.pkg.dev/PROJECT_ID/run-otel/otel-collector-metrics
```
ビルドが成功すると、ID、作成時間、イメージ名を含む SUCCESS メッセージが表示されます。イメージが Artifact Registry に保存されます。このイメージは必要に応じて再利用できます。

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

YAML

次の内容の新しいファイルを 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

次のように置き換えます。
- CONTAINER_PORT は、サービスの Ingress コンテナがリッスンするポートに置き換えます。デフォルトは 8080 です。
- SERVICE-NAME は、サービスの任意の名前（custom-metrics-sample-service など）に置き換えます。

次のコマンドを使用して新しいサービスを作成します。
```
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 指標を選択します。

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

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

sidecar_sample_counter{instance="INSTANCE_ID"}

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

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

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

クリーンアップ

このチュートリアル用に新規プロジェクトを作成した場合は、そのプロジェクトを削除します。既存のプロジェクトを使用し、このチュートリアルで変更を加えずに残す場合は、チュートリアル用に作成したリソースを削除します。

プロジェクトを削除する

課金されないようにする最も簡単な方法は、チュートリアル用に作成したプロジェクトを削除することです。

プロジェクトを削除するには:

注意: プロジェクトを削除すると、次のような影響があります。

プロジェクト内のすべてのものが削除されます。このドキュメントのタスクで既存のプロジェクトを使用した場合、それを削除すると、そのプロジェクトで行った他の作業もすべて削除されます。
カスタムプロジェクト ID が失われます。このプロジェクトを作成したときに、将来使用するカスタムプロジェクト ID を作成した可能性があります。そのプロジェクト ID を使用した URL（たとえば、appspot.com）を保持するには、プロジェクト全体ではなくプロジェクト内の選択したリソースだけを削除します。

複数のアーキテクチャ、チュートリアル、クイックスタートを実施する予定がある場合は、プロジェクトを再利用すると、プロジェクトの割り当て上限を超えないようにすることができます。

In the Google Cloud console, go to the Manage resources page.
Go to Manage resources
In the project list, select the project that you want to delete, and then click Delete.
In the dialog, type the project ID, and then click Shut down to delete the project.

チュートリアルリソースを削除する

このチュートリアルでデプロイした Cloud Run サービスを削除します。
```
gcloud run services delete SERVICE-NAME
```
SERVICE-NAME は、選択したサービス名です。

Cloud Run サービスは Google Cloud コンソールから削除することもできます。
チュートリアルの設定時に追加した gcloud のデフォルトリージョン構成を削除します。
```
 gcloud config unset run/region
```
プロジェクト構成を削除します。
```
 gcloud config unset project
```
このチュートリアルで作成した他の Google Cloud リソースを削除します。
- Artifact Registry Docker リポジトリを削除する

次のステップ

トレースとログの例を含むその他の例は、GitHub で入手できます。

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

目標

費用

始める前に

必要なロール

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

Cloud Run のロケーション

ティア 1 料金を適用

ティア 2 料金を適用

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

コードサンプルの取得

Go

Go

コードの確認

コードの配布

YAML

試してみる

クリーンアップ

プロジェクトを削除する

チュートリアル リソースを削除する

次のステップ

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

チュートリアルリソースを削除する