マイクロサービスオブザーバビリティを使用して Google Cloud で gRPC アプリケーションを設定する

マイクロサービスのオブザーバビリティツールを使用すると、アプリケーションを計測して、Google Cloud やその他の場所にデプロイされた gRPC ワークロードからテレメトリーデータを収集し、Cloud Monitoring、Cloud Logging、Cloud Trace で表示できるようになります。マイクロサービスオブザーバビリティは、Microservices API を有効にすることで、Monitoring、Logging、Trace へのアクセスが許可されている Deployment に対応しています。

このチュートリアルでは、Compute Engine を使用して Google Cloud でシンプルな gRPC アプリケーションを構築することでマイクロサービスオブザーバビリティ機能を使用し、マイクロサービスオブザーバビリティでアプリケーションを計測して Monitoring と Logging でライブ表示する方法を学習します。

目標

大まかな流れは次のとおりです。

サービスデベロッパーとして次のことができます。
- 任意の言語（C++、Go、Java）で gRPC アプリケーションを作成する。
- アプリケーションをオプトインし、マイクロサービスオブザーバビリティプラグインを制御する。
- アプリケーションを Compute Engine VM にデプロイする。
サービスオペレータとして、収集したデータをさまざまな方法で使用できます。
- Trace でトレースを表示する。
- マイクロサービス（gRPC）モニタリングと呼ばれるモニタリングダッシュボードで指標を表示する。
- Metrics Explorer で指標を表示する。
- ログエクスプローラでログエントリを検査する。

費用

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

Compute Engine

料金計算ツールを使うと、予想使用量に基づいて費用の見積もりを生成できます。新しい 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.

Enable the Compute Engine, and Microservices API APIs.

Enable the APIs

Create a service account:

In the Google Cloud console, go to the Create service account page.
Go to Create service account
Select your project.
In the Service account name field, enter a name. The Google Cloud console fills in the Service account ID field based on this name.

In the Service account description field, enter a description. For example, Service account for quickstart.
Click Create and continue.
Grant the following roles to the service account: Logging > Logs Viewer > Logs Writer, Monitoring > Monitoring Editor > Metrics Writer, Trace > Trace Admin > Trace Agent.

To grant a role, find the Select a role list, then select the role.

To grant additional roles, click Add another role and add each additional role.

Note: The Role field affects which resources the service account can access in your project. You can revoke these roles or grant additional roles later.
Click Continue.
In the Service account users role field, enter the identifier for the principal that will attach the service account to other resources, such as Compute Engine instances.

This is typically the email address for a Google Account.
Click Done to finish creating the service account.

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 Compute Engine, and Microservices API APIs.

Enable the APIs

Create a service account:

In the Google Cloud console, go to the Create service account page.
Go to Create service account
Select your project.
In the Service account name field, enter a name. The Google Cloud console fills in the Service account ID field based on this name.

In the Service account description field, enter a description. For example, Service account for quickstart.
Click Create and continue.
Grant the following roles to the service account: Logging > Logs Viewer > Logs Writer, Monitoring > Monitoring Editor > Metrics Writer, Trace > Trace Admin > Trace Agent.

To grant a role, find the Select a role list, then select the role.

To grant additional roles, click Add another role and add each additional role.

Note: The Role field affects which resources the service account can access in your project. You can revoke these roles or grant additional roles later.
Click Continue.
In the Service account users role field, enter the identifier for the principal that will attach the service account to other resources, such as Compute Engine instances.

This is typically the email address for a Google Account.
Click Done to finish creating the service account.

マイクロサービスオブザーバビリティの概要を確認します。
2 つのサポートされている環境変数を確認し、使用する環境変数を特定して、環境変数に必要な値を決定します。

CLI

Install the Google Cloud CLI.

To initialize the gcloud CLI, run the following command:

gcloud init

Create or select a Google Cloud project.

Create a Google Cloud project:
```
gcloud projects create PROJECT_ID
```
Replace PROJECT_ID with a name for the Google Cloud project you are creating.
Select the Google Cloud project that you created:
```
gcloud config set project PROJECT_ID
```
Replace PROJECT_ID with your Google Cloud project name.

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

Enable the Compute Engine, and Microservices API APIs:

gcloud services enable compute.googleapis.com microservices.googleapis.com

Set up authentication:

Create the service account:
```
gcloud iam service-accounts create SERVICE_ACCOUNT_NAME
```
Replace SERVICE_ACCOUNT_NAME with a name for the service account.
Grant roles to the service account. Run the following command once for each of the following IAM roles: roles/logging.logWriter, roles/monitoring.metricWriter, roles/cloudtrace.agent:
```
gcloud projects add-iam-policy-binding PROJECT_ID --member="serviceAccount:SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com" --role=ROLE
```
Replace the following:
- SERVICE_ACCOUNT_NAME: the name of the service account
- PROJECT_ID: the project ID where you created the service account
- ROLE: the role to grant
Note: The --role flag affects which resources the service account can access in your project. You can revoke these roles or grant additional roles later.
Grant the required role to the principal that will attach the service account to other resources.
```
gcloud iam service-accounts add-iam-policy-binding SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com --member="user:USER_EMAIL" --role=roles/iam.serviceAccountUser
```
Replace the following:
- SERVICE_ACCOUNT_NAME: the name of the service account
- PROJECT_ID: the project ID where you created the service account
- USER_EMAIL: the email address for a Google Account

Install the Google Cloud CLI.

To initialize the gcloud CLI, run the following command:

gcloud init

Create or select a Google Cloud project.

Create a Google Cloud project:
```
gcloud projects create PROJECT_ID
```
Replace PROJECT_ID with a name for the Google Cloud project you are creating.
Select the Google Cloud project that you created:
```
gcloud config set project PROJECT_ID
```
Replace PROJECT_ID with your Google Cloud project name.

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

Enable the Compute Engine, and Microservices API APIs:

gcloud services enable compute.googleapis.com microservices.googleapis.com

Set up authentication:

Create the service account:
```
gcloud iam service-accounts create SERVICE_ACCOUNT_NAME
```
Replace SERVICE_ACCOUNT_NAME with a name for the service account.
Grant roles to the service account. Run the following command once for each of the following IAM roles: roles/logging.logWriter, roles/monitoring.metricWriter, roles/cloudtrace.agent:
```
gcloud projects add-iam-policy-binding PROJECT_ID --member="serviceAccount:SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com" --role=ROLE
```
Replace the following:
- SERVICE_ACCOUNT_NAME: the name of the service account
- PROJECT_ID: the project ID where you created the service account
- ROLE: the role to grant
Note: The --role flag affects which resources the service account can access in your project. You can revoke these roles or grant additional roles later.
Grant the required role to the principal that will attach the service account to other resources.
```
gcloud iam service-accounts add-iam-policy-binding SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com --member="user:USER_EMAIL" --role=roles/iam.serviceAccountUser
```
Replace the following:
- SERVICE_ACCOUNT_NAME: the name of the service account
- PROJECT_ID: the project ID where you created the service account
- USER_EMAIL: the email address for a Google Account

マイクロサービスオブザーバビリティの概要を確認します。
2 つのサポートされている環境変数を確認し、使用する環境変数を特定して、環境変数に必要な値を決定します。

Compute Engine VM を作成して接続する

Compute Engine VM インスタンスを作成して接続する手順は次のとおりです。VM でアプリケーションをデプロイし、マイクロサービスオブザーバビリティを使用してアプリケーションを計測します。

VM インスタンスを作成します。

gcloud compute instances create grpc-observability-vm \
  --image-family=debian-11 \
  --image-project=debian-cloud \
  --service-account=SERVICE_ACCOUNT_NAME@$PROJECT_ID.iam.gserviceaccount.com

VM インスタンスに接続します:

gcloud compute ssh --project=$PROJECT_ID grpc-observability-vm

アプリケーションを Compute Engine VM にデプロイする

前のステップで作成した Compute Engine VM に任意のアプリケーションをデプロイしてこのステップをスキップするか、サンプルを使用して任意の言語で手順を続行できます。

C++

VM インスタンスに接続したら、次のコマンドを実行します。

sudo apt-get update -y
sudo apt-get install -y git build-essential clang
git clone -b v1.54.0 https://github.com/grpc/grpc.git --depth=1

Go

Go がインストールされていることを確認します。

sudo apt-get install -y git
sudo apt install wget
wget https://go.dev/dl/go1.20.2.linux-amd64.tar.gz
sudo rm -rf /usr/local/go && sudo tar -C /usr/local -xzf \
go1.20.2.linux-amd64.tar.gz
export PATH=$PATH:/usr/local/go/bin

gRPC-Go サンプルのクローンを作成します。

git clone https://github.com/grpc/grpc-go.git
cd grpc-go/
git checkout -b run-observability-example
875c97a94dca8093bf01ff2fef490fbdd576373d

Java

VM インスタンスに接続したら、Java 8 以降がインストールされていることを確認します。
```
sudo apt update
sudo apt upgrade
sudo apt install git
sudo apt-get install -y openjdk-11-jdk-headless
```

grpc-java リポジトリのクローンを作成します。

export EXAMPLES_VERSION=v1.54.1
git clone -b $EXAMPLES_VERSION --single-branch --depth=1 \
https://github.com/grpc/grpc-java.git

gRPC Google Cloud Observability 構成ファイルを作成する

サーバーとクライアントの両方でマイクロサービスオブザーバビリティを有効にするには、個別の gRPC Google Cloud Observability 構成ファイルが必要です。このファイルの場所は、後のステップで GRPC_GCP_OBSERVABILITY_CONFIG_FILE としてエクスポートされます。次の手順で、構成ファイルでさまざまなパラメータを設定します。

例 `GRPC_GCP_OBSERVABILITY_CONFIG_FILE`

{
  "project_id": "your-project-here",
  "cloud_logging": {
    "client_rpc_events": [
    {
      "methods": ["google.pubsub.v1.Subscriber/Acknowledge", "google.pubsub.v1.Publisher/CreateTopic"],
      "exclude": true,
    },
    {
      "methods": ["google.pubsub.v1.Subscriber/*", "google.pubsub.v1.Publisher/*"],
      "max_metadata_bytes": 4096,
      "max_message_bytes": 4096,
    }],
    "server_rpc_events": [{
      "methods": ["*"],
      "max_metadata_bytes": 4096,
      "max_message_bytes": 4096
    }],
  },
  "cloud_monitoring": {},
  "cloud_trace": {
    "sampling_rate": 0.5,
  }
  "labels": {
    "SOURCE_VERSION": "J2e1Cf",
    "SERVICE_NAME": "payment-service-1Cf",
    "DATA_CENTER": "us-west1-a"
  }
}

以下の各セクションでは、個別のコンポーネントの構成でデータ収集を有効にする手順について説明します。このチュートリアルで gRPC の例を使用した場合は、この構成をそのまま使用できます（your-project-here を更新した後）。または、アプリケーションのテンプレートとして使用することもできます。環境変数の構成情報を示す例もご覧ください。

指標を有効にする

指標を有効にするには、構成に cloud_monitoring オブジェクトを追加して、値を {} に設定します。

指標の詳細については、指標の定義をご覧ください。

トレースを有効にする

トレースを有効にするには、次の操作を行います。

構成に cloud_trace オブジェクトを追加します。
cloud_trace.sampling_rate を 0.5 に設定して、RPC の 50% をランダムにトレースします。

サービス間のトレースを有効にする場合は、アップストリームから受信した（または単独で開始した）トレースコンテキストをダウンストリームに伝播することをサービスでサポートする必要があります。

トレースの詳細については、トレースの定義をご覧ください。

ロギングを有効にする

ロギングを有効にするには、次の操作を行います。

構成に cloud_logging オブジェクトを追加します。
client_rpc_events と server_rpc_events のいずれか、または両方にパターンを追加して、トランスポートレベルのイベントログを生成する一連のサービスとメソッドを指定します。また、ヘッダーとメッセージに記録するバイト数も指定します。

ロギングの詳細については、ログレコードの定義をご覧ください。

オブザーバビリティプラグイン用にアプリケーションを計測する

アプリケーションを計測してマイクロサービスオブザーバビリティプラグインを使用できるようにするには、ご使用の言語で次の手順を行います。

C++

gRPC C++ v1.54 では、マイクロサービスオブザーバビリティで C++ を使用できます。サンプルリポジトリは GitHub にあります。

オブザーバビリティのサポートは、Bazel ビルドシステムでのみ使用できます。ターゲット grpcpp_gcp_observability を依存関係として追加します。
マイクロサービスオブザーバビリティを有効にするには、追加の依存関係（オブザーバビリティモジュール）が必要です。また、既存の gRPC クライアント、サーバー、またはその両方で次のコード変更を行う必要があります。
```
#include <grpcpp/ext/gcp_observability.h>

int main(int argc, char** argv) {
  auto observability = grpc::GcpObservability::Init();
  assert(observability.ok());
  …
  // Observability data flushed when object goes out of scope
}
```
gRPC オペレーション（チャネル、サーバー、認証情報の作成など）を行う前に、次の呼び出しを行います。
```
grpc::GcpObservability::Init();
```
absl::StatusOr<GcpObservability> が返されます。これは保存する必要があります。ステータスは、オブザーバビリティが正常に初期化されたかどうかを判断するのに役立ちます。付属の GcpObservability オブジェクトはオブザーバビリティの存続期間を制御します。オブザーバビリティデータは対象範囲外になると、自動的に閉じてフラッシュします。

Go

マイクロサービスオブザーバビリティプラグインは、gRPC Go バージョン v1.54.0 以降でサポートされています。サンプルリポジトリは GitHub にあります。

Go モジュールでマイクロサービスオブザーバビリティを有効にするには、オブザーバビリティモジュールと次のコードが必要です。

import "google.golang.org/grpc/gcp/observability"

func main() {
  ctx, cancel := context.WithTimeout(context.Background(), time.Second)
  defer cancel()
  if err := observability.Start(ctx); err != nil {
    log.Warning("Unable to start gRPC observability:", err)
  }
  defer observability.End()
  …
}

observability.Start 呼び出しは、環境変数から構成を解析し、それに応じてエクスポータを作成します。さらに、呼び出し後に作成されたクライアント接続とサーバーに収集ロジックを挿入します。遅延 observability.End 呼び出しにより、リソースがクリーンアップされ、アプリケーションを閉じる前にバッファ内のデータがフラッシュされます。

アプリケーションコードを更新したら、次のコマンドを実行して go.mod ファイルを更新します。

go mod tidy

Java

Java アプリケーションでマイクロサービスオブザーバビリティを使用するには、ビルドを変更して grpc-gcp-observability アーティファクトを追加します。gRPC バージョン 1.54.1 以降を使用します。

[Gradle] セクションと [Maven build tool] セクションのビルドスニペットで、grpcVersion が値 1.54.1 に設定されています。

サンプルリポジトリは GitHub にあります。

Java アプリケーションをマイクロサービスオブザーバビリティで正しく計測するには、次のコードを main() に追加します。

...
import io.grpc.gcp.observability.GcpObservability;
...

// Main application class
...

public static void main(String[] args) {
...
  // call GcpObservability.grpcInit() to initialize & get observability
  GcpObservability observability = GcpObservability.grpcInit();

...
  // call close() on the observability instance to shutdown observability
  observability.close();
...
}

gRPC チャネルまたはサーバーを作成する前に、GcpObservability.grpcInit() を呼び出す必要があります。GcpObservability.grpcInit() 関数は、マイクロサービスオブザーバビリティ構成を読み取り、読み取った構成を使用して、作成された各チャネルとサーバーのロギング、指標、トレース機能に必要なグローバルインターセプターとトレーサーを設定します。GcpObservability.grpcInit() はスレッドセーフで、1 回だけ呼び出す必要があります。GcpObservability のインスタンスを返します。これは、close() の呼び出しを後で行うために保存する必要があります。

GcpObservability.close() はリソースの割り当てを解除します。それ以降に作成されたチャネルまたはサーバーはロギングを行いません。

GcpObservability は java.lang.AutoCloseable を実装します。これは、次のように try-with-resource を使用すると自動的に終了します。

...
import io.grpc.gcp.observability.GcpObservability;
...

// Main application class
...

public static void main(String[] args) {
...
  // call GcpObservability.grpcInit() to initialize & get observability
  try (GcpObservability observability = GcpObservability.grpcInit()) {

...
  } // observability.close() called implicitly
...
}

Gradle ビルドツールを使用する

Gradle ビルドツールを使用する場合は、次のものを含めます。

def grpcVersion = '1.54.1'

...

dependencies {
...
implementation "io.grpc:grpc-gcp-observability:${grpcVersion}"
...
}

Maven ビルドツール（pom.xml）を使用する

Maven ビルドツールを使用する場合は、次のものを含めます。

<properties>
...
<grpc.version>1.54.1</grpc.version>
...
</properties>

...

<dependencies>
...
<dependency>
<groupId>io.grpc</groupId>
<artifactId>grpc-gcp-observability</artifactId>
<version>${grpc.version}</version>
</dependency>
...
</dependencies>

アプリケーションの実行

このセクションの手順は、チュートリアルで gRPC の例を使用した場合のみ行ってください。run コマンドを変更して、アプリケーションバイナリをターゲットにできます。

サーバーを実行する

C++

VM への SSH セッションを作成します。

環境変数をエクスポートします。上記で定義した手順を使用して server_config.json を作成します。

  export GOOGLE_CLOUD_PROJECT=$PROJECT_ID
  export GRPC_GCP_OBSERVABILITY_CONFIG_FILE="$(pwd)/examples/cpp/gcp_observability/helloworld/server_config.json"

サーバーアプリケーション shell cd grpc tools/bazel run examples/cpp/gcp_observability/helloworld:greeter_server を実行します。

Go

VM への SSH セッションを作成します。
環境変数をエクスポートします。上記で定義した手順を使用して server_config.json を作成します。
```
export GRPC_GCP_OBSERVABILITY_CONFIG_FILE=./server/serverConfig.json
```
サーバーアプリケーション shell go run ./server/main.go を実行します。

Java

サンプルディレクトリで README ファイルを開き、ファイルの指示に従います。
別のターミナルウィンドウを開くよう指示された場合は、次のコマンドを実行します。shell gcloud compute ssh --project=$PROJECT_ID grpc-observability-vm

クライアントを実行する

C++

VM への別の SSH セッションを作成します。

環境変数をエクスポートします。上記で定義した手順に沿って client_config.json ファイルを作成します。

  export GOOGLE_CLOUD_PROJECT=$PROJECT_ID
  export GRPC_GCP_OBSERVABILITY_CONFIG_FILE="$(pwd)/examples/cpp/gcp_observability/helloworld/client_config.json"

クライアントアプリケーションを実行する

cd grpc
tools/bazel run examples/cpp/gcp_observability/helloworld:greeter_client

Go

VM への別の SSH セッションを作成します。
環境変数をエクスポートします。上記で定義した手順に沿って client_config.json ファイルを作成します。shell export GRPC_GCP_OBSERVABILITY_CONFIG_FILE=./client/clientConfig.json

クライアントアプリケーションを実行する

cd grpc-go/examples/features/observability
go run ./client/main.go

Java

サンプルディレクトリで README ファイルを開き、ファイルの指示に従います。
別のターミナルウィンドウを開くよう指示された場合は、次のコマンドを実行します。shell gcloud compute ssh --project=$PROJECT_ID grpc-observability-vm

クリーンアップ

このチュートリアルで使用したリソースについて、Google Cloud アカウントに課金されないようにするには、リソースを含むプロジェクトを削除するか、プロジェクトを維持して個々のリソースを削除します。

プロジェクトを削除する

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

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

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

Delete a Google Cloud project:

gcloud projects delete PROJECT_ID

リソースを個別に削除する

インスタンスを削除します。

gcloud compute instances delete INSTANCE_NAME

次のステップ

構成データ、トレース定義、指標定義、ログ定義の詳細については、マイクロサービスオブザーバビリティリファレンスをご覧ください。
ログ、トレース、指標の表示については、トレース、指標、ログエントリを表示するをご覧ください。

マイクロサービス オブザーバビリティを使用して Google Cloud で gRPC アプリケーションを設定する

目標

費用

始める前に

コンソール

CLI

Compute Engine VM を作成して接続する

アプリケーションを Compute Engine VM にデプロイする

C++

Go

Java

gRPC Google Cloud Observability 構成ファイルを作成する

例 GRPC_GCP_OBSERVABILITY_CONFIG_FILE

指標を有効にする

トレースを有効にする

ロギングを有効にする

オブザーバビリティ プラグイン用にアプリケーションを計測する

C++

Go

Java

Gradle ビルドツールを使用する

Maven ビルドツール（pom.xml）を使用する

アプリケーションの実行

サーバーを実行する

C++

Go

Java

クライアントを実行する

C++

Go

Java

クリーンアップ

プロジェクトを削除する

リソースを個別に削除する

次のステップ

マイクロサービスオブザーバビリティを使用して Google Cloud で gRPC アプリケーションを設定する

例 `GRPC_GCP_OBSERVABILITY_CONFIG_FILE`

オブザーバビリティプラグイン用にアプリケーションを計測する