マイクロサービス オブザーバビリティを使用して 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 ユーザーは無料トライアルをご利用いただける場合があります。

このドキュメントに記載されているタスクの完了後、作成したリソースを削除すると、それ以上の請求は発生しません。詳細については、クリーンアップをご覧ください。

始める前に

コンソール

1. 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.

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

   Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

   Go to project selector

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

4. Enable the Compute Engine, and Microservices API APIs.

   Enable the APIs

5. Create a service account:

   1. In the Google Cloud console, go to the Create service account page.

      Go to Create service account
   2. Select your project.

   3. 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.

   4. Click Create and continue.

   5. 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. In production environments, do not grant the Owner, Editor, or Viewer roles. Instead, grant a predefined role or custom role that meets your needs.
   6. Click Continue.

   7. 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.

   8. Click Done to finish creating the service account.

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

   Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

   Go to project selector

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

8. Enable the Compute Engine, and Microservices API APIs.

   Enable the APIs

9. Create a service account:

   1. In the Google Cloud console, go to the Create service account page.

      Go to Create service account
   2. Select your project.

   3. 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.

   4. Click Create and continue.

   5. 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. In production environments, do not grant the Owner, Editor, or Viewer roles. Instead, grant a predefined role or custom role that meets your needs.
   6. Click Continue.

   7. 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.

   8. Click Done to finish creating the service account.

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

CLI

1. 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.
2. Install the Google Cloud CLI.

3. To initialize the gcloud CLI, run the following command:

   gcloud init

4. Create or select a Google Cloud project.

   Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the 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.

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

6. Enable the Compute Engine, and Microservices API APIs:

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

7. Set up authentication:

   1. Create the service account:

      gcloud iam service-accounts create SERVICE_ACCOUNT_NAME

      Replace SERVICE_ACCOUNT_NAME with a name for the service account.

   2. 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. In production environments, do not grant the Owner, Editor, or Viewer roles. Instead, grant a predefined role or custom role that meets your needs.

   3. 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
8. Install the Google Cloud CLI.

9. To initialize the gcloud CLI, run the following command:

   gcloud init

10. Create or select a Google Cloud project.

    Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the 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.

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

12. Enable the Compute Engine, and Microservices API APIs:

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

13. Set up authentication:

    1. Create the service account:

       gcloud iam service-accounts create SERVICE_ACCOUNT_NAME

       Replace SERVICE_ACCOUNT_NAME with a name for the service account.

    2. 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. In production environments, do not grant the Owner, Editor, or Viewer roles. Instead, grant a predefined role or custom role that meets your needs.

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

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

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

1. 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
   

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

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

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

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

C++

1. 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

1. 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
   

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

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

Java

1. VM インスタンスに接続したら、Java 8 以降がインストールされていることを確認します。

   sudo apt update
   sudo apt upgrade
   sudo apt install git
   sudo apt-get install -y openjdk-11-jdk-headless
   

2. 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 オブジェクトを追加して、値を {} に設定します。

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

トレースを有効にする

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

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

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

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

ロギングを有効にする

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

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

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

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

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

C++

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

1. オブザーバビリティのサポートは、Bazel ビルドシステムでのみ使用できます。ターゲット grpcpp_gcp_observability を依存関係として追加します。

2. マイクロサービス オブザーバビリティを有効にするには、追加の依存関係（オブザーバビリティ モジュール）が必要です。また、既存の 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

1. マイクロサービス オブザーバビリティ プラグインは、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 にあります。

1. 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++

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

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

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

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

Go

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

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

   export GRPC_GCP_OBSERVABILITY_CONFIG_FILE=./server/serverConfig.json
   

3. サーバー アプリケーション shell go run ./server/main.go を実行します。

Java

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

クライアントを実行する

C++

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

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

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

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

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

Go

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

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

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

Java

1. サンプル ディレクトリで README ファイルを開き、ファイルの指示に従います。
2. 別のターミナル ウィンドウを開くよう指示された場合は、次のコマンドを実行します。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

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

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

   gcloud compute instances delete INSTANCE_NAME

次のステップ

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