本文档包含设置微服务可观测性插件、检测 gRPC 应用以及从 Cloud Monitoring、Cloud Logging 和 Cloud Trace 获取信息所需的信息。
准备工作
微服务可观测性适用于通过启用 Microservices API 来获得 Cloud Monitoring、Cloud Logging 和 Cloud Trace 访问权限的任何部署。本指南使用 Compute Engine 示例提供了微服务可观测性设置示例。
概括来讲，您需要执行以下步骤：
- 作为服务开发者，您可以选择启用并控制微服务可观测性插件。
- 作为服务运营商，您可以通过多种方式使用收集的数据。
gRPC 代码库（C++、Go 和 Java）包含用于展示微服务可观测性的示例。
在配置可观测性之前，请完成以下任务：
- 阅读微服务可观测性概览。
- 确保您已有一个项目或创建一个新项目。
- 确保您已有一个服务账号或创建一个新账号。
- 了解两个支持的环境变量，决定要使用的环境变量，并确定环境变量所需的值。
- 启用 Microservices API。
选择配置环境变量
选择使用微服务可观测性插件（如针对可观测性插件对应用进行插桩处理所述）时，您必须使用环境变量提供配置信息。默认情况下，不会启用可观测性功能。您需要在运行 gRPC 应用或工作负载的虚拟机或容器上设置环境变量。
以下是环境变量：
GRPC_GCP_OBSERVABILITY_CONFIG_FILE：该值是指向 JSON 编码配置文件的路径。GRPC_GCP_OBSERVABILITY_CONFIG：该值是采用 JSON 编码的配置正文。
如果同时设置了这两个环境变量，则 GRPC_GCP_OBSERVABILITY_CONFIG_FILE 优先于 GRPC_GCP_OBSERVABILITY_CONFIG。
如需应用配置，您必须重启 gRPC 应用。无法在 Google Cloud 控制台中设置或查看环境变量的值。
在该配置中，您可以设置将日志记录、跟踪记录和指标数据上传到的目标项目。您可以在 project_id 字段中设置项目 ID。
如果将此字段留空，可观测性插件将根据应用默认凭据自动填充项目 ID 的值。
如果无法识别应用默认凭据，且
project_id字段为空，则INIT/START方法会引发或返回应用错误。应用随后必须处理错误。
使用配置数据中的信息来设置您选择的环境变量中的值。
启用 Microservices API
您可以使用 Google Cloud CLI 或 Google Cloud 控制台在项目中启用 Microservices API。启用 Microservice API 会自动启用 Cloud Logging API、Cloud Monitoring API 和 Cloud Trace API。
如需启用 API，请执行以下操作：
gcloud services enable microservices.googleapis.com
设置服务账号权限
如果使用的是非默认服务账号，请向该服务账号授予所需的权限。设置以下值：
- PROJECT_ID：将占位符替换成您自己的项目 ID。
- SERVICE_ACCOUNT_NAME：将占位符替换成您自己的项目的服务账号名称。
gcloud projects add-iam-policy-binding PROJECT_ID \ --member=serviceAccount:SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com \ --role=roles/logging.logWriter
gcloud projects add-iam-policy-binding PROJECT_ID> \ --member=serviceAccount:SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com \ --role=roles/monitoring.metricWriter
gcloud projects add-iam-policy-binding PROJECT_ID \ --member=serviceAccount:SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com \ --role=roles/cloudtrace.agent
针对可观测性插件对应用进行插桩处理
如需对应用进行插桩处理，以便其使用微服务可观测性插件，请按照以下说明使用 C++、Java 和 Go。
C++
从 gRPC C++ v1.54 开始，您可以将 C++ 与微服务可观测性结合使用。示例代码库位于 GitHub 中。
build 变更
可观测性支持只能通过 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 代码更改
如需对 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>
启用指标、跟踪记录和日志记录数据收集
以下部分介绍了在配置中启用数据收集的说明，以及显示环境变量中的配置信息的示例。
启用指标
如需启用指标，请将 cloud_monitoring 对象添加到配置中，并将其值设置为 {}。
如需详细了解指标，请参阅指标定义。
启用跟踪功能
如果您计划跨服务启用跟踪，请确保服务支持将从上游（或自行启动）接收的跟踪上下文传播到下游。
如需启用跟踪功能，请执行以下操作：
- 将
cloud_trace对象添加到配置中。 - 将
cloud_trace.sampling_rate设置为您希望应用观察到开始新跟踪记录的概率。- 例如，
1.0表示跟踪每个 RPC。 0.0表示不启动任何新的跟踪记录。0.5表示随机跟踪 50% 的 RPC。
- 例如，
如果在上游做出肯定采样决策，则无论采样率设置如何，您的服务都会上传 span。
如需详细了解跟踪，请参阅跟踪记录定义。
启用日志记录
如需启用日志记录，请执行以下操作：
- 将
cloud_logging对象添加到配置中。 - 将模式添加到
client_rpc_events和/或server_rpc_events，以指定要为其生成传输级事件日志记录的一组服务或方法以及要记录标头的字节数和消息。
如需详细了解日志记录，请参阅日志记录定义。
环境变量示例
以下示例在环境变量 GRPC_GCP_OBSERVABILITY_CONFIG 中设置可观测性变量：
export GRPC_GCP_OBSERVABILITY_CONFIG='{
"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": 1.00
},
"labels": {
"SOURCE_VERSION": "J2e1Cf",
"SERVICE_NAME": "payment-service-1Cf",
"DATA_CENTER": "us-west1-a"
}
}'
创建可观测性示例
按照以下说明创建并连接到 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
继续学习 Java、C++ 或 Go 的相关说明，具体取决于您的 gRPC 应用的语言。
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
转到示例目录。
cd grpc-java/examples/example-gcp-observability
在示例目录中，打开 README 文件，然后按照文件中的说明操作。
当系统指示您打开另一个终端窗口时，请发出以下命令：
gcloud compute ssh --project=PROJECT_ID grpc-observability-vm
C++
连接到虚拟机实例后，在终端窗口中运行
hello-world服务器二进制程序。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 cd grpc export GOOGLE_CLOUD_PROJECT=PROJECT_ID export GRPC_GCP_OBSERVABILITY_CONFIG_FILE="$(pwd)/examples/cpp/gcp_observability/helloworld/server_config.json" tools/bazel run examples/cpp/gcp_observability/helloworld:greeter_server
从另一个终端窗口中，使用 SSH 再次连接到虚拟机，然后运行以下命令，该命令会运行
hello-world客户端二进制程序。cd grpc export GOOGLE_CLOUD_PROJECT=PROJECT_ID export GRPC_GCP_OBSERVABILITY_CONFIG_FILE="$(pwd)/examples/cpp/gcp_observability/helloworld/client_config.json" tools/bazel run examples/cpp/gcp_observability/helloworld:greeter_client
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
转到
gRPC-Go目录克隆：cd examples/features/observability
运行服务器。
export GRPC_GCP_OBSERVABILITY_CONFIG_FILE=./server/serverConfig.json go run ./server/main.go
在单独的终端窗口中，运行以下命令。
export PATH=$PATH:/usr/local/go/bin cd grpc-go/examples/features/observability export GRPC_GCP_OBSERVABILITY_CONFIG_FILE=./client/clientConfig.json go run ./client/main.go
查看跟踪记录、指标和日志条目
使用本部分中的说明查看跟踪记录、指标和日志条目。
在 Cloud Trace 上查看跟踪记录
设置示例或对工作负载进行插桩后，您应该会在 Google Cloud 控制台中看到由 gRPC 客户端和 gRPC 服务器生成的跟踪记录（列为最近的跟踪记录）。
查看跟踪记录的日志
如果同时启用日志记录和跟踪记录，则可以与 Cloud Trace 瀑布图或日志浏览器一起查看跟踪记录的日志条目。
在信息中心内查看指标
微服务可观测性为指标定义中定义的指标提供一个名为微服务 (gRPC) Monitoring 的监控信息中心。仅当启用 Microservices API 时，信息中心才会显示在 Google Cloud 控制台中。Google Cloud 控制台会调用 Service Usage API 以验证是否已在项目中启用 Microservices API。用户必须拥有 serviceusage.services.list 权限才能查看信息中心。
微服务 (gRPC) Monitoring 信息中心是一个 Google Cloud 信息中心，您无法直接修改它。如需自定义信息中心，您必须将该信息中心复制到自定义信息中心。然后，您可以更新自定义信息中心，例如添加、删除或重新排列图表。
在 Metrics Explorer 上查看指标
设置 gRPC 示例或检测工作负载后，您应该会在 Google Cloud 控制台中看到 gRPC 客户端和 gRPC 服务器生成的指标。
如需查看和绘制指标图表，请按照使用 Metrics Explorer 时选择指标中的说明执行操作
在日志浏览器中检查日志条目
建议的查询是 Cloud Logging 的一项功能，其中 Google Cloud 会根据注入的日志建议一组查询。您可以点击并使用准备好的过滤条件。
在 Cloud Logging 中显示与建议查询匹配的日志条目后，您会在大约 6 分钟内看到新的建议查询。在大多数情况下，您会在更早看到新的建议查询。如果过去 15 分钟内有与建议匹配的日志条目，则系统会继续显示任何建议的查询。它们会继续显示为建议，直到过去 15 分钟内没有任何匹配的日志条目。
您可以创建自定义查询。如需查看相关说明，请参阅日志记录查询语言指南。例如，在 Logs Explorer 的“查询”窗格中，您可以尝试使用以下代码显示所有 gRPC 调试日志：
log_id("microservices.googleapis.com/observability/grpc")
您可以使用 gRPC 日志记录中的所有字段进行过滤。以下是日志条目示例：
{
"insertId": "17kh8vafzuruci",
"jsonPayload": {
"authority": "10.84.1.15:50051",
"sequenceId": "6",
"serviceName": "helloworld.Greeter",
"peer": {
"ipPort": 50051,
"address": "10.84.1.10",
"type": "IPV4"
},
"callId": "d9577780-c608-4bff-9e12-4d9cdea6b298",
"type": "SERVER_TRAILER",
"methodName": "SayHello",
"payload": {},
"logger": "CLIENT"
},
"resource": {
"type": "k8s_container",
"labels": {
"pod_name": "grpc-client-deployment-155-6967959544-x8ndr",
"container_name": "grpc-client-container-155",
"cluster_name": "o11y-cluster",
"namespace_name": "grpc-client-namespace-155",
"location": "us-west1-b",
"project_id": "grpc-greeter"
}
},
"timestamp": "2023-04-05T23:33:41.718523Z",
"severity": "DEBUG",
"labels": {
"environment": "example-client"
},
"logName": "projects/grpc-greeter/logs/microservices.googleapis.com%2Fobservability%2Fgrpc",
"receiveTimestamp": "2023-04-05T23:33:42.712682457Z"
}
建议的查询
微服务可观测性向 Cloud Logging 提供以下建议查询：
gRPC 的标题或尾部日志记录
此查询提供 RPC 的基本视图，并生成对等信息和 RPC 结果。
log_id("microservices.googleapis.com/observability/grpc") AND
jsonPayload.type=("CLIENT_HEADER" OR "SERVER_TRAILER")
gRPC 调用失败
此查询查找以非正常状态结束的 RPC。
log_id("microservices.googleapis.com/observability/grpc") AND
jsonPayload.type="SERVER_TRAILER" AND
jsonPayload.payload.statusCode!="OK"
已取消或超出期限的 gRPC 的日志记录
gRPC 取消过多或超出时限可以提供有关性能损失或意外应用行为的有用信息。
log_id("microservices.googleapis.com/observability/grpc") AND
((jsonPayload.type="SERVER_TRAILER" AND jsonPayload.payload.statusCode=("CANCELLED" OR "DEADLINE_EXCEEDED")) OR (jsonPayload.type="CANCEL"))
使用日志和跟踪记录进行问题排查
如果您看到指示不良行为的 RPC 事件，则可以在事件中找到 callid。使用以下查询可显示一个 RPC 中发生的所有事件，无论它是一元 RPC 还是流式传输 RPC。上述日志条目用作示例：
log_id("microservices.googleapis.com/observability/grpc")
jsonPayload.callid="a358c7b80-3548-4bc8-a33f-b93ba1514904"
如需确定问题的范围，您可以找到同一方法或位置的所有 RPC 事件。以下查询以 Greeter 服务为例，显示与特定 RPC 方法相关的所有调试日志：
log_id("microservices.googleapis.com/observability/grpc")
jsonPayload.serviceName="helloworld.Greeter"
jsonPayload.methodName="SayHello"
如需检查特定状态代码的失败 RPC，您可以添加状态代码作为过滤条件之一。以下查询显示了以不正常状态结束的尾随事件：
log_id("microservices.googleapis.com/observability/grpc")
jsonPayload.payload.statusCode!="OK"
可观测性选项
微服务可观测性包括以下可选功能。
定义自定义标签
您可以定义自定义标签，以便将用户提供的信息添加到可观测性数据。自定义标签由键值对组成。每个键值对都作为跨度标签附加到跟踪数据，作为度量标签附加到度量数据，并作为日志条目标签附加到日志记录数据。
自定义标签通过 labels 字段中的键值对列表在配置中定义。所有自定义标签键和值的类型均为 STRING。该实现会读取配置并为每个键值对创建单独的标签，然后将该标签附加到可观测性数据。
例如，以下是一个标签定义：
"labels": {
"DATACENTER": "SAN_JOSE_DC",
"APP_ID": "24512"
}
每个日志条目都有以下附加标签：
{
"DATACENTER" : "SAN_JOSE_DC"
"APP_ID" : "24512"
}
启用载荷日志记录
使用您提供给工作负载的环境变量启用载荷日志记录。如需为 HelloWorld 消息和标头启用载荷日志记录，请更新 gRPC 示例中配置文件 gcp_observability_server_config.json 和/或 gcp_observability_client_config.json 的值，如下所示：
{
"cloud_monitoring":{
},
"cloud_trace":{
"sampling_rate":1.0
},
"cloud_logging":{
"client_rpc_events":[
{
"methods":[
"helloworld.Greeter/*"
],
"max_metadata_bytes":4096,
"max_message_bytes":4096
}
],
"server_rpc_events":[
{
"methods":[
"helloworld.Greeter/*"
],
"max_metadata_bytes":4096,
"max_message_bytes":4096
}
]
}
}
设置跨项目可观测性
您可以使用环境变量 GRPC_GCP_OBSERVABILITY_CONFIG 中设置的配置明确设置目标项目。对于跨项目可观测性，您还必须设置适当的服务账号权限。假设目标项目 ID 为 core-platform-stats，您可以通过以下示例配置设置跨项目可观测性：
{
"project_id":"core-platform-stats",
"cloud_monitoring":{
},
"cloud_trace":{
"sampling_rate":1.0
},
"cloud_logging":{
"client_rpc_events":[
{
"methods":[
"helloworld.Greeter/*"
]
}
],
"server_rpc_events":[
{
"methods":[
"helloworld.Greeter/*"
]
}
]
}
}
估算日志量
本部分为您提供了可用于酌情估算日志注入量的信息。您可以在订阅服务的 RPC 事件之前进行估算。
| 资源项 | 详细信息 |
|---|---|
| 为 OK 一元调用生成的事件 | 6 个事件 OK 一元调用 RPC 会为客户端或服务器生成以下 6 个事件：
|
| 日志条目的平均大小 | 默认为 500 个字节 日志条目映射到一个 RPC 事件，RPC 事件包含该事件、资源标签和自定义标签的详细调试信息。 |
| 载荷日志记录大小 | 默认为 0，可以配置 最大载荷大小可在“可观测性配置”中配置。默认情况下，系统不会记录载荷。 |
| 自定义标签大小 | 默认为 0，可以配置 系统会使用环境变量向应用提供自定义标签。如果未指定，则没有自定义标签 |
每月日志注入总大小的估算公式：
Monthly Log Ingestion = QPS * 6 * (500B + Payload Logging Size + Custom Labels Size) * 2592000
例如，如果一元调用方法的 QPS 为 1 且未启用任何额外功能，则估算的日志注入大小约为 7.24 GiB。
后续步骤
- 如需详细了解配置数据、跟踪记录定义、指标定义和日志定义，请参阅微服务可观测性参考。