本文档介绍如何使用 Monitoring API 中的 timeSeries.list
方法来读取指标数据,也称为时间序列数据。
本文档不讨论 Monitoring Query Language (MQL) 和 timeSeries.query
方法。如需了解相关信息,请参阅通过 Monitoring API 使用 MQL。
您可以通过多种方式使用 timeSeries.list
方法:
为了在不编写任何代码的情况下运行
list
方法,本页面上的协议标签页中的示例使用基于表单的 API Explorer。(如需详细了解此工具,请参阅 API Explorer。)要了解如何通过选定的编程语言使用
list
方法,请参阅本页面的可运行代码示例。Google Cloud CLI 不支持使用 Google Cloud CLI 读取指标数据。-
如需使用 Metrics Explorer 查看受监控资源的指标,请执行以下操作:
- 在 Google Cloud Console 中,转到 Monitoring 或使用以下按钮:
转到 Monitoring - 在 Monitoring 导航窗格中,点击
Metrics Explorer。
- 在工具栏中,选择浏览器标签页。
- 选择配置标签页。
- 展开选择指标菜单,然后使用子菜单选择资源类型和指标。例如,如需绘制虚拟机的 CPU 利用率图表,请执行以下操作:
- (可选)如需减少显示的菜单选项,请在过滤栏中输入部分指标名称。在此示例中,请输入
utilization
。 - 在活跃资源菜单中,选择虚拟机实例。
- 在活跃指标类别菜单中,选择实例。
- 在活跃指标菜单中,选择 CPU 利用率。
- (可选)如需减少显示的菜单选项,请在过滤栏中输入部分指标名称。在此示例中,请输入
- 在 Google Cloud Console 中,转到 Monitoring 或使用以下按钮:
如需了解指标和时间序列,请参阅指标、时间序列和资源。
概览
每次调用 timeSeries.list
方法都会从单一指标类型返回任意数量的时间序列。例如,如果您使用 Compute Engine,那么对于每个虚拟机实例,compute.googleapis.com/instance/cpu/usage_time
指标类型都有单独的时间序列。
您通过提供以下信息来指定所需的时间序列数据:
- 指定指标类型的过滤条件表达式。或者,过滤器通过指定生成时间序列的资源或指定时间序列中特定标签的值,选择指标的部分时间序列。
- 限制返回多少数据的时间间隔。
- (可选)关于如何合并多个时间序列以生成数据聚合摘要的规范。如需了解详情,请参阅聚合数据中的一些示例。
时间序列过滤条件
通过将时序过滤条件传递给 timeSeries.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
方法会为未指定标签中的每个值组合返回一个时间序列。该方法仅返回包含数据的时间序列。
时间间隔
使用 API 读取数据时,请通过设置开始时间和结束时间来指定要检索数据的时间间隔。API 根据间隔 (start, end]
(即从开始时间到结束时间)检索数据。
开始时间不得晚于结束时间。如果您指定的开始时间晚于结束时间,则 API 会返回错误。
如果您只想检索具有特定时间戳的数据,请将开始时间设置为与结束时间相同,或者不设置开始时间。
时间格式
开始时间和结束时间必须指定为 RFC 3339 格式的字符串。 例如:
2021-09-01T12:34:56+04:00 2021-09-01T12:34:56.992Z
Linux 上的 date -Iseconds
命令对生成时间戳很有用。
基本列表操作
timeSeries.list
方法可用于返回简单的原始数据,也可用于返回已经过复杂处理的数据。本部分列出了一些基本用例。
示例:列出可用的时间序列
此示例显示如何仅列出与过滤条件匹配的时间序列的名称和说明,而不是返回所有可用数据:
协议
以下是 timeSeries.list
的示例参数:
- 名称:
projects/PROJECT_ID
- 过滤条件:
metric.type = "compute.googleapis.com/instance/cpu/utilization"
- interval.startTime:
2021-09-01T00:00:00Z
- interval.endTime:
2021-09-01T00:20:00Z
字段:
timeSeries.metric
如需访问字段参数,请点击显示标准参数。
点击执行按钮之前,将 PROJECT_ID
更改为项目的 ID,并将结束时间调整为最近某个时间,将开始时间调整为早于 20 分钟的时间。
该示例输出显示了两个不同虚拟机实例的时间序列:
{
"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网址 命令、HTTP 请求或 JavaScript 的形式查看请求,请在 API Explorer 中点击 fullscreen 全屏。
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.startTime:
2021-09-01T00:00:00Z
- interval.endTime:
2021-09-01T00:20:00Z
字段:
timeSeries.points.interval.endTime,timeSeries.points.value
如需访问字段参数,请点击显示标准参数。
点击执行按钮之前,将 PROJECT_ID
和 YOUR_INSTANCE_NAME
更改为项目中的值,并将结束时间设置为最近某个时间,将开始时间设置为早于结束时间 20 分钟的时间。
请求将返回如下结果:
{
"timeSeries": [
{
"points": [
{
"interval": {
"endTime": "2021-09-01T00:19:01Z"
},
"value": {
"doubleValue": 0.06763074536575005
}
},
{
"interval": {
"endTime": "2021-09-01T00:18:01Z"
},
"value": {
"doubleValue": 0.06886174467702706
}
},
...
{
"interval": {
"endTime": "2021-09-01T00:17:01Z"
},
"value": {
"doubleValue": 0.06929610064253211
}
}
]
}
]
}
若要以 c网址 命令、HTTP 请求或 JavaScript 的形式查看请求,请在 API Explorer 中点击 fullscreen 全屏。
C#
Go
Java
Node.js
PHP
Python
Ruby
返回的数据包括 20 分钟内每个时间序列中的 20 个数据点,因为 Compute Engine 指标的收集频率是每分钟。如需了解详情,请参阅指标数据的保留和延迟时间。API 以反向时间顺序返回每个时间序列中的数据点,此类点排序没有覆盖。
如果遇到困难,请参阅排查 API 调用问题。
聚合数据
timeSeries.list
方法可对返回的时间序列数据执行统计聚合和缩减。以下部分展示了两个示例。如需了解更多选项,请参阅该方法的文档。
示例:校准时间序列
此示例将各个时间序列中的 20 个独立的利用率测量结果缩减为 2 个测量结果:20 分钟间隔中两个 10 分钟时间段的平均利用率。来自各个时间序列的数据首先校准到 10 分钟时间段,然后对每个 10 分钟时间段中的值进行均值计算。
该示例将各个时间序列的 20 个测量结果按时间序列分成两组。此操作有两个优势:可以缩减数据,还可以将所有时间序列中的数据校准至准确的 10 分钟间隔。然后,您可以进一步处理数据。
协议
以下是 timeSeries.list
的示例参数:
- 名称:
projects/PROJECT_ID
- aggregation.alignmentPeriod:
600s
- aggregation.perSeriesAligner:
ALIGN_MEAN
- 过滤条件:
metric.type = "compute.googleapis.com/instance/cpu/utilization"
- interval.startTime:
2021-09-01T00:00:00Z
- interval.endTime:
2021-09-01T00: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": "2021-09-01T00:20:00.000Z",
"endTime": "2021-09-01T00:20:00.000Z"
},
"value": { "doubleValue": 0.06688481346044381 }
},
{
"interval": {
"startTime": "2021-09-01T00:10:00.000Z",
"endTime": "2021-09-01T00:10:00.000Z"
},
"value": {"doubleValue": 0.06786652821310177 }
}
]
},
{
"metric": {
"labels": { "instance_name": "your-second-instance" },
"type": "compute.googleapis.com/instance/cpu/utilization"
},
"points": [
{
"interval": {
"startTime": "2021-09-01T00:20:00.000Z",
"endTime": "2021-09-01T00:20:00.000Z"
},
"value": { "doubleValue": 0.04144239874207415 }
},
{
"interval": {
"startTime": "2021-09-01T00:10:00.000Z",
"endTime": "2021-09-01T00:10:00.000Z"
},
"value": { "doubleValue": 0.04045793689050091 }
}
]
},
{
"metric": {
"labels": { "instance_name": "your-third-instance" },
"type": "compute.googleapis.com/instance/cpu/utilization"
},
"points": [
{
"interval": {
"startTime": "2021-09-01T00:20:00.000Z",
"endTime": "2021-09-01T00:20:00.000Z"
},
"value": { "doubleValue": 0.029650046587339607 }
},
{
"interval": {
"startTime": "2021-09-01T00:10:00.000Z",
"endTime": "2021-09-01T00:10:00.000Z"
},
"value": { "doubleValue": 0.03053874224715402 }
}
]
}
]
}
若要以 c网址 命令、HTTP 请求或 JavaScript 的形式查看请求,请在 API Explorer 中点击 fullscreen 全屏。
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:
2021-09-01T00:00:00Z
- interval.end_time:
2021-09-01T00:20:00Z
字段:
timeSeries.metric,timeSeries.points
如需访问字段参数,请点击显示标准参数。
点击执行按钮之前,将 PROJECT_ID
更改为项目的 ID,并将结束时间调整为最近某个时间,将开始时间调整为早于结束时间 20 分钟的时间。
以下示例结果只有一个时间序列和两个数据点。每个数据点是相应时间段内三个虚拟机实例的平均利用率:
{
"timeSeries": [
{
"metric": {
"type": "compute.googleapis.com/instance/cpu/utilization"
},
"points": [
{
"interval": {
"startTime": "2021-09-01T00:20:00.000Z",
"endTime": "2021-09-01T00:20:00.000Z"
},
"value": {
"doubleValue": 0.045992419596619184
}
},
{
"interval": {
"startTime": "2021-09-01T00:10:00.000Z",
"endTime": "2021-09-01T00:10:00.000Z"
},
"value": {
"doubleValue": 0.04628773578358556
}
}
]
}
]
}
若要以 c网址 命令、HTTP 请求或 JavaScript 的形式查看请求,请在 API Explorer 中点击 fullscreen 全屏。
C#
Go
Java
Node.js
PHP
Python
Ruby
如果遇到困难,请参阅排查 API 调用问题。