本页面介绍如何使用 Monitoring API 中的 timeSeries.list
方法来读取指标数据,也称为时间序列数据。
本页面不讨论 Monitoring Query Language (MQL) 和 timeSeries.query
方法。如需了解相关信息,请参阅通过 Monitoring API 使用 MQL。
您可以通过多种方式使用 timeSeries.list
方法:
为了在不编写任何代码的情况下运行
list
方法,本页面上的协议标签页中的示例使用基于表单的 API Explorer。(如需详细了解此工具,请参阅 API Explorer。)要了解如何通过选定的编程语言使用
list
方法,请参阅本页面的可运行代码示例。Cloud SDK 不支持使用gcloud
命令行工具读取指标数据。-
如需使用 Metrics Explorer 查看受监控资源的指标,请执行以下操作:
- 在 Google Cloud Console 中,转到 Monitoring 或使用下面的按钮:
转到 Monitoring - 在 Monitoring 导航窗格中,点击
Metrics Explorer。
- 在查找资源类型和指标文本框中输入受监控资源的名称。
- 在 Google Cloud Console 中,转到 Monitoring 或使用下面的按钮:
如需了解指标和时间序列,请参阅指标、时间序列和资源。
概览
每次调用 timeSeries.list
方法都会从单一指标类型返回任意数量的时间序列。例如,如果您使用 Compute Engine,那么对于每个虚拟机实例,compute.googleapis.com/instance/cpu/usage_time
指标类型都有单独的时间序列。
您通过提供以下信息来指定所需的时间序列数据:
- 指定指标类型的过滤条件表达式。或者,过滤器通过指定生成时间序列的资源或指定时间序列中特定标签的值,选择指标的部分时间序列。
- 限制返回多少数据的时间间隔。
- (可选)关于如何合并多个时间序列以生成数据聚合摘要的规范。如需了解详情,请参阅聚合数据中的一些示例。
时间序列过滤条件
通过将时间序列过滤条件传递给 list
方法,可指定要检索的时间序列。以下是常见的过滤条件组成成分:
过滤条件必须指定单个指标类型。例如:
metric.type = "compute.googleapis.com/instance/cpu/usage_time"
要检索自定义指标,请将过滤条件中的 metric.type 前缀更改为
custom.googleapis.com
或另一个可能使用的前缀(常用的是external.googleapis.com
)。过滤条件可为指标的维度标签指定值。指标类型决定了存在哪些标签。例如:
(metric.label.instance_name = "your-instance-id" OR metric.label.instance_name = "your-other-instance-id")
请注意,虽然实际指标对象使用
labels
作为其键,但label
是正确的。过滤条件可以将时间序列限制为包含特定受监控的资源类型的时间序列:
resource.type = "gae_app"
过滤条件组成成分可合并到单个时间序列过滤条件中,如下所示:
metric.type = "compute.googleapis.com/instance/cpu/usage_time"
AND (metric.label.instance_name = "your-instance-id" OR
metric.label.instance_name = "your-other-instance-id")
如果您没有为所有指标标签指定值,则 list
方法会为未指定标签中的每个值组合返回时间序列。该方法仅返回包含数据的时间序列。
时间间隔
调用 timeSeries.list
方法时,您必须指定 interval.startTime 和 interval.endTime。所产生的时间段包含结束时间,但不包含开始时间,除非二者相同。这可能有点让人迷惑不解。例如,请考虑以下 (start, end]
间隔示例:
(T, T+1]
- 该间隔不包含 T。
(T-1, T]
- 该间隔包含 T。
(T, T]
- 这种情况较为特殊,也不常见,该间隔仅包含时间 T。如果您省略开始时间,这就是您获得的时间间隔。
时间间隔中的值
开始时间和结束时间必须指定为 RFC 3339 格式的字符串。例如:
2018-05-11T12:34:56+04:00 2018-05-11T12:34:56.992Z
Linux 上的 date -Iseconds
命令对生成时间戳很有用。
时间间隔中的范围
时间间隔由开始时间和结束时间指定,但 API 并不强制要求指定开始时间。开始时间若未指定,则默认与结束时间相同。这么做仅符合测量时间点的 GAUGE
指标的语义规则。
如果您的指标是 CUMULATIVE
或 DELTA
,那么该方法将测量累积值或随时间的变化。对于“随时间的变化”指标,必须同时提供间隔的开始时间和结束时间,并且开始时间必须早于结束时间。
如需了解详情,请参阅指标的种类。
基本列表操作
timeSeries.list
方法可用于返回简单的原始数据,也可用于返回已经过复杂处理的数据。本部分列出了一些基本用例。
示例:列出可用的时间序列
此示例显示如何仅列出与过滤条件匹配的时间序列的名称和说明,而不是返回所有可用数据:
协议
以下是 timeSeries.list
的示例参数:
- 名称:
projects/[PROJECT_ID]
- 过滤条件:
metric.type = "compute.googleapis.com/instance/cpu/utilization"
- interval.start_time:
2018-05-11T00:00:00Z
- interval.end_time:
2018-05-11T00:20:00Z
- 字段:
timeSeries.metric
点击执行按钮之前,将 [PROJECT_ID]
更改为您的项目 ID。
该示例输出显示了两个不同虚拟机实例的时间序列:
{
"timeSeries": [
{
"metric": {
"labels": {
"instance_name": "your-first-instance"
},
"type": "compute.googleapis.com/instance/cpu/utilization"
},
},
{
"metric": {
"labels": {
"instance_name": "your-second-instance"
},
"type": "compute.googleapis.com/instance/cpu/utilization"
},
}
]
}
C#
Go
Java
Node.js
PHP
Python
Ruby
如果遇到困难,请参阅 API 调用问题排查。
示例:获取时间序列数据
此示例返回过去 20 分钟内来自 Compute Engine 实例的 timeSeries.list
请求的所有可用信息(包括指标数据)。
协议
协议示例进一步对输出进行限制,以使返回的数据在响应框中更易于管理。此示例使用不同的字段值:
- filter 值现在将时间序列限制为单个虚拟机实例。
- fields 值现在仅指定测量结果的时间和值。
这些值将限制结果中返回的时间序列数据量。
以下是 timeSeries.list
的示例参数:
- 名称:
projects/[PROJECT_ID]
- 过滤条件:
metric.type = "compute.googleapis.com/instance/cpu/utilization" AND metric.label.instance_name = "[YOUR_INSTANCE_NAME]"
- interval.start_time:
2018-05-11T00:00:00Z
- interval.end_time:
2018-05-11T00:20:00Z
- 字段:
timeSeries.points.interval.endTime,timeSeries.points.value
在点击执行按钮之前,将 [PROJECT_ID]
和 [YOUR_INSTANCE_NAME
] 更改为项目中的值,并将结束时间设置为最近某个时间,将开始时间设置为早于结束时间 20 分钟的时间。
请求将返回如下结果:
{
"timeSeries": [
{
"points": [
{
"interval": {
"endTime": "2018-05-T00:19:01Z"
},
"value": {
"doubleValue": 0.06763074536575005
}
},
{
"interval": {
"endTime": "2018-05-11T00:18:01Z"
},
"value": {
"doubleValue": 0.06886174467702706
}
},
...
{
"interval": {
"endTime": "2018-05-11T00:17:01Z"
},
"value": {
"doubleValue": 0.06929610064253211
}
}
]
}
]
}
C#
Go
Java
Node.js
PHP
Python
Ruby
返回的数据包括 20 分钟内每个时间序列中的 20 个数据点,因为 Compute Engine 指标的收集频率是每分钟。如需了解详情,请参阅指标数据的保留和延迟时间。API 以反向时间顺序返回每个时间序列中的数据点,此类点排序没有覆盖。
如果遇到困难,请参阅 API 调用问题排查。
聚合数据
timeSeries.list
方法可对返回的时间序列数据执行统计聚合和缩减。以下部分展示了两个示例。如需了解更多选项,请参阅该方法的文档。
示例:校准时间序列
此示例将各个时间序列中的 20 个独立的利用率测量结果缩减为两个测量结果:20 分钟间隔中两个 10 分钟时间段的平均利用率。来自各个时间序列的数据首先校准到 10 分钟(600 秒)时间段,然后对每个 10 分钟时间段中的值进行均值计算。
该示例将各个时间序列的 20 个测量结果按时间序列分成两组。此操作有两个优势:可以缩减数据,还可以将所有时间序列中的数据校准至准确的 10 分钟间隔。 然后,您可以进一步处理数据。
协议
以下是 timeSeries.list
的示例参数:
- 名称:
projects/[PROJECT_ID]
- aggregation.alignmentPeriod:
600s
- aggregation.perSeriesAligner:
ALIGN_MEAN
- 过滤条件:
metric.type = "compute.googleapis.com/instance/cpu/utilization"
- interval.start_time:
2018-05-11T00:00:00Z
- interval.end_time:
2018-05-11T00:20:00Z
- 字段:
timeSeries.metric,timeSeries.points
上一个示例中显示的针对单个实例的过滤条件将被删除:此查询返回的数据少得多,因此不需要将其限制为一个虚拟机实例。
点击执行按钮之前,将 [PROJECT_ID]
更改为项目的 ID,并将结束时间调整为最近某个时间,将开始时间调整为早于结束时间 20 分钟的时间。
以下示例结果为三个虚拟机实例中的每一个提供一个时间序列。每个时间序列具有两个数据点,即 10 分钟校准时间段的平均利用率:
{
"timeSeries": [
{
"metric": {
"labels": {"instance_name": "your-first-instance"},
"type": "compute.googleapis.com/instance/cpu/utilization"
},
"points": [
{
"interval": {
"startTime": "2018-05-04T14:00:00.000Z",
"endTime": "2018-05-04T14:00:00.000Z"
},
"value": { "doubleValue": 0.06688481346044381 }
},
{
"interval": {
"startTime": "2018-05-04T13:50:00.000Z",
"endTime": "2018-05-04T13:50:00.000Z"
},
"value": {"doubleValue": 0.06786652821310177 }
}
]
},
{
"metric": {
"labels": { "instance_name": "your-second-instance" },
"type": "compute.googleapis.com/instance/cpu/utilization"
},
"points": [
{
"interval": {
"startTime": "2018-05-04T14:00:00.000Z",
"endTime": "2018-05-04T14:00:00.000Z"
},
"value": { "doubleValue": 0.04144239874207415 }
},
{
"interval": {
"startTime": "2018-05-04T13:50:00.000Z",
"endTime": "2018-05-04T13:50:00.000Z"
},
"value": { "doubleValue": 0.04045793689050091 }
}
]
},
{
"metric": {
"labels": { "instance_name": "your-third-instance" },
"type": "compute.googleapis.com/instance/cpu/utilization"
},
"points": [
{
"interval": {
"startTime": "2018-05-04T14:00:00.000Z",
"endTime": "2018-05-04T14:00:00.000Z"
},
"value": { "doubleValue": 0.029650046587339607 }
},
{
"interval": {
"startTime": "2018-05-04T13:50:00.000Z",
"endTime": "2018-05-04T13:50:00.000Z"
},
"value": { "doubleValue": 0.03053874224715402 }
}
]
}
]
}
C#
Go
Java
Node.js
PHP
Python
Ruby
如果遇到困难,请参阅 API 调用问题排查。
示例:跨多个时间序列进行缩减
此示例进一步扩展了上一示例,将三个虚拟机实例中的已校准时间序列合并为单个时间序列,以测量所有实例的平均利用率。
协议
以下是 timeSeries.list
的示例参数,aggregation.crossSeriesReducer:
- 名称:
projects/[PROJECT_ID]
- aggregation.alignmentPeriod:
600s
- aggregation.crossSeriesReducer:
REDUCE_MEAN
- aggregation.perSeriesAligner:
ALIGN_MEAN
- 过滤条件:
metric.type = "compute.googleapis.com/instance/cpu/utilization"
- interval.start_time:
2018-05-11T00:00:00Z
- interval.end_time:
2018-05-11T00:20:00Z
- 字段:
timeSeries.metric,timeSeries.points
点击执行按钮之前,将 [PROJECT_ID]
更改为项目的 ID,并将结束时间调整为最近某个时间,将开始时间调整为早于结束时间 20 分钟的时间。
以下示例结果只有一个时间序列和两个数据点。每个数据点是相应时间段内三个虚拟机实例的平均利用率:
{
"timeSeries": [
{
"metric": {
"type": "compute.googleapis.com/instance/cpu/utilization"
},
"points": [
{
"interval": {
"startTime": "2018-05-04T14:00:00.000Z",
"endTime": "2018-05-04T14:00:00.000Z"
},
"value": {
"doubleValue": 0.045992419596619184
}
},
{
"interval": {
"startTime": "2018-05-04T13:50:00.000Z",
"endTime": "2018-05-04T13:50:00.000Z"
},
"value": {
"doubleValue": 0.04628773578358556
}
}
]
}
]
}
C#
Go
Java
Node.js
PHP
Python
Ruby
如果遇到困难,请参阅 API 调用问题排查。