使用 gRPC 客户端指标

本页面介绍了如何在使用 gRPC 通过以下受支持的接口之一与 Cloud Storage 进行交互时，向 Cloud Monitoring 发出 gRPC 客户端指标：

客户端指标可用于监控使用 gRPC 与 Cloud Storage 交互的客户端应用的性能。客户端指标与服务器端指标不同，后者从服务器端的角度分析 Cloud Storage 性能。

工作原理

您可以选择在使用 gRPC 通过某个受支持的接口与 Cloud Storage 进行交互时向 Cloud Monitoring 发出客户端指标。您可以使用 Metrics Explorer 查看客户端指标，以帮助您监控和优化 Cloud Storage 与 gRPC 客户端之间的互动、管理用量以及排查性能瓶颈和技术问题。

价格

Cloud Storage 客户端指标是免费的，这意味着您可以发出、存储和访问 Cloud Storage 客户端指标，而不会产生 Cloud Monitoring 费用。如需详细了解价格，请参阅 Google Cloud Observability 价格。

准备工作

如需使用客户端指标，您必须先完成以下步骤：

验证您要使用的 Cloud Storage 客户端库或连接器是否支持 gRPC。以下 Cloud Storage 客户端库和连接器支持 gRPC：
设置身份验证。
启用 Cloud Monitoring API。
启用 Cloud Storage API。

前往 Cloud Storage API
设置发出客户端指标所需的角色和权限。

所需的角色

如需设置向 Cloud Monitoring 发出 gRPC 客户端指标所需的权限，请向 gRPC 客户端使用的服务账号授予 Monitoring Metric Writer (roles/monitoring.metricWriter) IAM 角色。

此预定义角色包含向 Cloud Monitoring 发出 gRPC 客户端指标所需的权限。如需查看所需的确切权限，请参阅所需权限部分：

所需权限

monitoring.timeSeries.create

您也可以使用其他自定义角色或预定义角色来获得这些权限。如需详细了解 Monitoring Metric Writer 角色，请参阅有关 roles/monitoring.metricWriter 的 IAM 文档。

注意事项

如果您在 Dataproc 上使用 Cloud Storage 连接器，则需要向 Dataproc 虚拟机 (VM) 服务账号授予 Monitoring Metric Writer (roles/monitoring.metricWriter) IAM 角色。
如果您在 Dataflow 上使用 Apache Beam 连接器，则需要向 Dataflow 工作器服务账号授予 Monitoring Metric Writer (roles/monitoring.metricWriter) IAM 角色。

在 Metrics Explorer 中查看指标

请按照以下说明在 Metrics Explorer 中查看 Cloud Storage gRPC 客户端方面的指标。

在 Google Cloud 控制台中，转到 Metrics Explorer 页面。

转到 Metrics Explorer
选择要查看指标的项目。
在指标下拉菜单中，点击选择指标。
在按资源或指标名称过滤搜索栏中，输入 storage.googleapis.com/Client 或按指标名称搜索要应用的指标，然后点击应用。如需添加多个指标，请点击添加查询。

Cloud Storage 会将指标应用于您的项目。您可以使用以下下拉菜单过滤或汇总指标：
- 如需根据指定条件选择和查看部分数据，请使用过滤条件下拉菜单。
- 如需将多个数据点合并为单个值并查看指标的摘要视图，请使用汇总下拉菜单。
让应用运行至少 1 分钟，然后再检查是否有任何已发布的指标。

如需查看您使用信息中心向项目添加的指标，请参阅信息中心概览。

指标说明

以下各部分概述了可用于监控 gRPC 客户端性能的 Cloud Storage 客户端指标。

客户端每次尝试指标

以下指标会收集客户端尝试与服务器通信的各次尝试的性能数据。客户端每次尝试指标可帮助您衡量重试行为、瓶颈，并优化客户端与服务器之间的通信。

完整指标	说明	插桩类型	单位	属性
`storage.googleapis.com/client/grpc/client/attempt/started`	`Preview`。已启动的 RPC 尝试次数，包括尚未完成的 RPC 尝试。	计数器	`{attempt}`	`grpc.method`：完整的 gRPC 方法名称，包括软件包、服务和方法。 `grpc.target`：创建 gRPC 渠道时使用的规范化目标 URI。
`storage.googleapis.com/client/grpc/client/attempt/duration`	`Preview`。完成 RPC 尝试所需的端到端时间（包括选择子通道所需的时间）。	直方图	`s`	`grpc.method`：完整的 gRPC 方法名称，包括软件包、服务和方法。 `grpc.target`：创建 gRPC 渠道时使用的规范化目标 URI。 `grpc.status`：收到的 gRPC 服务器状态代码，例如 `OK`、`CANCELLED` 或 `DEADLINE_EXCEEDED`。 `grpc.lb.locality`：流量被发送到的区域。此属性将设置为从 `weighted_target` 政策传递的解析器属性，如果解析器属性未设置，则为空字符串。
`storage.googleapis.com/client/grpc/client/attempt/sent_total_compressed_message_size`	`Preview`。每次 RPC 尝试在所有请求消息中发送的总字节数（压缩，未加密），不包括元数据。不包括 gRPC 或传输框架字节。	直方图	`By`	`grpc.method`：完整的 gRPC 方法名称，包括软件包、服务和方法。 `grpc.target`：创建 gRPC 渠道时使用的规范化目标 URI。 `grpc.status`：收到的 gRPC 服务器状态代码，例如 `OK`、`CANCELLED` 或 `DEADLINE_EXCEEDED`。 `grpc.lb.locality`：流量被发送到的区域。此属性将设置为从 `weighted_target` 政策传递的解析器属性，如果解析器属性未设置，则设置为空字符串。
`storage.googleapis.com/client/grpc/client/attempt/rcvd_total_compressed_message_size`	`Preview`。每次 RPC 尝试在所有响应消息中收到的总字节数（压缩，未加密），不包括元数据。不包括 gRPC 或传输框架字节。	直方图	`By`	`grpc.method`：完整的 gRPC 方法名称，包括软件包、服务和方法。 `grpc.target`：创建 gRPC 渠道时使用的规范化目标 URI。 `grpc.status`：收到的 gRPC 服务器状态代码，例如 `OK`、`CANCELLED` 或 `DEADLINE_EXCEEDED`。 `grpc.lb.locality`：流量发送到的区域。此属性将设置为从 `weighted_target` 政策传递的解析器属性，如果解析器属性未设置，则为空字符串。

如需详细了解客户端每次尝试指标，请参阅 GitHub 中的 OpenTelemetry 指标文档。

客户端每次来电指标

以下指标提供了客户端对服务器的调用的整个生命周期的汇总视图。客户端每通来电指标可提供有关客户端来电的概要数据，提供跟踪指标以了解来电模式，并帮助您确定错误的频率。

完整指标	说明	插桩类型	单位	属性
`storage.googleapis.com/client/grpc/client/call/duration`	`Preview`。衡量 gRPC 库从应用的角度完成 RPC 所需的端到端时间。	直方图	`s`	`grpc.method`：完整的 gRPC 方法名称，包括软件包、服务和方法。 `grpc.target`：创建 gRPC 渠道时使用的规范化目标 URI。 `grpc.status`：收到的 gRPC 服务器状态代码，例如 `OK`、`CANCELLED` 或 `DEADLINE_EXCEEDED`。

如需详细了解客户端每调用插桩，请参阅 GitHub 中的 OpenTelemetry 指标文档。

请求负载感知指标

以下指标可让您深入了解客户端应用使用请求负载感知的有效性。请求负载感知指标可帮助您均衡服务器负载、优化资源利用率并缩短客户端响应时间。以下指标仅在直接连接的情况下可用。

完整指标	说明	插桩类型	单位	属性
`storage.googleapis.com/client/grpc/lb/rls/cache_entries`	`Preview`。请求加载感知缓存中的条目数。	仪表盘	`{entry}`	`grpc.target`：表示 WRR 所用 gRPC 通道的目标。 `grpc.lb.rls.server_target`：请求负载感知服务器与之通信的目标 URI。 `grpc.lb.rls.instance_uuid`：单个请求负载感知客户端实例的通用唯一标识符 (UUID)。该值本身没有意义，但在同一 gRPC 渠道中有多个实例或同一目标有多个渠道的情况下，它可用于区分请求负载感知客户端实例。
`storage.googleapis.com/client/grpc/lb/rls/cache_size`	`Preview`。请求负载感知缓存的当前大小。	仪表盘	`By`	`grpc.target`：WRR 所用 gRPC 通道的目标。 `grpc.lb.rls.server_target`：请求负载感知服务器与之通信的目标 URI。 `grpc.lb.rls.instance_uuid`：单个请求负载感知客户端实例的 UUID。该值本身没有意义，但在同一 gRPC 渠道中有多个实例或同一目标有多个渠道的情况下，它可用于区分请求负载感知客户端实例。
`storage.googleapis.com/client/grpc/lb/rls/default_target_picks`	`Preview`。发送到默认目标的负载均衡器 (LB) 选择次数。	计数器	`{pick}`	`grpc.target`：表示使用请求负载感知的 gRPC 渠道的目标。 `grpc.lb.rls.server_target`：请求负载感知服务器要与之通信的目标 URI。 `grpc.lb.rls.data_plane_target`：用于路由数据平面流量的请求负载感知的目标字符串。该值要么由请求负载感知服务器针对特定键返回，要么在请求负载感知配置中配置为默认目标。 `grpc.lb.pick_result`：LB 选择的结果，例如 `"complete"`、`"fail"` 或 `"drop"`。
`storage.googleapis.com/client/grpc/lb/rls/target_picks`	`Preview`。发送到每个请求负载感知目标的 LB 选择次数。如果请求负载感知服务器也返回了默认目标，则从缓存发送到该目标的 RPC 会计入此指标，而非 `grpc.rls.default_target_picks`。	计数器	`{pick}`	`grpc.target`：使用请求负载感知的 gRPC 渠道的目标。 `grpc.lb.rls.server_target`：请求负载感知服务器要与之通信的目标 URI。 `grpc.lb.rls.data_plane_target`：请求负载感知用于路由数据平面流量的目标字符串。该值要么由请求负载感知服务器针对特定键返回，要么在请求负载感知配置中配置为默认目标。 `grpc.lb.pick_result`：LB 选择的结果，例如 `"complete"`、`"fail"` 或 `"drop"`。
`storage.googleapis.com/client/grpc/lb/rls/failed_picks`	`Preview`。由于请求负载感知请求失败或请求负载感知通道遭到限制而失败的 LB 选择次数。	计数器	`{pick}`	`grpc.target`：使用请求负载感知的 gRPC 渠道的目标。 `grpc.lb.rls.server_target`：请求负载感知服务器要与之通信的目标 URI。

xDiscovery Service 客户端指标

以下指标可提供有关客户端应用如何与 xDiscovery Service (xDS) 控制平面进行交互以发现和配置与后端服务的连接的数据分析。xDS 指标可帮助您跟踪服务请求延迟时间、监控配置更新，以及优化整体 xDS 性能。

以下指标仅在直接连接的情况下可用。

完整指标	说明	插桩类型	单位	属性
`storage.googleapis.com/client/grpc/xds_client/connected`	`Preview`。衡量 xDS 客户端是否有可用的 ADS 流到 xDS 服务器。对于给定服务器，此指标在流最初创建时会设置为 `1`。如果发生连接失败，或者 ADS 数据流失败但未看到 `A57` 中所述的响应消息，该指标会设置为 `0`。一旦设置为 `0`，该指标将在 ADS 数据流上收到第一个响应时重置为 `1`。此指标仅适用于 C++ 版 Cloud 客户端库。	仪表盘	`{bool}`	`grpc.target`：对于客户端，表示 `XdsClient` 所使用的 gRPC 渠道的目标。对于服务器，将是字符串 `"#server"`。 `grpc.xds.server`：`XdsClient` 正在与之通信的 xDS 服务器的目标 URI。
`storage.googleapis.com/client/grpc/xds_client/resource_updates_invalid`	`Preview`。收到的被视为无效的资源数量。此指标仅适用于 C++ 版 Cloud 客户端库。	计数器	`{resource}`	`grpc.target`：对于客户端，表示使用 `XdsClient` 的 gRPC 渠道的目标。对于服务器，将是字符串 `"#server"`。 `grpc.xds.server`：`XdsClient` 正在与之通信的 xDS 服务器的目标 URI。 `grpc.xds.resource_type`：表示 xDS 资源类型，例如 `"envoy.config.listener.v3.Listener"`。
`storage.googleapis.com/client/grpc/xds_client/resource_updates_valid`	`Preview`。已收到的资源数量，即使未更改，也被视为有效。此指标仅适用于 C++ 版 Cloud 客户端库。	计数器	`{resource}`	`grpc.target`：对于客户端，表示使用 `XdsClient` 的 gRPC 渠道的目标。对于服务器，将是字符串 `"#server"`。 `grpc.xds.server`：`XdsClient` 正在与之通信的 xDS 服务器的目标 URI。 `grpc.xds.resource_type`：表示 xDS 资源类型，例如 `"envoy.config.listener.v3.Listener"`。
`storage.googleapis.com/client/grpc/xds_client/resources`	`Preview`。xDS 资源的数量。此指标仅适用于 C++ 版 Cloud 客户端库。	仪表盘	`{resource}`	`grpc.target`：对于客户端，表示使用 `XdsClient` 的 gRPC 渠道的目标。对于服务器，将是字符串 `"#server"`。 `grpc.xds.authority`：xDS 授权实体。对于在引入 `xdstp://` URI 表示法之前在 xDS API 中标识的非 xdstp 资源名称，该值将为 `"#old"`。 `grpc.xds.cache_state`：表示 xDS 资源的缓存状态。 `grpc.xds.resource_type` 表示 xDS 资源类型，例如 `"envoy.config.listener.v3.Listener"`。
`storage.googleapis.com/client/grpc/xds_client/server_failure`	`Preview`。不再正常运行且已变得不可用、过载或提供错误或无效配置数据的 xDS 服务器的数量。此指标仅适用于 C++ 版 Cloud 客户端库。	计数器	`{failure}`	`grpc.target`：`XdsClient` 正在与之通信的 xDS 服务器的目标 URI。 `grpc.xds.server`：对于客户端，这表示使用 `XdsClient` 的 gRPC 渠道的目标。对于服务器，这是字符串 `"#server"`。

如需详细了解 xDS 客户端指标，请参阅 GitHub 中的基于 xDS 的全局负载均衡文档。

停用客户端指标

您可以根据需要选择停用客户端指标。

Java

public GrpcStorageOptions.Builder setEnableGrpcClientMetrics(false enableGrpcClientMetrics)

如需了解详情，请参阅 Java 版 Cloud 客户端库类 GrpcStorageOptions.Builder 方法的 gRPC 客户端指标。

C++

如需使用 C++ 版 Cloud 客户端库停用 gRPC API 的客户端指标，请参阅结构体 EnableGrpcMetricsOption。

如果您使用 Bazel 构建应用，并希望停用客户端指标，请在应用的 build 文件中将 enable_grpc_metrics 选项设置为 false。

后续步骤

详细了解在 Google Cloud中实现可观测性。
了解如何向应用添加自定义跟踪记录和指标。