Querying Monitoring Data in Batches

Function

This API is used to query the monitoring data of specified metrics within a specified time range and a specified granularity in batches. You can query the monitoring data of up to 500 metrics in batches. The default maximum query intervals (the to-from value) for different periods and numbers of metrics to be queried are different. The following requirements must be met: Number of metrics x (to-from value)/Monitoring period ≤ 3000. If the obtained value is greater than 3000, the from value is automatically adjusted to meet the requirements.

Constraints

Notes:

The size of a POST request cannot exceed 512 KB. Otherwise, the request will be denied.
The default maximum query interval (to – from) varies depending on period and the number of metrics to be queried. The rule is as follows: Number of metrics x (to – from)/Monitoring interval ≤ 3000.

Number of metrics: the number of elements in the metrics attribute in the request.

Monitoring interval: the value of the period attribute in the request, in milliseconds.

3000: the total number of all data points (the metric data list) in the response body.

If period is 1, the monitoring interval is 60,000 ms (60 x 1,000).
If period is 300, the monitoring interval is 300,000 ms (300 x 1,000).
If period is 1200, the monitoring interval is 1,200,000 ms (1,200 x 1,000).
If period is 3600, the monitoring interval is 3,600,000 ms (3,600 x 1,000).
If period is 14400, the monitoring interval is 14,400,000 ms (14,400 x 1,000).
If period is 86400, the monitoring interval is 86,400,000 ms (86,400 x 1,000).

For example, if 300 metrics are queried in batches and the monitoring interval is 60,000 ms, the maximum value of (to – from) is 600,000. If (to – from) exceeds 600,000, from is automatically changed to **to – 600,000.

Debugging

You can debug this API through automatic authentication in API Explorer or use the SDK sample code generated by API Explorer.

Authorization Information

Each account has all the permissions required to call all APIs, but IAM users must be assigned the required permissions.

If you are using role/policy-based authorization, see Permissions Policies and Supported Actions for details on the required permissions.
If you are using identity policy-based authorization, the following identity policy-based permissions are required.

Action

Access Level

Resource Type (*: required)

Condition Key

Alias

Dependencies

ces:metricData:list

List

-

-

-

-

Action	Access Level	Resource Type (*: required)	Condition Key	Alias	Dependencies
ces:metricData:list	List	-	-	-	-

URI

POST /V1.0/{project_id}/batch-query-metric-data

**Table 1** Path Parameters
Parameter	Mandatory	Type	Description
project_id	Yes	String	Definition Project ID. It is used to specify the project that an asset belongs to. You can query the assets of a project by project ID. You can obtain the project ID from the API or console. For details, see Obtaining a Project ID. Constraints N/A Range 1 to 64 characters. Default Value N/A

Request Parameters

**Table 2** Request header parameters
Parameter	Mandatory	Type	Description
Content-Type	No	String	Definition MIME type of the request body. Constraints N/A Range 1 to 64 characters Default Value Default value application/json; charset=UTF-8 is recommended. For APIs used to upload objects or images, the MIME type varies with the flow type.
X-Auth-Token	No	String	Definition User token. Constraints N/A Range 1 to 16,384 characters Default Value N/A

**Table 3** Request body parameters
Parameter	Mandatory	Type	Description
metrics	Yes	Array of MetricInfo objects	Definition Metric data. Constraints 1 to 500 metric data objects.
period	Yes	String	Definition Aggregation granularity of monitoring data. For details about the aggregation, see What Is Aggregation? Constraints N/A Range The value can be: 1: real-time data of monitored resources. 60: Data is aggregated every one minute (one data point per minute). 300: Data is aggregated every 5 minutes (one data point every 5 minutes). 1200: Data is aggregated every 20 minutes (one data point every 20 minutes). 3600: Data is aggregated every hour (one data point per hour). 14400: Data is aggregated every 4 hours (one data point every four hours). 86400: Data is aggregated every one day (one data point per day). Default Value N/A
filter	Yes	String	Definition Data aggregation method. Constraints When period is set to 1 (original value), the filter field does not take effect. The default value of filter is average. The filter parameter takes effect only when period is greater than 1. Range The value can be: average variance min: minimum value. max: maximum value. sum Default Value N/A
from	Yes	Integer	Definition Start time of the query. The value is a UNIX timestamp in milliseconds. Constraints When period is set to 1, if (to – from) > 4 x 3,600 x 1,000, adjust the value of from to to – 4 x 3,600 x 1,000. When period is set to 300, if (to – from) > 24 x 3,600 x 1,000, adjust from to to – 24 x 3,600 x 1,000. When period is set to 1200, if (to – from) is greater than 3 x 24 x 3,600 x 1,000, adjust from to to – 3 x 24 x 3,600 x 1,000. When period is set to 3600, if (to – from) > 10 x 24 x 3,600 x 1,000, adjust from to to – 10 x 24 x 3,600 x 1,000. When period is set to 14400, if (to – from) > 30 x 24 x 3,600 x 1,000, adjust from to to – 30 x 24 x 3,600 x 1,000. When period is set to 86400, if (to – from) > 180 x 24 x 3,600 x 1,000, adjust from to to – 180 x 24 x 3,600 x 1,000. Range The millisecond-level timestamp range is [1111111111111,9999999999999]. Default Value N/A
to	Yes	Integer	Definition End time of the query. The value is a UNIX timestamp in milliseconds. Constraints The value of from must be earlier than that of to. Range The millisecond-level timestamp range is [1111111111111,9999999999999]. Default Value N/A

**Table 4** MetricInfo
Parameter	Mandatory	Type	Description
namespace	Yes	String	Definition Service namespace, for example, the namespace of ECS is SYS.ECS . For details about service namespaces, see Services Interconnected with Cloud Eye. Constraints N/A Range The value is in the format of service.item, where service and item are separated by a period (.). service and item each must start with a letter. They can contain letters, digits, and underscores (_) and allow 3 to 32 characters. Default Value N/A
metric_name	Yes	String	Definition Metric ID. For example, if the metric of an ECS is CPU usage, metric_name is cpu_util . For details about the metric names of each resource, see their service documentation. You can navigate there from Services Interconnected with Cloud Eye. Constraints N/A Range The value must start with a letter and can only contain letters, digits, underscores (_), and hyphens (-). For example, the ECS metric cpu_util indicates the CPU usage of an ECS. The DDS metric mongo001_command_ps indicates the command execution frequency. It allows 1 to 96 characters. Default Value N/A
dimensions	Yes	Array of MetricsDimension objects	Definition Metric dimension. Constraints 1 to 4 metric dimension objects.

**Table 5** MetricsDimension
Parameter	Mandatory	Type	Description
name	Yes	String	Definition Dimension of a resource. For example, the dimension of an ECS is instance_id . A maximum of four dimensions are supported. For details about the dimension names of each resource, see their service documentation. You can navigate there from Services Interconnected with Cloud Eye. Constraints N/A Range The value starts with a letter and allows 1 to 32 characters. It can contain only letters, digits, underscores (_), and hyphens (-). Default Value N/A
value	Yes	String	Definition Resource dimension value, which is an instance ID, for example, 4270ff17-aba3-4138-89fa-820594c39755. Constraints N/A Range 1 to 256 characters Default Value N/A

Response Parameters

Status code: 200

**Table 6** Response body parameters
Parameter	Type	Description
metrics	Array of BatchMetricData objects	Definition Metric response body.

**Table 7** BatchMetricData
Parameter	Type	Description
unit	String	Definition Metric unit. Range N/A
datapoints	Array of DatapointForBatchMetric objects	Definition Metric data list. During data query, Cloud Eye rounds up the value of from based on the aggregation granularity selected, so there may be more data points in datapoints than expected. A maximum of 3,000 data points can be returned.
namespace	String	Definition Service namespace. Range N/A
metric_name	String	Definition Metric name, for example, an ECS metric is cpu_util. Range N/A
dimensions	Array of MetricsDimensionResp objects	Definition Service dimension list.

**Table 8** DatapointForBatchMetric
Parameter	Type	Description
max	Double	Definition Maximum value of metric data within an aggregation period. Range N/A
min	Double	Definition Minimum value of metric data within an aggregation period. Range N/A
average	Double	Definition Average value of metric data within an aggregation period. Range N/A
sum	Double	Definition Sum of metric data within an aggregation period. Range N/A
variance	Double	Definition Variance value of metric data within an aggregation period. Range N/A
timestamp	Long	Definition Time when the metric was collected. It is a UNIX timestamp in millisecond. Range N/A

**Table 9** MetricsDimensionResp
Parameter	Type	Description
name	String	Definition Dimension of a resource. For example, the dimension of an ECS is instance_id . A maximum of four dimensions are supported. For details about the dimension names of each resource, see their service documentation. You can navigate there from Services Interconnected with Cloud Eye. Range The value starts with a letter and allows 1 to 32 characters. It can contain only letters, digits, underscores (_), and hyphens (-).
value	String	Definition Resource dimension value, which is an instance ID, for example, 4270ff17-aba3-4138-89fa-820594c39755. Range 1 to 256 characters

Status code: 400

**Table 10** Response body parameters
Parameter	Type	Description
-	String	Request error.

Status code: 401

**Table 11** Response body parameters
Parameter	Type	Description
-	String	The authentication information is not provided or is incorrect.

Status code: 403

**Table 12** Response body parameters
Parameter	Type	Description
-	String	Access to the requested page is forbidden.

Status code: 408

**Table 13** Response body parameters
Parameter	Type	Description
-	String	The request timed out.

Status code: 429

**Table 14** Response body parameters
Parameter	Type	Description
-	String	Too many requests.

Status code: 500

**Table 15** Response body parameters
Parameter	Type	Description
-	String	Failed to complete the request because of an internal service error.

Status code: 503

**Table 16** Response body parameters
Parameter	Type	Description
-	String	The system is currently unavailable.

Example Requests

{
  "metrics" : [ {
    "namespace" : "MINE.APP",
    "dimensions" : [ {
      "name" : "instance_id",
      "value" : "33328f02-3814-422e-b688-bfdba93d4050"
    } ],
    "metric_name" : "cpu_util"
  }, {
    "namespace" : "MINE.APP",
    "dimensions" : [ {
      "name" : "instance_id",
      "value" : "33328f02-3814-422e-b688-bfdba93d4051"
    } ],
    "metric_name" : "cpu_util"
  } ],
  "from" : 1484153313000,
  "to" : 1484653313000,
  "period" : "1",
  "filter" : "average"
}

Example Responses

Status code: 200

{
  "metrics" : [ {
    "unit" : "request/s",
    "datapoints" : [ {
      "average" : 0,
      "timestamp" : 1484401920000
    }, {
      "average" : 1,
      "timestamp" : 1484407920000
    } ],
    "namespace" : "MINE.APP",
    "dimensions" : [ {
      "name" : "instance_id",
      "value" : "33328f02-3814-422e-b688-bfdba93d4050"
    } ],
    "metric_name" : "cpu_util"
  }, {
    "unit" : "request/s",
    "datapoints" : [ {
      "average" : 2.3,
      "timestamp" : 1484401920000
    }, {
      "average" : 1.2,
      "timestamp" : 1484407920000
    } ],
    "namespace" : "MINE.APP",
    "dimensions" : [ {
      "name" : "instance_id",
      "value" : "33328f02-3814-422e-b688-bfdba93d4051"
    } ],
    "metric_name" : "cpu_util"
  } ]
}