借助微服务可观测性工具，您可以对应用进行插桩处理，以在 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的以下收费组件：
如需根据您的预计使用量来估算费用，请使用价格计算器。
完成本文档中描述的任务后，您可以通过删除所创建的资源来避免继续计费。如需了解详情，请参阅清理。
准备工作
控制台
- 登录您的 Google Cloud 账号。如果您是 Google Cloud新手，请 创建一个账号来评估我们的产品在实际场景中的表现。新客户还可获享 $300 赠金，用于运行、测试和部署工作负载。
-
In the Google Cloud console, on the project selector page, select or create a Google Cloud project.
Roles required to select or create a project
- Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
-
Create a project: To create a project, you need the Project Creator role
(
roles/resourcemanager.projectCreator), which contains theresourcemanager.projects.createpermission. Learn how to grant roles.
-
Verify that billing is enabled for your Google Cloud project.
-
启用 Compute Engine 和 Microservices API。
启用 API 所需的角色
如需启用 API，您需要拥有 Service Usage Admin IAM 角色 (
roles/serviceusage.serviceUsageAdmin)，该角色包含serviceusage.services.enable权限。了解如何授予角色。 -
确保您拥有 Create Service Accounts IAM 角色 (
roles/iam.serviceAccountCreator) 和 Project IAM Admin 角色 (roles/resourcemanager.projectIamAdmin)。了解如何授予角色。 -
在 Google Cloud 控制台中，前往创建服务账号页面。
转到“创建服务账号” - 选择您的项目。
-
在服务账号名称字段中，输入一个名称。 Google Cloud 控制台会根据此名称填充服务账号 ID 字段。
在服务账号说明字段中，输入说明。例如，
Service account for quickstart。 - 点击创建并继续。
-
向服务账号授予以下角色：Logging > Logs Viewer > Logs Writer、Monitoring > Monitoring Editor > Metrics Writer、Trace > Trace Admin > Trace Agent。
如需授予角色，请找到选择角色列表，然后选择相应角色。
如需授予其他角色，请点击 添加其他角色，然后添加其他各个角色。
- 点击继续。
-
在服务账号用户角色字段中，输入将服务账号挂接到其他资源（例如 Compute Engine 实例）的正文的标识符。
这通常是 Google 账号的电子邮件地址。
-
点击完成以完成服务账号的创建过程。
-
In the Google Cloud console, on the project selector page, select or create a Google Cloud project.
Roles required to select or create a project
- Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
-
Create a project: To create a project, you need the Project Creator role
(
roles/resourcemanager.projectCreator), which contains theresourcemanager.projects.createpermission. Learn how to grant roles.
-
Verify that billing is enabled for your Google Cloud project.
-
启用 Compute Engine 和 Microservices API。
启用 API 所需的角色
如需启用 API，您需要拥有 Service Usage Admin IAM 角色 (
roles/serviceusage.serviceUsageAdmin)，该角色包含serviceusage.services.enable权限。了解如何授予角色。 -
确保您拥有 Create Service Accounts IAM 角色 (
roles/iam.serviceAccountCreator) 和 Project IAM Admin 角色 (roles/resourcemanager.projectIamAdmin)。了解如何授予角色。 -
在 Google Cloud 控制台中，前往创建服务账号页面。
转到“创建服务账号” - 选择您的项目。
-
在服务账号名称字段中，输入一个名称。 Google Cloud 控制台会根据此名称填充服务账号 ID 字段。
在服务账号说明字段中，输入说明。例如，
Service account for quickstart。 - 点击创建并继续。
-
向服务账号授予以下角色：Logging > Logs Viewer > Logs Writer、Monitoring > Monitoring Editor > Metrics Writer、Trace > Trace Admin > Trace Agent。
如需授予角色，请找到选择角色列表，然后选择相应角色。
如需授予其他角色，请点击 添加其他角色，然后添加其他各个角色。
- 点击继续。
-
在服务账号用户角色字段中，输入将服务账号挂接到其他资源（例如 Compute Engine 实例）的正文的标识符。
这通常是 Google 账号的电子邮件地址。
-
点击完成以完成服务账号的创建过程。
- 阅读微服务可观测性概览。
- 了解两个支持的环境变量，决定要使用的环境变量，并确定环境变量所需的值。
cli
- 登录您的 Google Cloud 账号。如果您是 Google Cloud新手，请 创建一个账号来评估我们的产品在实际场景中的表现。新客户还可获享 $300 赠金，用于运行、测试和部署工作负载。
-
安装 Google Cloud CLI。
-
如果您使用的是外部身份提供方 (IdP)，则必须先使用联合身份登录 gcloud CLI。
-
如需初始化 gcloud CLI，请运行以下命令：
gcloud init -
选择或创建项目所需的角色
- 选择项目：选择项目不需要特定的 IAM 角色，您可以选择已获授角色的任何项目。
-
创建项目：如需创建项目，您需要拥有 Project Creator 角色 (
roles/resourcemanager.projectCreator)，该角色包含resourcemanager.projects.create权限。了解如何授予角色。
-
创建 Google Cloud 项目：
gcloud projects create PROJECT_ID
将
PROJECT_ID替换为您要创建的 Google Cloud 项目的名称。 -
选择您创建的 Google Cloud 项目：
gcloud config set project PROJECT_ID
将
PROJECT_ID替换为您的 Google Cloud 项目名称。
启用 Compute Engine 和 Microservices API：
启用 API 所需的角色
如需启用 API，您需要拥有 Service Usage Admin IAM 角色 (
roles/serviceusage.serviceUsageAdmin)，该角色包含serviceusage.services.enable权限。了解如何授予角色。gcloud services enable compute.googleapis.com
microservices.googleapis.com -
设置身份验证：
-
确保您拥有 Create Service Accounts IAM 角色 (
roles/iam.serviceAccountCreator) 和 Project IAM Admin 角色 (roles/resourcemanager.projectIamAdmin)。了解如何授予角色。 -
创建服务账号：
gcloud iam service-accounts create SERVICE_ACCOUNT_NAME
将
SERVICE_ACCOUNT_NAME替换为服务账号的名称。 -
向服务账号授予角色。对以下每个 IAM 角色运行以下命令一次：
roles/logging.logWriter, roles/monitoring.metricWriter, roles/cloudtrace.agentgcloud projects add-iam-policy-binding PROJECT_ID --member="serviceAccount:SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com" --role=ROLE
请替换以下内容：
SERVICE_ACCOUNT_NAME：服务账号的名称PROJECT_ID：您在其中创建服务账号的项目的 IDROLE：要授予的角色
-
向将服务账号关联到其他资源的主账号授予所需角色。
gcloud iam service-accounts add-iam-policy-binding SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com --member="user:USER_EMAIL" --role=roles/iam.serviceAccountUser
请替换以下内容：
SERVICE_ACCOUNT_NAME：服务账号的名称PROJECT_ID：您在其中创建服务账号的项目的 IDUSER_EMAIL：Google 账号的电子邮件地址
-
确保您拥有 Create Service Accounts IAM 角色 (
-
安装 Google Cloud CLI。
-
如果您使用的是外部身份提供方 (IdP)，则必须先使用联合身份登录 gcloud CLI。
-
如需初始化 gcloud CLI，请运行以下命令：
gcloud init -
选择或创建项目所需的角色
- 选择项目：选择项目不需要特定的 IAM 角色，您可以选择已获授角色的任何项目。
-
创建项目：如需创建项目，您需要拥有 Project Creator 角色 (
roles/resourcemanager.projectCreator)，该角色包含resourcemanager.projects.create权限。了解如何授予角色。
-
创建 Google Cloud 项目：
gcloud projects create PROJECT_ID
将
PROJECT_ID替换为您要创建的 Google Cloud 项目的名称。 -
选择您创建的 Google Cloud 项目：
gcloud config set project PROJECT_ID
将
PROJECT_ID替换为您的 Google Cloud 项目名称。
启用 Compute Engine 和 Microservices API：
启用 API 所需的角色
如需启用 API，您需要拥有 Service Usage Admin IAM 角色 (
roles/serviceusage.serviceUsageAdmin)，该角色包含serviceusage.services.enable权限。了解如何授予角色。gcloud services enable compute.googleapis.com
microservices.googleapis.com -
设置身份验证：
-
确保您拥有 Create Service Accounts IAM 角色 (
roles/iam.serviceAccountCreator) 和 Project IAM Admin 角色 (roles/resourcemanager.projectIamAdmin)。了解如何授予角色。 -
创建服务账号：
gcloud iam service-accounts create SERVICE_ACCOUNT_NAME
将
SERVICE_ACCOUNT_NAME替换为服务账号的名称。 -
向服务账号授予角色。对以下每个 IAM 角色运行以下命令一次：
roles/logging.logWriter, roles/monitoring.metricWriter, roles/cloudtrace.agentgcloud projects add-iam-policy-binding PROJECT_ID --member="serviceAccount:SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com" --role=ROLE
请替换以下内容：
SERVICE_ACCOUNT_NAME：服务账号的名称PROJECT_ID：您在其中创建服务账号的项目的 IDROLE：要授予的角色
-
向将服务账号关联到其他资源的主账号授予所需角色。
gcloud iam service-accounts add-iam-policy-binding SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com --member="user:USER_EMAIL" --role=roles/iam.serviceAccountUser
请替换以下内容：
SERVICE_ACCOUNT_NAME：服务账号的名称PROJECT_ID：您在其中创建服务账号的项目的 IDUSER_EMAIL：Google 账号的电子邮件地址
-
确保您拥有 Create Service Accounts IAM 角色 (
- 阅读微服务可观测性概览。
- 了解两个支持的环境变量，决定要使用的环境变量，并确定环境变量所需的值。
创建并连接到 Compute Engine 虚拟机
使用以下说明创建并连接到 Compute Engine 虚拟机实例。在虚拟机上部署应用，然后通过微服务可观测性对应用进行插桩处理。
创建虚拟机实例：
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
连接到虚拟机实例：
gcloud compute ssh --project=$PROJECT_ID grpc-observability-vm
将应用部署到 Compute Engine 虚拟机
您可以将所选应用部署到您在上一步中创建的 Compute Engine 虚拟机，然后跳过此步骤，也可以使用示例继续按照您的首选语言的说明操作。
C++
连接到虚拟机实例后，请运行以下命令。
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
连接到虚拟机实例后，请确保您已安装 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，以随机跟踪 50% 的 RPC。
如果您计划跨服务启用跟踪，请确保服务支持将从上游（或自行启动）接收的跟踪上下文传播到下游。
如需详细了解跟踪，请参阅跟踪记录定义。
启用日志记录
如需启用日志记录，请执行以下操作：
- 将
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 构建工具部分的构建代码段中，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() 具有线程安全性，并且必须只调用一次。它会返回一个 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++
- 创建与虚拟机的 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
- 创建与虚拟机的 SSH 会话。
导出环境变量。按照上文所定义的步骤创建
server_config.json。export GRPC_GCP_OBSERVABILITY_CONFIG_FILE=./server/serverConfig.json运行服务器应用
shell go run ./server/main.go
Java
- 在示例目录中，打开自述文件并按照该文件中的说明操作。
- 当说明提示您打开另一个终端窗口时，请发出以下命令：
shell gcloud compute ssh --project=$PROJECT_ID grpc-observability-vm
运行客户端
C++
- 创建与虚拟机的另一个 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
- 创建与虚拟机的另一个 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
- 在示例目录中，打开自述文件并按照该文件中的说明操作。
- 当说明提示您打开另一个终端窗口时，请发出以下命令：
shell gcloud compute ssh --project=$PROJECT_ID grpc-observability-vm
清理
为避免因本教程中使用的资源导致您的 Google Cloud 账号产生费用，请删除包含这些资源的项目，或者保留项目但删除各个资源。
删除项目
删除 Google Cloud 项目：
gcloud projects delete PROJECT_ID
删除各个资源
-
删除实例：
gcloud compute instances delete INSTANCE_NAME
后续步骤
- 如需详细了解配置数据、跟踪记录定义、指标定义和日志定义，请参阅微服务可观测性参考文档。
- 如需了解如何查看日志、跟踪记录和指标，请参阅查看跟踪记录、指标和日志条目