本文档介绍了如何读取指标数据(也称为时间序列数据),
使用 timeSeries.list
方法,
Monitoring API。
您可以通过以下几种方式调用 timeSeries.list
方法:
- 您可以通过此页面上的协议标签页来使用基于表单的 APIs Explorer。
- 您可以使用特定于语言的客户端库。
- 您可以使用 Metrics Explorer。
读取指标数据的另一种方法是向
timeSeries.query
方法,
该 API 需要使用 Monitoring Query Language (MQL)。本文档未对以下内容进行描述
MQL 或 timeSeries.query
方法。有关
主题,请参阅
使用 timeSeries.query
检索数据。
概览
每次调用 timeSeries.list
方法都会从单一指标类型返回任意数量的时间序列。例如,如果你是
则 compute.googleapis.com/instance/cpu/usage_time
每个虚拟机实例都有单独的时序。
如需了解指标和时间序列,请参阅指标、时间序列和资源。
您可以通过向 timeSeries.list
方法提供以下信息来指定所需的时间序列数据:
- 指定指标类型的过滤条件表达式。或者,过滤器通过指定生成时间序列的资源或指定时间序列中特定标签的值,选择指标的部分时间序列。
- 限制返回多少数据的时间间隔。
- (可选)关于如何合并多个时间序列以生成数据聚合摘要的规范。如需更多信息和 示例,请参阅汇总数据。
时间序列过滤条件
通过将时序过滤条件传递给 timeSeries.list
方法,可指定要检索的时序。下面列出了常见的过滤条件组成部分:
过滤条件必须指定单个指标类型。例如:
metric.type = "compute.googleapis.com/instance/cpu/usage_time"
要检索用户定义的指标,请更改 将过滤条件更改为
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
参考页面。在标有尝试此方法的窗格中,输入以下内容:
-
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 中,点击 fullscreen 全屏
。
C#
如需向 Monitoring 进行身份验证,请设置应用默认凭据。 如需了解详情,请参阅为本地开发环境设置身份验证。
Go
如需向 Monitoring 进行身份验证,请设置应用默认凭据。 如需了解详情,请参阅为本地开发环境设置身份验证。
Java
如需向 Monitoring 进行身份验证,请设置应用默认凭据。 如需了解详情,请参阅为本地开发环境设置身份验证。
Node.js
如需向 Monitoring 进行身份验证,请设置应用默认凭据。 如需了解详情,请参阅为本地开发环境设置身份验证。
PHP
如需向 Monitoring 进行身份验证,请设置应用默认凭据。 如需了解详情,请参阅为本地开发环境设置身份验证。
Python
如需向 Monitoring 进行身份验证,请设置应用默认凭据。 如需了解详情,请参阅为本地开发环境设置身份验证。
Ruby
如需向 Monitoring 进行身份验证,请设置应用默认凭据。 如需了解详情,请参阅为本地开发环境设置身份验证。
如果您遇到困难,请参阅 排查 Monitoring API 问题。
示例:获取时间序列数据
此示例返回在 特定 Compute Engine 实例以 20 分钟为间隔。返回的数据量取决于指标的抽样率。由于 系统每分钟对 CPU 利用率进行采样, 大约有 20 个数据点如果有多个数据点 那么 API 会返回每个 按反向时间顺序排列的时序;此点排序没有替换项。
协议
协议示例进一步限制了输出,以使返回的 更容易在响应框中管理数据:
- filter 值将时序限制为单个虚拟机实例。
- fields 值仅指定 测量结果。
这些设置将限制结果中返回的时间序列数据量。
打开
timeSeries.list
参考页面。在标有尝试此方法的窗格中,输入以下内容:
-
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 中,点击 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
参考页面。在标有尝试此方法的窗格中,输入以下内容:
-
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 中,点击 fullscreen 全屏
。
C#
如需向 Monitoring 进行身份验证,请设置应用默认凭据。 如需了解详情,请参阅为本地开发环境设置身份验证。
Go
如需向 Monitoring 进行身份验证,请设置应用默认凭据。 如需了解详情,请参阅为本地开发环境设置身份验证。
Java
如需向 Monitoring 进行身份验证,请设置应用默认凭据。 如需了解详情,请参阅为本地开发环境设置身份验证。
Node.js
如需向 Monitoring 进行身份验证,请设置应用默认凭据。 如需了解详情,请参阅为本地开发环境设置身份验证。
PHP
如需向 Monitoring 进行身份验证,请设置应用默认凭据。 如需了解详情,请参阅为本地开发环境设置身份验证。
Python
如需向 Monitoring 进行身份验证,请设置应用默认凭据。 如需了解详情,请参阅为本地开发环境设置身份验证。
Ruby
如需向 Monitoring 进行身份验证,请设置应用默认凭据。 如需了解详情,请参阅为本地开发环境设置身份验证。
如果您遇到困难,请参阅 排查 Monitoring API 问题。
示例:跨多个时间序列进行缩减
此示例进一步扩展了上一示例,将三个虚拟机实例中的已校准时间序列合并为单个时间序列,以测量所有实例的平均利用率。
协议
打开
timeSeries.list
参考页面。在标有尝试此方法的窗格中,输入以下内容:
-
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 中,点击 fullscreen 全屏
。
C#
如需向 Monitoring 进行身份验证,请设置应用默认凭据。 如需了解详情,请参阅为本地开发环境设置身份验证。
Go
如需向 Monitoring 进行身份验证,请设置应用默认凭据。 如需了解详情,请参阅为本地开发环境设置身份验证。
Java
如需向 Monitoring 进行身份验证,请设置应用默认凭据。 如需了解详情,请参阅为本地开发环境设置身份验证。
Node.js
如需向 Monitoring 进行身份验证,请设置应用默认凭据。 如需了解详情,请参阅为本地开发环境设置身份验证。
PHP
如需向 Monitoring 进行身份验证,请设置应用默认凭据。 如需了解详情,请参阅为本地开发环境设置身份验证。
Python
如需向 Monitoring 进行身份验证,请设置应用默认凭据。 如需了解详情,请参阅为本地开发环境设置身份验证。
Ruby
如需向 Monitoring 进行身份验证,请设置应用默认凭据。 如需了解详情,请参阅为本地开发环境设置身份验证。
如果您遇到困难,请参阅 排查 Monitoring API 问题。
后续步骤
- 了解指标数据的保留和延迟时间。
- 了解 过滤和聚合:处理时序。