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

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

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

创建并连接到 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