查询监控数据
功能介绍
查询指定时间范围指定指标的指定粒度的监控数据，可以通过参数指定需要查询的数据维度。
调试
您可以在API Explorer中调试该接口，支持自动认证鉴权。API Explorer可以自动生成SDK代码示例，并提供SDK代码示例调试功能。
URI
GET /V1.0/{project_id}/metric-data
样例：
GET /V1.0/{project_id}/metric-data?namespace={namespace}&metric_name={metric_name}&dim.{i}=key,value&from={from}&to={to}&period={period}&filter={filter}
- 参数说明
表1 参数说明 名称
是否必选
说明
project_id
是
参数解释：
项目ID，用于明确项目归属，配置后可通过该ID查询项目下资产，可以通过调用API获取，也可以从控制台获取。获取方式请参见获取项目ID。
约束限制：
不涉及。
取值范围：
字符串长度在1 ~64 之间。
默认取值：
不涉及。
表2 查询检索参数 名称
是否必选
参数类型
说明
namespace
是
String
参数解释：
服务指标命名空间。各服务命名空间请参考支持监控的服务列表。
约束限制：
不涉及
取值范围：
格式为service.item；service和item必须是字符串，必须以字母开头，只能包含0-9/a-z/A-Z/_，其中service不能为“SYS”、“AGT”和“SRE”，namespace不能为SERVICE.BMS，因为此namespace已被系统使用。字符串长度在3~32 之间。如：弹性云服务器的命名空间为SYS.ECS，文档数据库的命名空间为SYS.DDS。
默认取值：
不涉及。
metric_name
是
String
参数解释：
指标ID，例如弹性云服务器的监控指标CPU使用率，对应的metric_name为cpu_util。各服务监控指标请参考支持监控的服务列表。
约束限制：
不涉及。
取值范围：
必须以字母开头，只能包含0-9/a-z/A-Z/_/-；如：弹性云服务器中的监控指标cpu_util，表示弹性服务器的CPU使用率；文档数据库中的指标mongo001_command_ps，表示command执行频率。字符串长度在1~96之间。
默认取值：
不涉及。
from
是
Integer
参数解释：
查询数据起始时间。UNIX时间戳，单位毫秒（ms）。
约束限制：
由于聚合运算的过程是将一个聚合周期范围内的数据点聚合到周期起始边界上，如果将from和to的范围设置在聚合周期内，会因为聚合未完成而造成查询数据为空，所以建议from参数相对于当前时间向前偏移至少1个周期。以5分钟聚合周期为例：假设当前时间点为10:35，10:30~10:35之间的原始数据会被聚合到10:30这个点上，所以查询5分钟数据点时from参数应为10:30。
取值范围：
不涉及。
默认取值：
不涉及。
说明：云监控会根据所选择的聚合粒度向前取整from参数。
to
是
Integer
参数解释：
查询数据截止时间UNIX时间戳，单位毫秒（ms）。
约束限制：
from必须小于to。
取值范围：
不涉及。
默认取值：
不涉及。
period
是
Integer
参数解释：
指标监控数据的聚合粒度。
约束限制：
不涉及。
取值范围：
取值范围：1，60，300，1200，3600，14400，86400。
1为监控资源的实时数据；
60为聚合1分钟粒度数据，表示1分钟一个数据点；
300为聚合5分钟粒度数据，表示5分钟一个数据点；
1200为聚合20分钟粒度数据，表示20分钟一个数据点；3600为聚合1小时粒度数据，表示1小时一个数据点；14400为聚合4小时粒度数据，表示4小时一个数据点；86400为聚合1天粒度数据，表示1天一个数据点。
默认取值：
不涉及。
filter
是
String
参数解释：
数据聚合方式。
约束限制：
不涉及。
取值范围：
支持的聚合方式如下:
- average：聚合周期内指标数据的平均值。
- max：聚合周期内指标数据的最大值。
- min：聚合周期内指标数据的最小值。
- sum：聚合周期内指标数据的求和值。
- variance：聚合周期内指标数据的方差。
默认取值：
不涉及。
说明：聚合运算的过程是将一个聚合周期范围内的数据点根据相应的聚合算法聚合到周期起始边界上，以5分钟聚合周期为例：假设当前时间点为10:35，则10:30~10:35之间的原始数据会被聚合到10:30这个时间点。
dim
是
String
参数解释：
指标的维度。若指标的维度存在层级关系，需要使用多层级维度方式进行查询。
约束限制：
目前最大支持4个层级维度，维度编号从0开始，编号3为最深层级。
取值范围：
维度格式为dim.{i}=key,value，key的最大长度32，value的最大长度为256。
CloudTable仅支持多维度查询。
以下维度说明仅为示例，有关每个监控对象维度的详细信息，请查阅具体云服务的文档。您可以通过“支持监控的服务列表”页面导航至对应文档。
- 单层级维度：如弹性云服务器的CPU使用率（cpu_util），其维度为instance_id，且instance_id为0层，维度信息代入方式如下：
- 多层级维度：如弹性云服务器的(Agent) 磁盘读速率（disk_agt_read_bytes_rate）维度为disk，disk上层维度为instance_id。instance_id为0层，disk为1层，其维度信息代入方式如下：
默认取值：
不涉及。
- 对于dim字段的内容，可通过调用查询指标列表接口，在其响应体的相关指标数据中获取。
- 对于OBS相关指标数据，当进行了相关OBS接口操作时可查询到相关指标数据，否则查询结果为空。
- 对于EVS相关指标数据，disk_name维度下，它的返回值有云服务器实例ID-盘符名和云服务器实例ID-volume-卷ID两种。
- 云服务器实例ID-盘符名，例如：6f3c6f91-4b24-4e1b-b7d1-a94ac1cb011d-vda(vda为盘符名)。
- 云服务器实例ID-volume-卷ID，例如：6f3c6f91-4b24-4e1b-b7d1-a94ac1cb011d-volume-31f45764-38b3-44ad-aaca-4015c83371e6。
- 样例：
请求样例一：查看弹性云服务器ID为6f3c6f91-4b24-4e1b-b7d1-a94ac1cb011d的CPU使用率在2019-04-30 20:00:00到2019-04-30 22:00:00时间内，周期为20分钟的监控数据。
GET https://{云监控的endpoint}/V1.0/{project_id}/metric-data?namespace=SYS.ECS&metric_name=cpu_util&dim.0=instance_id,6f3c6f91-4b24-4e1b-b7d1-a94ac1cb011d&from=1556625600000&to=1556632800000&period=1200&filter=min请求样例二：查询CloudTable服务维度分别是cluster_id为f2fbxxxc-36b2-4d1d-895d-972a4d656xxx和instance_name为hmaster-active的监控指标cmdProcessMem，在2019-04-30 20:00:00到2019-04-30 22:00:00时间内，周期为20分钟的监控数据。GET https://{云监控的endpoint}/V1.0/{project_id}/metric-data?namespace=SYS.CloudTable&metric_name=cmdProcessMem&dim.0=cluster_id,f2fbxxxc-36b2-4d1d-895d-972a4d656xxx&dim.1=instance_name,hmaster-active&from=1556625600000&to=1556632800000&period=1200&filter=variance
请求消息
无
响应消息
- 响应参数
表3 响应参数 名称
参数类型
说明
datapoints
Array of objects
参数解释：
指标数据列表。详细参数请参见表4。
由于查询数据时，云监控会根据所选择的聚合粒度向前取整from参数，所以datapoints中包含的数据点有可能会多于预期。
metric_name
String
参数解释：
指标ID，例如弹性云服务器监控指标中的cpu_util。
指标ID，例如弹性云服务器的监控指标CPU使用率，对应的metric_name为cpu_util。各服务监控指标请参考支持监控的服务列表。
取值范围：
不涉及。
表4 datapoints字段数据结构说明 名称
参数类型
说明
average
Double
参数解释:
聚合周期内指标数据的平均值。
取值范围：
不涉及。
max
Double
参数解释:
聚合周期内指标数据的最大值。
取值范围：
不涉及。
min
Double
参数解释:
聚合周期内指标数据的最小值。
取值范围：
不涉及。
sum
Double
参数解释:
聚合周期内指标数据的求和值。
取值范围：
不涉及。
variance
Double
参数解释:
聚合周期内指标数据的方差。
取值范围：
不涉及。
timestamp
Long
参数解释:
指标采集时间，UNIX时间戳，单位毫秒。
取值范围：
不涉及。
unit
String
参数解释:
指标单位。
取值范围：
不涉及。
- 响应样例
响应样例一：维度为SYS.ECS，响应弹性云服务器，CPU使用率的平均值。
{ "datapoints": [ { "average": 0.23, "timestamp": 1442341200000, "unit": "%" } ], "metric_name": "cpu_util" }响应样例二：维度为SYS.ECS，响应弹性云服务器，CPU使用率的求和值。{ "datapoints": [ { "sum": 0.53, "timestamp": 1442341200000, "unit": "%" } ], "metric_name": "cpu_util" }响应样例三：维度为SYS.ECS，响应弹性云服务器，CPU使用率的最大值。{ "datapoints": [ { "max": 0.13, "timestamp": 1442341200000, "unit": "%" } ], "metric_name": "cpu_util" }
返回值
错误码
请参考返回错误码说明。
常见问题
请参考查询监控数据常见问题。
