用户定义的指标概览

用户定义的指标是指 Google Cloud 未定义的所有指标。其中包括您可能定义的指标，以及 由第三方应用定义的通过用户定义的指标，您可以捕获特定于应用的数据或客户端系统数据。Cloud Monitoring 收集的内置指标可以为您提供有关后端延迟时间或磁盘使用情况的信息，但无法告知您的应用衍生了多少个后台例程等内容。

您还可以创建基于日志条目内容的指标。 基于日志的指标是一类用户定义的指标，但您必须创建 从 Cloud Logging 中获取它们。如需详细了解基于日志的指标，请参阅基于日志的指标概览。

用户定义的指标有时也称为自定义指标或 应用特定指标这些指标可让您或第三方 应用, 定义 并收集内置 Cloud Monitoring 指标无法实现的信息。 您可以使用由库提供的 API 来对代码进行插桩并由此捕获此类指标，然后将这些指标发送到 Cloud Monitoring 等后端应用。

您可以创建用户定义的指标（基于日志的指标除外）、 Cloud Monitoring API 监控。不过，我们建议您使用 OpenTelemetry。有关如何 创建用户定义的指标，请参阅以下文档：

• 收集 OTLP 指标和跟踪记录介绍了如何使用 Ops Agent 及其 OpenTelemetry 协议 (OTLP) 接收器从使用 OpenTelemetry 插桩且在 Compute Engine 上运行的应用中收集指标和跟踪记录。

• Google Cloud Managed Service for Prometheus 介绍了如何收集 Prometheus Google Kubernetes Engine 和 Kubernetes 上运行的应用中的指标。

• 收集 Prometheus 指标描述了如何收集 Prometheus 指标， 使用 Ops Agent 从应用中收集 Prometheus 指标 在 Compute Engine 上运行

• 使用 API 创建用户定义的指标 介绍了如何使用 Cloud Monitoring API 创建指标 以及如何为这些指标添加指标数据。 本文档说明了如何将 Monitoring API 与 使用 API Explorer、C#、Go、 Java、Node.js、PHP、Python 和 Ruby 编程语言。

• 在 Cloud Run 上创建自定义指标介绍了如何在 Cloud Run 部署中将 OpenTelemetry Collector 用作边车代理。

在 Cloud Monitoring 中，您可以像使用内置指标一样使用用户定义指标。您可以为自定义指标绘制图表、设置提醒、读取它们，也可以监控它们。如需了解如何读取指标数据，请参阅以下文档：

• 列出指标和资源类型介绍了如何列出 并检查用户定义的指标类型和内置指标类型。例如，您可以使用该文档中的信息列出项目中的所有用户定义的指标描述符。
• 检索时间序列数据介绍了如何使用 Monitoring API 从指标中检索时间序列数据。例如，本文档介绍了如何使用该 API 获取 Google Cloud 项目中虚拟机 (VM) 实例的 CPU 利用率。

Google Cloud 控制台提供了一个专用页面，可帮助您查看 用户定义的指标有关本页内容的信息，请参阅 查看和管理指标使用情况。

注意：用户定义的指标是 Cloud Monitoring 的付费功能。 如需了解价格，请参阅 Cloud Monitoring 价格摘要。

用户定义的指标的指标描述符

每种指标类型都必须有一个指标描述符，用于定义指标数据的组织方式。指标描述符还定义了 以及指标的名称例如， 指标列表：显示所有内置指标 指标类型。

Cloud Monitoring 可以使用您写入的指标数据为您创建指标描述符，您也可以显式创建指标描述符，然后再写入指标数据。无论是哪种情况，您都必须 您希望如何组织指标数据

设计示例

假设您有一个在单台机器上运行的程序，并且此程序调用辅助程序 A 和 B。您希望计算程序 A 和 B 的调用频率。您还想在程序 A 的调用频率超过每分钟 10 次，以及程序 B 的调用频率超过每分钟 5 次的时候收到提醒。最后，假设您有一个 Google Cloud 项目，并且计划将数据写入 global 受监控的资源。

以下示例介绍了可用于用户定义指标的几种不同设计：

• 您使用两个指标：Metric-type-A 统计对程序的调用次数 A 和 Metric-type-B 计算对计划 B 的调用次数。此时，Metric-type-A 包含 1 个时间序列，Metric-type-B 包含 1 个时间序列。

  您可以创建一个包含两个条件的提醒政策，也可以创建两个提醒政策，每个提醒政策均包含一个具有此数据模式的条件。一个提醒政策可以支持多个条件，但对于通知渠道仅支持一个配置。

  如果您对受监控活动的数据之间的相似性不感兴趣，则此模型可能是合适的。在此示例中，活动为程序 A 和 B 的调用率。

• 您可以使用一个指标并使用标签来存储程序标识符。例如，标签可以存储值 A 或 B。Monitoring 会为每个唯一的标签组合创建一个时序。因此，存在一个标签值为 A 的时序和另一个标签值为 B 的时序。

  与上一个模型一样，您可以创建一个提醒政策或两个提醒政策。但是，提醒政策的条件更为复杂。程序 A 的调用速率超过阈值时生成突发事件的条件必须使用仅包含标签值为 A 的数据点的过滤条件。

  此模型的一个优势是计算比率很简单。例如，您可以确定总数中有多大比例是对 A 的调用。

• 您可以使用一个指标来计算调用次数，但不能使用标签记录调用了哪个程序。此模型有一个时间序列，其中结合了两个程序的数据。但是，您无法创建符合您目标的提醒政策，因为两个程序的数据无法分开。

前两种设计可让您满足数据分析要求；但最后一个设计则不支持。

如需了解详情，请参阅创建用户定义的指标。

用户定义的指标的名称

创建用户定义的指标时，您需要定义一个字符串标识符， 表示指标类型。此字符串在 中用户定义的指标 并且必须使用将指标标记为 用户定义的指标对于 Monitoring，允许使用的前缀为 custom.googleapis.com/、workload.googleapis.com/、external.googleapis.com/user 和 external.googleapis.com/prometheus。前缀后跟一个名称 说明了您要收集的内容。 如需详细了解命名指标的推荐方法，请参阅指标命名惯例。以下是两种指标类型的标识符示例：

    custom.googleapis.com/cpu_utilization
    custom.googleapis.com/instance/cpu/utilization

在前面的示例中，前缀 custom.googleapis.com 表示 指标都是用户定义的指标这两个示例都适用于衡量 CPU 利用率；但它们使用不同的组织模式。如果您预计会有大量用户定义的指标，我们建议您使用第二个示例所用的分层命名结构。

所有指标类型都具有称为“资源名称”的全局唯一标识符。指标类型的资源名称结构为：

projects/PROJECT_ID/metricDescriptors/METRIC_TYPE

其中，METRIC_TYPE 是指标类型的字符串标识符。如果上述指标示例是在项目 my-project-id 中创建的，则这些指标的资源名称如下：

    projects/my-project-id/metricDescriptors/custom.googleapis.com/cpu_utilization
    projects/my-project-id/metricDescriptors/custom.googleapis.com/instance/cpu/utilization

名称还是类型？ 在指标描述符中，name 字段存储指标类型的资源名称，而 type 字段存储 METRIC_TYPE 字符串。

用户定义的指标的受监控资源类型

将数据写入时间序列时，您必须指明数据的来源。要指定数据的来源，您需要选择一个 受监控的资源类型 代表数据的来源，然后使用它来描述 特定来源。受监控的资源不属于指标类型。 而是时序 数据包含对指标类型的引用和 对受监控的资源的引用。指标类型用于描述数据 受监控的资源描述数据的来源。

在创建指标描述符之前，请先考虑受监控的资源。您使用的受监控的资源类型会影响您需要在指标描述符中添加的标签。例如，Compute Engine 虚拟机资源包含项目 ID、实例 ID 和实例可用区的标签。因此，如果您 您计划针对 Compute Engine 虚拟机资源写入指标， 那么资源标签会包含实例 ID 不需要为指标描述符中的实例 ID 添加标签。

每个指标的数据点都必须与一个受监控的资源对象关联。不同受监控的资源对象的数据点保存在不同的时序中。

您必须将以下受监控的资源类型之一与 用户定义的指标：

• aws_ec2_instance：Amazon EC2 实例。
• dataflow_job：Dataflow 作业。
• gae_instance：App Engine 实例。
• gce_instance：Compute Engine 实例。
• generic_node：用户指定的计算节点。
• generic_task：用户定义的任务。
• gke_container：GKE 容器实例。
• global：其他资源类型均不适用时，请使用此资源。对于大多数使用场景来说，更适合选择 generic_node 或 generic_task，而非 global。
• k8s_cluster：Kubernetes 集群。
• k8s_container：Kubernetes 容器。
• k8s_node：Kubernetes 节点。
• k8s_pod：Kubernetes pod。

常见做法是使用表示运行应用代码的物理资源的受监控资源对象。 这样做具有很多优势：

• 与使用单一资源类型相比，您可以体验更好的性能。
• 避免因多个进程向同一时间序列写入数据导致的数据无序。
• 您可以将用户定义的指标数据与来自相同资源的其他指标数据组合在一起。

global 和通用资源

在某些情况下，如果没有更具体的资源类型适合使用，则 generic_task 和 generic_node 资源类型十分实用。generic_task 类型适用于定义类似任务的资源（如应用）。generic_node 类型适用于定义类似节点的资源（如虚拟机）。 这两种 generic_* 类型都有多个可用于定义唯一资源对象的常见标签，让您可以轻松地在指标过滤条件中使用这些标签进行聚合和缩减。

相比之下，global 资源类型只有 project_id 标签。如果一个项目中有多个指标来源，则使用相同的 global 资源对象可能会导致您的指标数据发生冲突和被覆盖。

支持用户定义的指标的 API 方法

下表显示了 Monitoring API 中的哪些方法 支持用户定义的指标以及支持内置指标的方法：

Monitoring API 方法	与 用户定义的指标搭配使用	与 内置指标搭配使用
monitoredResourceDescriptors.get	是	是
monitoredResourceDescriptors.list	是	是
metricDescriptors.get	是	是
metricDescriptors.list	是	是
timeSeries.list	是	是
timeSeries.create	是
metricDescriptors.create	是
metricDescriptors.delete	是

限制和延迟时间

如需了解与用户定义的指标和数据保留相关的限制，请参阅配额和限制。

如需在超过指标数据的保留期限之后继续保留，您必须手动将数据复制到其他位置，例如 Cloud Storage 或 BigQuery。

如需了解与将数据写入用户定义的指标相关的延迟时间，请参阅指标数据的延迟时间。

后续步骤

• 使用 Google Cloud Managed Service for Prometheus 收集 Prometheus Google Kubernetes Engine 和 Kubernetes 上运行的应用中的指标。
• 收集 Prometheus 指标，来源为： Compute Engine 上运行的应用
• 从使用 OpenTelemetry 插桩且在 Compute Engine 上运行的应用收集 OTLP 指标和轨迹。
• 使用 API 创建用户定义的指标
• Cloud Monitoring API 简介
• 指标、时序和资源