自定义指标是用户定义的指标。自定义指标使用的元素与内置 Cloud Monitoring 指标相同:
- 一组数据点。
- 指标类型信息,用于说明数据点代表什么。
- 受监控的资源信息,用于说明数据点的来源。
自定义指标的使用方式与内置指标相同。也就是说,您可以为自定义指标数据创建图表和提醒。
如需了解内置指标和自定义指标的底层结构,请参阅指标、时间序列和资源。如需浏览内置指标,请参阅指标列表。 如需浏览可用的受监控资源,请参阅资源列表。
使用自定义指标
要使用自定义指标,您必须有新指标类型的指标描述符。指标描述符定义数据的组织方式。在开始写入自定义指标数据之前,请确定您希望如何使用收集的数据,并确保数据组织支持这些目标。
创建指标描述符
Cloud Monitoring 可以自动为您创建指标描述符,也可以使用 Monitoring API 中的 metricDescriptors.create
方法自行创建指标描述符。您不能使用 Google Cloud Console for Monitoring 操纵指标描述符。
要让 Cloud Monitoring 为您创建指标描述符,您只需为指标写入时间序列数据,然后 Cloud Monitoring 会根据您写入的数据创建描述符。如需了解详情,请参阅自动创建指标描述符。自动创建存在限制,因此了解指标定义中包含哪些信息会很有帮助。获得新的自定义指标描述符后(无论是由您还是由 Monitoring 创建),您都可以将指标描述符用于指标描述符 API 方法和时间序列 API 方法。
无论您是明确创建指标描述符,还是让 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
的调用率超过阈值时生成突发事件的条件,条件需要包含一个过滤器,该过滤器包括标签值为A
的数据点并排除所有其他数据点。此模型的一个优势是计算比率很简单。例如,您可以确定总数中有多大比例是对
A
的调用。使用单个自定义指标类型来计算调用次数,但不使用标签来记录被调用的程序。此模型有一个时间序列,其中结合了两个程序的数据。但是,您无法创建符合您目标的提醒政策,因为两个程序的数据无法分开。
自定义指标名称
创建自定义指标时,您需要创建一个表示该指标类型的字符串标识符。此字符串在 Google Cloud 项目的自定义指标中必须是唯一的。字符串必须以将其标记为用户定义指标的前缀开头。对于 Monitoring,唯一支持的前缀是 custom.googleapis.com/
和 external.googleapis.com/prometheus
。不支持使用任意前缀。前缀后跟一个名称,用于描述您要收集的信息。如需了解详情,请参阅命名规则。
以下是两种指标类型的标识符示例:
custom.googleapis.com/cpu_utilization
custom.googleapis.com/instance/cpu/utilization
自定义指标类型的资源名称在所有项目的所有 Google Cloud 资源中都是唯一的。指标类型的资源名称格式为:
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
字符串。
定义自定义指标描述符
要收集自定义指标数据,您必须提供一个 MetricDescriptor
对象,用于指定该指标的各种信息。Cloud Monitoring 可以自动为您创建描述符;如需了解详情,请参阅自动创建指标描述符。
如果您想明确创建指标描述符,则需要提供以下信息:
请按照上一部分中的说明,为自定义指标类型选择标识符。
选择一个项目,在其中定义您的自定义指标并写入其时间序列数据。
如果您需要在多个项目中使用相同的指标,请在每个项目中为指标提供相同的定义。
AWS 的自定义指标应该在您 AWS 帐号的 AWS 连接器项目中创建。
选择指标的显示名和说明。显示名将在 Google Cloud Console 中使用。
选择指标的种类、值类型和(可选)单位。 并非所有值类型和指标种类都支持自定义指标。 请参阅值类型和指标类型。
选择指标的标签 - 其名称、值类型和说明。
如需获取有关如何进行上述选择的更多帮助,您可以浏览内置指标以及查看时间序列数据。
手动创建指标描述符包括用于手动创建指标描述符的代码示例。
选择受监控的资源类型
将数据写入时间序列时,您必须指明数据的来源。为此,请选择一种受监控的资源类型,用于表示数据的来源,然后用它来描述特定来源。受监控的资源不是指标类型的一部分;相反,您向其写入数据的时间序列包含对指标类型(用于描述数据)的引用以及对受监控的资源(用于指示数据的来源)的引用。
在创建指标描述符之前,请先考虑受监控的资源。您使用的受监控的资源类型会影响您需要在指标描述符中添加的标签。例如,如果您将虚拟机实例受监控资源与您的数据一起使用,那么您将不需要指标标签来指定实例。如需了解详情,请参阅自定义指标的受监控资源。
每个指标的数据点都必须与一个受监控的资源对象关联。不同受监控资源对象的数据点保存在不同的时间序列中。
自定义指标的受监控资源
您只能在自定义指标中使用以下受监控资源类型。
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
和 location
标签。如果一个项目中有多个指标来源,则使用相同的 global
资源对象可能会导致您的指标数据发生冲突和被覆盖。
创建指标描述符
您为自定义指标收集的数据必须与自定义指标类型的描述符相关联。您可以自行创建指标描述符,或者 Monitoring 可以为您创建指标描述符。
您可以通过有限的方式更改现有描述符;如需了解详情,请参阅修改指标描述符。
自动创建指标描述符
如果您将指标数据写入尚不存在的自定义指标类型,则系统将自动为您创建新的自定义指标类型。 但是,这个新的指标描述符可能不是您想要的;系统在自动创建指标描述符时会做出一些假设,并使用默认值。
具体而言,在调用 timeSeries.create
时,如果 TimeSeries
对象包含指定了不存在的指标类型名称的 Metric
对象,则 Cloud Monitoring 会创建一个具备以下字段的新 MetricDescriptor
:
type
:类型是从Metric
对象的type
字段中复制的。name
:名称是根据方法调用中的项目 ID 以及Metric
对象中type
的值创建的。labels
:标签是Metric
对象中的标签。新指标描述符中的每个标签描述符都具备以下字段:key
:Metric
对象中的标签键。valueType
:STRING
description
:未设置
metricKind
:默认的指标种类为GAUGE
,但如果您指定TimeSeries
对象的metricKind
参数,则新指标将具备该参数指定的种类。您只能指定GAUGE
和CUMULATIVE
种类。valueType
:值类型取自写入的Point
的值类型。必须为BOOL
、INT64
、DOUBLE
或DISTRIBUTION
。如果您在TimeSeries
的valueType
字段中指定值类型,则该类型必须与Point
的类型匹配。unit
:未设置description
:"Auto created custom metric."
。displayName
:未设置
单次 timeSeries.create
调用可以包含多个引用同一个不存在的自定义指标类型的 TimeSeries
对象。在这种情况下,系统会以相同的方式设置新类型的字段,只是新的指标描述符中的标签包含对 create
的本次调用中所有时间序列中的 Metric
对象的所有标签的集合。
下一步:请参阅写入指标数据。
手动创建指标描述符
收集创建自定义指标类型所需的信息后,调用 metricDescriptors.create
方法,并传入 MetricDescriptor
对象。如需了解详情,请参阅修改指标描述符。
使用与现有自定义指标描述符相同的类型名称调用 metricDescriptors.create
通常会导致错误。但是,如果新 MetricDescriptor
对象的所有字段都与现有描述符的字段完全匹配,则不会出现错误,但不会产生任何效果。
在以下示例中,您将创建一个采样平均值自定义指标 custom.googleapis.com/stores/daily_sales
。该指标具有单个维度标签 store_id
。
协议
要创建指标描述符,请使用 metricDescriptors.create
方法。您可以使用方法参考页面上的 API Explorer 微件来执行此方法。 如需了解详情,请参阅 API Explorer。
以下是 metricDescriptors.create
的示例参数:
- 名称(网址):
projects/[PROJECT_ID]
请求正文:提供一个
MetricDescriptor
对象,如下所示:{ "name": "", "description": "Daily sales records from all branch stores.", "displayName": "Sales", "type": "custom.googleapis.com/stores/sales", "metricKind": "CUMULATIVE", "valueType": "DOUBLE", "unit": "{USD}", "labels": [ { "key": "store_id", "valueType": "STRING", "description": "The ID of the store." }, ], }
在微件字段中提供这些值,将 [PROJECT_ID
替换为您的项目 ID:
点击执行按钮以运行该方法。
在创建新的自定义指标时,MetricDescriptor
中的 name
字段会被忽略,因此可以省略。create
方法将返回已填充 name
字段的新指标描述符,在本示例中,该字段如下所示:
"name": "projects/[PROJECT_ID]/metricDescriptors/custom.googleapis.com/stores/daily_sales"
例如,如果您想要获取指标的描述符,则使用此名称。
C#
Go
Java
Node.js
PHP
Python
Ruby
如果遇到困难,请参阅 API 调用问题排查。
下一步:请参阅写入指标数据。
删除指标
要删除自定义指标,请删除其指标描述符。 您无法删除自定义指标中的时间序列数据,但删除指标描述符会导致数据无法访问。数据会根据数据保留政策过期并被系统删除。
要删除自定义指标描述符,请调用 metricDescriptors.delete
方法。
协议
要删除指标描述符,请使用 metricDescriptors.delete
方法。您可以使用方法参考页面上的 API Explorer 微件来执行此方法。 如需了解详情,请参阅 API Explorer。
您只能删除自定义指标类型。
要删除在手动创建指标描述符中创建的 stores/daily_sales
自定义指标,请执行以下操作:
- 转到
metricDescriptors.delete
的参考页面: 将指标描述符的名称提供给 API Explorer 微件。
名称:
projects/[PROJECT_ID]/metricDescriptors/custom.googleapis.com/stores/daily_sales
点击执行按钮。
C#
Go
Java
Node.js
PHP
Python
Ruby
如果遇到困难,请参阅 API 调用问题排查。
写入指标数据
您只能将数据写入自定义指标类型。 要写入数据,请使用 timeSeries.create
方法。如果时间序列已存在,则此方法会将新数据点附加到现有时间系列。如果时间序列不存在,则此方法将创建该时间序列并附加数据。
您可以通过将 TimeSeries
对象列表传递到 timeSeries.create
来写入数据点。列表大小上限为 200,列表中的每个对象都必须指定不同的时间序列:
- 每个时间序列都由
TimeSeries
对象的metric
和resource
字段标识。这些字段表示数据的指标类型以及从中收集数据的受监控资源。 - 省略字段
metricKind
和valueType
;写入数据点时,系统会忽略这两个字段。 每个
TimeSeries
对象只能包含一个Point
个对象:- 该点的值和时段必须与指标类型的定义一致。如需了解不同指标种类的时间间隔,请参阅
TimeInterval
。 - 该点的时段必须晚于时间序列中已有的点。
- 时段的结束时间不得早于 25 小时之前,也不得晚于 5 分钟后。
- 该点的值和时段必须与指标类型的定义一致。如需了解不同指标种类的时间间隔,请参阅
如果要向同一时间序列写入多个点,请对每个点分别使用
timeSeries.create
方法。请勿将数据写入速度超过每 10 秒 1 个数据点的单个时间序列。如果您要将数据点添加到不同的时间序列,则没有速率限制。
协议
要写入数据,请使用 timeSeries.create
方法。您可以使用方法参考页面上的 API Explorer 微件来执行此方法。 如需了解详情,请参阅 API Explorer。
要将数据点写入在手动创建指标描述符中创建的 stores/daily_sales
自定义指标,请执行以下操作:
- 转到
timeSeries.create
的参考页面。 - 将以下参数提供给 API Explorer 微件。
- 点击执行按钮。
使用以下示例参数:
- 名称:
projects/[PROJECT_ID]
请求正文:包含
TimeSeries
对象列表。在以下示例中,列表中只有一个时间序列。{ "timeSeries": [ { "metric": { "type": "custom.googleapis.com/my_metric", "labels": { "my_label": "my_value" } }, "resource": { "type": "gce_instance", "labels": { "project_id": "[PROJECT_ID]", "instance_id": "1234567890123456789", "zone": "us-central1-f" } }, "points": [ { "interval": { "endTime": "2018-06-01T10:00:00-04:00" }, "value": { "doubleValue": 123.45 } } ] } ] }
C#
Go
Java
Node.js
PHP
Python
Ruby
如果遇到困难,请参阅 API 调用问题排查。
修改指标描述符
您还可以使用 timeSeries.create
调用向自定义指标添加新标签。您可以通过将标签包含在时间序列数据中来为自定义指标描述符添加标签。
如果您尝试编写的标签有效,并且不会导致指标描述符中的标签数超过标签限制(10 个),系统即会添加标签。然后写入时间序列数据,就好像标签从一开始就存在一样。
如果您要执行添加新标签以外的操作,必须删除并重新创建指标描述符。在这种情况下,您将丢失先前为旧指标描述符收集的所有时间序列数据。如需详细了解,请参阅删除指标。
您无法重命名指标。