通过微服务可观测性在 Google Cloud 上设置 gRPC 应用

---

借助微服务可观测性工具，您可以对应用进行插桩处理，以在 Cloud Monitoring、Cloud Logging 和 Cloud Trace 中从部署在 Google Cloud 和其他位置的 gRPC 工作负载收集和呈现遥测数据。微服务可观测性适用于通过启用 Microservices API 获得 Monitoring、Logging 和 Trace 的访问权限的任何部署。

在本教程中，您将了解如何使用 Compute Engine 在 Google Cloud 上构建简单的 gRPC 应用以利用微服务可观测性功能、通过微服务可观测性对应用进行插桩处理以及在 Monitoring 和 Logging 上进行实时查看。

目标

概括来讲，您需要执行以下步骤。

• 作为服务开发者，您可以：

  • 使用您选择的语言（C++、Go 或 Java）创建 gRPC 应用。
  • 在您的应用中选择启用并控制微服务可观测性插件。
  • 在 Compute Engine 虚拟机上部署应用。

• 作为服务运营商，您可以通过多种方式使用收集的数据：

  • 通过 Trace 查看跟踪记录。
  • 在名为微服务 (gRPC) Monitoring 的监控信息中心上查看指标。
  • 在 Metrics Explorer 上查看指标。
  • 在 Logs 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.
   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.
   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. 了解两个支持的环境变量，决定要使用的环境变量，并确定环境变量所需的值。

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.

   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.

    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. 了解两个支持的环境变量，决定要使用的环境变量，并确定环境变量所需的值。

创建并连接到 Compute Engine 虚拟机

使用以下说明创建并连接到 Compute Engine 虚拟机实例。在虚拟机上部署应用，然后通过微服务可观测性对应用进行插桩处理。

1. 创建虚拟机实例：

   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. 连接到虚拟机实例：

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

将应用部署到 Compute Engine 虚拟机

您可以将所选应用部署到您在上一步中创建的 Compute Engine 虚拟机，然后跳过此步骤，也可以使用示例继续按照您的首选语言的说明操作。

C++

1. 连接到虚拟机实例后，请运行以下命令。

   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. 连接到虚拟机实例后，请确保您已安装 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，以随机跟踪 50% 的 RPC。

如果您计划跨服务启用跟踪，请确保服务支持将从上游（或自行启动）接收的跟踪上下文传播到下游。

如需详细了解跟踪，请参阅跟踪记录定义。

启用日志记录

如需启用日志记录，请执行以下操作：

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 构建工具部分的构建代码段中，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() 具有线程安全性，并且必须只调用一次。它会返回一个 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. 创建与虚拟机的 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. 创建与虚拟机的 SSH 会话。

2. 导出环境变量。按照上文所定义的步骤创建 server_config.json。

   export GRPC_GCP_OBSERVABILITY_CONFIG_FILE=./server/serverConfig.json
   

3. 运行服务器应用 shell go run ./server/main.go

Java

1. 在示例目录中，打开自述文件并按照该文件中的说明操作。
2. 当说明提示您打开另一个终端窗口时，请发出以下命令：shell gcloud compute ssh --project=$PROJECT_ID grpc-observability-vm

运行客户端

C++

1. 创建与虚拟机的另一个 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. 创建与虚拟机的另一个 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. 在示例目录中，打开自述文件并按照该文件中的说明操作。
2. 当说明提示您打开另一个终端窗口时，请发出以下命令：shell gcloud compute ssh --project=$PROJECT_ID grpc-observability-vm

清理

为避免因本教程中使用的资源导致您的 Google Cloud 账号产生费用，请删除包含这些资源的项目，或者保留项目但删除各个资源。

删除项目

注意：删除项目会产生以下影响：

• 项目中的所有内容都会被删除。如果您将现有项目用于本文档中的任务，则删除该项目后，还将删除您已在该项目中完成的任何其他工作。
• 自定义项目 ID 丢失。创建此项目时，您可能创建了要在将来使用的自定义项目 ID。要保留使用该项目 ID 的网址（例如 appspot.com 网址），请删除项目内的所选资源，而不是删除整个项目。

如果您打算探索多个架构、教程或快速入门，则重复使用项目可以帮助您避免超出项目配额限制。

Delete a Google Cloud project:

gcloud projects delete PROJECT_ID

逐个删除资源

1. 删除实例：

   gcloud compute instances delete INSTANCE_NAME

后续步骤

• 如需详细了解配置数据、跟踪记录定义、指标定义和日志定义，请参阅微服务可观测性参考文档。
• 如需了解如何查看日志、跟踪记录和指标，请参阅查看跟踪记录、指标和日志条目