本文档介绍了如何使用 Monitoring API 中的 timeSeries.list
方法读取指标数据(也称为时间序列数据)。
您可以通过多种方式调用 timeSeries.list
方法:
- 您可以通过此页面上的协议标签页来使用基于表单的 API Explorer。
- 您可以使用特定语言的客户端库。
- 您可以使用 Metrics Explorer。
读取指标数据的另一种方法是向 timeSeries.query
方法发送一个命令,该方法需要使用 Monitoring Query Language (MQL)。本文档不介绍 MQL 或 timeSeries.query
方法。如需了解这些主题,请参阅使用 timeSeries.query
检索数据。
概览
每次调用 timeSeries.list
方法都会从单一指标类型返回任意数量的时序。例如,如果您使用的是 Compute Engine,则 compute.googleapis.com/instance/cpu/usage_time
指标类型会为每个虚拟机实例提供单独的时序。如需了解指标和时序,请参阅指标、时序和资源。
您可以通过向 timeSeries.list
方法提供以下信息来指定所需的时间序列数据:
- 指定指标类型的过滤条件表达式。或者,过滤器通过指定生成时序的资源或指定时序中特定标签的值,选择指标的部分时序。
- 限制返回多少数据的时间间隔。
- (可选)关于如何合并多个时序以生成数据聚合摘要的规范。如需了解详情和示例,请参阅汇总数据。
时间序列过滤条件
通过将时序过滤条件传递给 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 = "gce_instance"
过滤条件组成成分可合并到单个时序过滤条件中,如下所示:
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 格式的字符串。 例如:
2024-03-01T12:34:56+04:00 2024-03-01T12:34:56.992Z
Linux 上的 date -Iseconds
命令对生成时间戳很有用。
基本列表操作
timeSeries.list
方法可用于返回简单的原始数据,也可用于返回经过高度处理的数据。本部分介绍了如何列出可用的时序,以及如何获取特定时序中的值。
示例:列出可用的时序
此示例显示如何仅列出与过滤条件匹配的时间序列的名称和说明,而不是返回所有可用数据:
协议
打开
timeSeries.list
参考页面。在标有 Try this method(尝试此方法)的窗格中,输入以下内容:
-
name:输入项目的路径。
projects/PROJECT_ID
-
filter:指定指标类型。
metric.type = "compute.googleapis.com/instance/cpu/utilization"
- interval.endTime:输入结束时间。
- interval.startTime:输入开始时间,并确保该时间比结束时间早 20 分钟。
点击显示标准参数,然后在字段中输入以下内容:
timeSeries.metric
-
name:输入项目的路径。
点击执行。
该示例输出显示了两个不同虚拟机实例的时序:
{
"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"
},
}
]
}
如需以 curl
命令、HTTP 请求或 JavaScript 的形式查看请求,请点击 API Explorer 中的 fullscreen 全屏。
C#
如需向 Monitoring 进行身份验证,请设置应用默认凭据。 如需了解详情,请参阅为本地开发环境设置身份验证。
Go
如需向 Monitoring 进行身份验证,请设置应用默认凭据。 如需了解详情,请参阅为本地开发环境设置身份验证。
Java
如需向 Monitoring 进行身份验证,请设置应用默认凭据。 如需了解详情,请参阅为本地开发环境设置身份验证。
Node.js
如需向 Monitoring 进行身份验证,请设置应用默认凭据。 如需了解详情,请参阅为本地开发环境设置身份验证。
PHP
如需向 Monitoring 进行身份验证,请设置应用默认凭据。 如需了解详情,请参阅为本地开发环境设置身份验证。
Python
如需向 Monitoring 进行身份验证,请设置应用默认凭据。 如需了解详情,请参阅为本地开发环境设置身份验证。
Ruby
如需向 Monitoring 进行身份验证,请设置应用默认凭据。 如需了解详情,请参阅为本地开发环境设置身份验证。
如果遇到困难,请参阅排查 Monitoring API 问题。
示例:获取时序数据
此示例返回以 20 分钟间隔为特定 Compute Engine 实例记录的 CPU 利用率测量结果。返回的数据量取决于指标的采样率。由于 CPU 利用率每分钟采样一次,因此此查询的结果约为 20 个数据点。当针对一个时序返回多个数据点时,API 会以反向时间顺序返回每个时序中的数据点;此点排序没有替换项。
协议
协议示例进一步限制了输出,使返回的数据在响应框中更易于管理:
- filter 值将时序限制为单个虚拟机实例。
- fields 值仅指定测量结果的时间和值。
这些设置将限制结果中返回的时序数据量。
打开
timeSeries.list
参考页面。在标有 Try this method(尝试此方法)的窗格中,输入以下内容:
-
name:输入项目的路径。
projects/PROJECT_ID
filter:指定指标类型。
metric.type = "compute.googleapis.com/instance/cpu/utilization" AND metric.label.instance_name = "INSTANCE_NAME"
interval.endTime:输入结束时间。
interval.startTime:输入开始时间,并确保该时间比结束时间早 20 分钟。
点击显示标准参数,然后在字段中输入以下内容:
timeSeries.points.interval.endTime,timeSeries.points.value
-
name:输入项目的路径。
点击执行。
请求将返回如下结果:
{
"timeSeries": [
{
"points": [
{
"interval": {
"endTime": "2024-03-01T00:19:01Z"
},
"value": {
"doubleValue": 0.06763074536575005
}
},
{
"interval": {
"endTime": "2024-03-01T00:18:01Z"
},
"value": {
"doubleValue": 0.06886174467702706
}
},
...
{
"interval": {
"endTime": "2024-03-01T00:17:01Z"
},
"value": {
"doubleValue": 0.06929610064253211
}
}
]
}
]
}
如需以 curl
命令、HTTP 请求或 JavaScript 的形式查看请求,请点击 API Explorer 中的 fullscreen 全屏。
C#
如需向 Monitoring 进行身份验证,请设置应用默认凭据。 如需了解详情,请参阅为本地开发环境设置身份验证。
Go
如需向 Monitoring 进行身份验证,请设置应用默认凭据。 如需了解详情,请参阅为本地开发环境设置身份验证。
Java
如需向 Monitoring 进行身份验证,请设置应用默认凭据。 如需了解详情,请参阅为本地开发环境设置身份验证。
Node.js
如需向 Monitoring 进行身份验证,请设置应用默认凭据。 如需了解详情,请参阅为本地开发环境设置身份验证。
PHP
如需向 Monitoring 进行身份验证,请设置应用默认凭据。 如需了解详情,请参阅为本地开发环境设置身份验证。
Python
如需向 Monitoring 进行身份验证,请设置应用默认凭据。 如需了解详情,请参阅为本地开发环境设置身份验证。
Ruby
如需向 Monitoring 进行身份验证,请设置应用默认凭据。 如需了解详情,请参阅为本地开发环境设置身份验证。
如果遇到困难,请参阅排查 Monitoring API 问题。
聚合数据
timeSeries.list
方法可对返回的时间序列数据执行统计聚合和缩减。以下部分展示了两个示例。
如需了解详情,请参阅过滤和聚合:操控时序。
示例:校准时序
此示例将各个时间序列中的 20 个独立的利用率测量结果缩减为 2 个测量结果:20 分钟间隔中两个 10 分钟时间段的平均利用率。来自各个时序的数据首先校准到 10 分钟时间段,然后对每个 10 分钟时间段中的值进行均值计算。
校准操作有两个优势:它可以使数据变得平滑,并且它会精确地在 10 分钟的边界上校准来自所有时间序列数据的数据。校准后的数据可以得到进一步处理。
协议
打开
timeSeries.list
参考页面。在标有 Try this method(尝试此方法)的窗格中,输入以下内容:
-
name:输入项目的路径。
projects/PROJECT_ID
-
aggregation.alignmentPeriod:输入
600s
-
aggregation.perSeriesAligner:选择
ALIGN_MEAN
-
filter:指定指标类型。
metric.type = "compute.googleapis.com/instance/cpu/utilization"
- interval.endTime:输入结束时间。
- interval.startTime:输入开始时间,并确保该时间比结束时间早 20 分钟。
-
点击显示标准参数,然后在字段中输入以下内容:
timeSeries.metric,timeSeries.points
-
name:输入项目的路径。
点击执行。
上一个示例中显示的针对单个实例的过滤条件将被删除:此查询返回的数据少得多,因此不需要将其限制为一个虚拟机实例。
以下示例结果为三个虚拟机实例中的每一个提供一个时序。每个时序具有两个数据点,即 10 分钟校准时间段的平均利用率:
{
"timeSeries": [
{
"metric": {
"labels": {"instance_name": "your-first-instance"},
"type": "compute.googleapis.com/instance/cpu/utilization"
},
"points": [
{
"interval": {
"startTime": "2024-03-01T00:20:00.000Z",
"endTime": "2024-03-01T00:20:00.000Z"
},
"value": { "doubleValue": 0.06688481346044381 }
},
{
"interval": {
"startTime": "2024-03-01T00:10:00.000Z",
"endTime": "2024-03-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": "2024-03-01T00:20:00.000Z",
"endTime": "2024-03-01T00:20:00.000Z"
},
"value": { "doubleValue": 0.04144239874207415 }
},
{
"interval": {
"startTime": "2024-03-01T00:10:00.000Z",
"endTime": "2024-03-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": "2024-03-01T00:20:00.000Z",
"endTime": "2024-03-01T00:20:00.000Z"
},
"value": { "doubleValue": 0.029650046587339607 }
},
{
"interval": {
"startTime": "2024-03-01T00:10:00.000Z",
"endTime": "2024-03-01T00:10:00.000Z"
},
"value": { "doubleValue": 0.03053874224715402 }
}
]
}
]
}
如需以 curl
命令、HTTP 请求或 JavaScript 的形式查看请求,请点击 API Explorer 中的 fullscreen 全屏。
C#
如需向 Monitoring 进行身份验证,请设置应用默认凭据。 如需了解详情,请参阅为本地开发环境设置身份验证。
Go
如需向 Monitoring 进行身份验证,请设置应用默认凭据。 如需了解详情,请参阅为本地开发环境设置身份验证。
Java
如需向 Monitoring 进行身份验证,请设置应用默认凭据。 如需了解详情,请参阅为本地开发环境设置身份验证。
Node.js
如需向 Monitoring 进行身份验证,请设置应用默认凭据。 如需了解详情,请参阅为本地开发环境设置身份验证。
PHP
如需向 Monitoring 进行身份验证,请设置应用默认凭据。 如需了解详情,请参阅为本地开发环境设置身份验证。
Python
如需向 Monitoring 进行身份验证,请设置应用默认凭据。 如需了解详情,请参阅为本地开发环境设置身份验证。
Ruby
如需向 Monitoring 进行身份验证,请设置应用默认凭据。 如需了解详情,请参阅为本地开发环境设置身份验证。
如果遇到困难,请参阅排查 Monitoring API 问题。
示例:跨多个时序进行缩减
此示例进一步扩展了上一示例,将三个虚拟机实例中的已校准时序合并为单个时序,以测量所有实例的平均利用率。
协议
打开
timeSeries.list
参考页面。在标有 Try this method(尝试此方法)的窗格中,输入以下内容:
-
name:输入项目的路径。
projects/PROJECT_ID
-
aggregation.alignmentPeriod:输入
600s
-
aggregation.perSeriesAligner:选择
ALIGN_MEAN
-
aggregation.crossSeriesReducer:选择
REDUCE_MEAN
-
filter:指定指标类型。
metric.type = "compute.googleapis.com/instance/cpu/utilization"
- interval.endTime:输入结束时间。
- interval.startTime:输入开始时间,并确保该时间比结束时间早 20 分钟。
-
点击显示标准参数,然后在字段中输入以下内容:
timeSeries.metric,timeSeries.points
-
name:输入项目的路径。
点击执行。
以下示例结果只有一个时序和两个数据点。每个数据点是相应时间段内三个虚拟机实例的平均利用率:
{
"timeSeries": [
{
"metric": {
"type": "compute.googleapis.com/instance/cpu/utilization"
},
"points": [
{
"interval": {
"startTime": "2024-03-01T00:20:00.000Z",
"endTime": "2024-03-01T00:20:00.000Z"
},
"value": {
"doubleValue": 0.045992419596619184
}
},
{
"interval": {
"startTime": "2024-03-01T00:10:00.000Z",
"endTime": "2024-03-01T00:10:00.000Z"
},
"value": {
"doubleValue": 0.04628773578358556
}
}
]
}
]
}
如需以 curl
命令、HTTP 请求或 JavaScript 的形式查看请求,请点击 API Explorer 中的 fullscreen 全屏。
C#
如需向 Monitoring 进行身份验证,请设置应用默认凭据。 如需了解详情,请参阅为本地开发环境设置身份验证。
Go
如需向 Monitoring 进行身份验证,请设置应用默认凭据。 如需了解详情,请参阅为本地开发环境设置身份验证。
Java
如需向 Monitoring 进行身份验证,请设置应用默认凭据。 如需了解详情,请参阅为本地开发环境设置身份验证。
Node.js
如需向 Monitoring 进行身份验证,请设置应用默认凭据。 如需了解详情,请参阅为本地开发环境设置身份验证。
PHP
如需向 Monitoring 进行身份验证,请设置应用默认凭据。 如需了解详情,请参阅为本地开发环境设置身份验证。
Python
如需向 Monitoring 进行身份验证,请设置应用默认凭据。 如需了解详情,请参阅为本地开发环境设置身份验证。
Ruby
如需向 Monitoring 进行身份验证,请设置应用默认凭据。 如需了解详情,请参阅为本地开发环境设置身份验证。
如果遇到困难,请参阅排查 Monitoring API 问题。
后续步骤
- 了解指标数据的保留和延迟时间。
- 了解过滤和聚合:操控时序。