Querying Monitoring Data of Multiple Metrics
Function
You can query the data of specified metrics within a specified time range and at a specified granularity. You can query the monitoring data of up to 500 metrics in one batch.
Constraints
- In regions CN East-Shanghai1, CN East-Shanghai2, CN North-Beijing4, and CN South-Guangzhou, you can query raw data as well as data aggregated at 1-minute and 5-minute intervals for any two days within a 20-day period. In other regions, only data from the most recent two days is available for such queries.
- Data aggregated at 20-minute, 1-hour, and 4-hour intervals is available for querying based on the metric data's retention period. For details, see How Long Is Metric Data Retained?
Debugging
You can debug the API in API Explorer which supports automatic authentication. API Explorer can automatically generate and debug example SDK code.
URI
POST /V1.0/{project_id}/batch-query-metric-data
- Parameter description
Table 1 Parameter description Parameter
Mandatory
Description
project_id
Yes
Definition
Project ID, which 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 about how to obtain the project ID, see Obtaining a Project ID.
Constraints
N/A
Range
1 to 64 characters
Default Value
N/A
Request

- 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.
- If period is 1, the monitoring interval is 60,000 ms (60 x 1000).
- If period is 300, the monitoring interval is 300,000 ms (300 x 1000).
- If period is 1200, the monitoring interval is 1,200,000 ms (1200 x 1000).
- If period is 3600, the monitoring interval is 3,600,000 ms (3600 x 1000).
- If period is 14400, the monitoring interval is 14,400,000 ms (14400 x 1000).
- If period is 86400, the monitoring interval is 86,400,000 ms (86400 x 1000).
For example, if 300 metrics are queried in batches and the monitoring interval is 60,000 ms, the maximum value of (to-from) is 600000. If (to-from) exceeds 600,000, from is automatically changed to to-600000.
- Request parameters
Table 2 Request parameters Parameter
Mandatory
Type
Description
metrics
Yes
Array of objects
Definition
Metric data.
For details, see Table 3.
Constraints
The array can contain a maximum of 500 items.
from
Yes
Long
Definition
Start time of the query. The value is a UNIX timestamp, in milliseconds.
Constraints
Set from to at least one period earlier than the current time. Cloud Eye aggregates raw data generated within an aggregation period to the start time of the period. If the time range specified by from and to falls within an ongoing aggregation period, the query result will be empty because the aggregation has not finished yet. Set from to at least one period earlier than the current time. Take the 5-minute period as an example. If it is 10:35 now, the raw data generated between 10:30 and 10:35 will be aggregated to 10:30. In this example, if period is 5 minutes, from should be 10:30.
Range
N/A
Default Value
N/A
NOTE:Cloud Eye rounds up from based on the level of granularity required to perform the rollup.
to
Yes
Long
Definition
End time of the query. The value is a UNIX timestamp, in milliseconds (ms).
Constraints
from must be earlier than to.
Range
N/A
Default Value
N/A
period
Yes
String
Definition
Aggregation granularity of metric monitoring data.
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 one 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
filter does not affect the query result of raw data. (The period is 1.)
Range
The value can be:
- average: average value of metric data within an aggregation period.
- max: maximum value of metric data in an aggregation period.
- min: minimum value of metric data within an aggregation period.
- sum: sum of metric data within an aggregation period.
- variance: variance value of metric data within an aggregation period.
Default Value
N/A
Table 3 metrics data structure description Parameter
Mandatory
Type
Description
namespace
Yes
String
Definition
Namespace of the queried service. For details, see Services Interconnected with Cloud Eye.
Constraints
N/A
Range
The namespace must be in the service.item format. service and item must be strings, and each must start with a letter and contain only letters (case-insensitive), digits, and underscores (_). In addition, service cannot start with SYS, AGT, or SRE. namespace cannot be SERVICE.BMS because this namespace has been used by the system. The value can contain 3 to 32 characters. For example, the ECS namespace is SYS.ECS, and the DDS namespace is SYS.DDS.
Default Value
N/A
metric_name
Yes
String
Definition
Metric ID. For example, metric_name of ECS CPU usage is cpu_util. For details about the metrics of each service, see Services Interconnected with Cloud Eye.
Constraints
N/A
Range
The value must start with a letter and can contain only digits, letters (case-insensitive), 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. The value can contain 1 to 96 characters.
Default Value
N/A
dimensions
Yes
Array of objects
Definition
Dimension of a metric.
Each dimension is a JSON object, and its structure is as follows:
{
"name": "instance_id",
"value": "33328f02-3814-422e-b688-bfdba93d4050"
}
For details, see Table 4.
Constraints
A maximum of four dimensions are supported.
Table 4 dimensions data structure description Parameter
Mandatory
Type
Description
name
Yes
String
Definition
Monitoring dimension name. For example, the dimension of an ECS is instance_id. For details about the dimension of each service, see the key column in Services Interconnected with Cloud Eye.
Constraints
N/A
Range
The value must start with a letter and can contain 1 to 32 characters. It can contain only digits, letters, underscores (_), and hyphens (-).
Default Value
N/A
value
Yes
String
Definition
Dimension value, for example, an ECS ID. dimensions can be obtained from the response body by calling the API for querying metrics.
Constraints
N/A
Range
The value must start with a letter or digit and can contain 1 to 256 characters. It can contain only digits, letters, underscores (_), and hyphens (-).
Default Value
N/A
- dimensions can be obtained from the response body by calling the API for querying metrics.
- OBS metric data can be queried only when the related OBS APIs are called.
- Example requests
Example 1: Query the average disk usage of the disk whose mount_point is 012bec14bc176310c19f40e384fd629b on the ECS whose instance_id is 07d878a9-2243-4e84-aeef-c47747d18024 from 20:00:00 to 22:00:00 on April 30, 2019.
{ "from": 1556625600000, "to": 1556632800000, "period": "1", "filter": "average", "metrics": [{ "dimensions": [{ "name": "instance_id", "value": "07d878a9-2243-4e84-aeef-c47747d18024" }, { "name": "mount_point", "value": "012bec14bc176310c19f40e384fd629b" }], "metric_name": "disk_usedPercent", "namespace": "AGT.ECS" }] }
Example 2: Query the average memory usage of the ECS whose instance_id is 238764d4-c4e1-4274-88a1-5956b057766b from 20:00:00 to 22:00:00 on April 30, 2019.
{ "from": 1556625600000, "to": 1556632800000, "period": "1", "filter": "average", "metrics": [{ "dimensions": [{ "name": "instance_id", "value": "238764d4-c4e1-4274-88a1-5956b057766b" }], "metric_name": "mem_usedPercent", "namespace": "AGT.ECS" }] }
Example 3: Query the average cpu_util of the five ECSs whose values of instance_id are faea5b75-e390-4e2b-8733-9226a9026070, faea5b75-e390-4e2b-8733-9226a9026071, faea5b75-e390-4e2b-8733-9226a9026072, faea5b75-e390-4e2b-8733-9226a9026073, and faea5b75-e390-4e2b-8733-9226a9026074 from 00:00:00 to 23:59:59 on August 21, 2024. Query five metrics. The monitoring period is 60,000 ms. The maximum value of (to – from) is 36000000. The value of the request parameter (to – from) is 86399000, which exceeds the maximum value 36000000. The formula is as follows: Number of metrics × Value of (to – from)/Monitoring period ≤ 3000. The system automatically sets the value of from to to – 36000000, that is, 1724219999000.
{ "metrics": [ { "namespace": "SYS.ECS", "dimensions": [ { "name": "instance_id", "value": "faea5b75-e390-4e2b-8733-9226a9026070" } ], "metric_name": "cpu_util" }, { "namespace": "SYS.ECS", "dimensions": [ { "name": "instance_id", "value": "faea5b75-e390-4e2b-8733-9226a9026071" } ], "metric_name": "cpu_util" }, { "namespace": "SYS.ECS", "dimensions": [ { "name": "instance_id", "value": "faea5b75-e390-4e2b-8733-9226a9026072" } ], "metric_name": "cpu_util" }, { "namespace": "SYS.ECS", "dimensions": [ { "name": "instance_id", "value": "faea5b75-e390-4e2b-8733-9226a9026073" } ], "metric_name": "cpu_util" }, { "namespace": "SYS.ECS", "dimensions": [ { "name": "instance_id", "value": "faea5b75-e390-4e2b-8733-9226a9026074" } ], "metric_name": "cpu_util" } ], "from": 1724169600000, "to": 1724255999000, "period": "1", "filter": "average" }
Example 4: View the average cpu_util of the ECS whose instance_id is faea5b75-e390-4e2b-8733-9226a9026070 and the average network_vm_connections of the ECS whose instance_id is 06b4020f-461a-4a52-84da-53fa71c2f42b from 20:00:00 to 22:00:00 on April 30, 2019.{ "metrics": [ { "namespace": "SYS.ECS", "dimensions": [ { "name": "instance_id", "value": "faea5b75-e390-4e2b-8733-9226a9026070" } ], "metric_name": "cpu_util" }, { "namespace": "SYS.ECS", "dimensions": [ { "name": "instance_id", "value": "06b4020f-461a-4a52-84da-53fa71c2f42b" } ], "metric_name": "network_vm_connections" } ], "from": 1556625600000, "to": 1556632800000, "period": "1", "filter": "average" }
Example 5: View the individual sums of rds021_myisam_buf_usage of the RDS instance whose rds_cluster_id is 3c8cc15614ab46f5b8743317555e0de2in01 and the RDS instance whose rds_cluster_id is 3b2fa8b55a9b4adca3713962a9d31884in01 from 20:00:00 to 22:00:00 on April 30, 2019.{ "metrics": [ { "namespace": "SYS.RDS", "dimensions": [ { "name": "rds_cluster_id", "value": "3c8cc15614ab46f5b8743317555e0de2in01" } ], "metric_name": "rds021_myisam_buf_usage" }, { "namespace": "SYS.RDS", "dimensions": [ { "name": "rds_cluster_id", "value": "3b2fa8b55a9b4adca3713962a9d31884in01" } ], "metric_name": "rds021_myisam_buf_usage" } ], "from": 1556625600000, "to": 1556632800000, "period": "1", "filter": "sum" }
Example 6: View the minimum proc_specified_count of the server whose instance_id is cd841102-f6b1-407d-a31f-235db796dcbb and proc is b28354b543375bfa94dabaeda722927f. The monitoring data is collected from 20:00:00 to 22:00:00 on April 30, 2019 and the aggregation period is 20 minutes.{ "metrics": [ { "namespace": "AGT.ECS", "dimensions": [ { "name": "instance_id", "value": "cd841102-f6b1-407d-a31f-235db796dcbb" }, { "name": "proc", "value": "b28354b543375bfa94dabaeda722927" } ], "metric_name": "proc_specified_count" } ], "from": 1556625600000, "to": 1556632800000, "period": "1200", "filter": "min" }
Response
- Response parameters
Table 5 Parameter description Parameter
Type
Description
metrics
Array of objects
Definition
Metric data list.
For details, see Table 6.
Table 6 metrics data structure description Parameter
Type
Description
unit
String
Definition
Metrics unit.
Range
N/A
datapoints
Array of 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.
For details, see Table 8.
namespace
String
Definition
Metric namespace.
Range
N/A
dimensions
Array of objects
Definition
List of metric dimensions.
Each dimension is a JSON object, and its structure is as follows:
{
"name": "instance_id",
"value": "33328f02-3814-422e-b688-bfdba93d4050"
}
For details, see Table 7.
metric_name
String
Definition
Metric name.
Range
N/A
Table 7 dimensions data structure description Parameter
Type
Description
name
String
Definition
Monitoring dimension name. For example, the dimension of an ECS is instance_id. For details about the dimension of each service, see the key column in Services Interconnected with Cloud Eye.
Range
N/A
value
String
Definition
Dimension value, for example, an ECS ID.
Range
N/A
Table 8 datapoints data structure description Parameter
Type
Description
average
Double
Definition
Average value of metric data within an aggregation period.
Range
N/A
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
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 a metric was collected. It is a UNIX timestamp, in milliseconds.
Range
N/A
- Example response
Example response 1: The average cpu_util of the ECS whose instance_id is faea5b75-e390-4e2b-8733-9226a9026070 and the average network_vm_connections of the ECS whose instance_id is 06b4020f-461a-4a52-84da-53fa71c2f42b are displayed.
{ "metrics": [ { "namespace": "SYS.ECS", "metric_name": "cpu_util", "dimensions": [ { "name": "instance_id", "value": "faea5b75-e390-4e2b-8733-9226a9026070" } ], "datapoints": [ { "average": 0.69, "timestamp": 1556625610000 }, { "average": 0.7, "timestamp": 1556625715000 } ], "unit": "%" }, { "namespace": "SYS.ECS", "metric_name": "network_vm_connections", "dimensions": [ { "name": "instance_id", "value": "06b4020f-461a-4a52-84da-53fa71c2f42b" } ], "datapoints": [ { "average": 1, "timestamp": 1556625612000 }, { "average": 3, "timestamp": 1556625717000 } ], "unit": "count" } ] }
Response example 2: The rds021_myisam_buf_usage sums of the RDS instance whose rds_cluster_id are 3c8cc15614ab46f5b8743317555e0de2in01 is displayed, and those of the RDS instance whose rds_cluster_id is 3b2fa8b55a9b4adca3713962a9d31884in01 are displayed.{ "metrics": [ { "unit": "Ratio", "datapoints": [ { "sum": 0.07, "timestamp": 1556625628000 }, { "sum": 0.07, "timestamp": 1556625688000 } ], "namespace": "SYS.RDS", "dimensions": [ { "name": "rds_cluster_id", "value": "3c8cc15614ab46f5b8743317555e0de2in01" } ], "metric_name": "rds021_myisam_buf_usage" }, { "unit": "Ratio", "datapoints": [ { "sum": 0.06, "timestamp": 1556625614000 }, { "sum": 0.07, "timestamp": 1556625674000 } ], "namespace": "SYS.RDS", "dimensions": [ { "name": "rds_cluster_id", "value": "3b2fa8b55a9b4adca3713962a9d31884in01" } ], "metric_name": "rds021_myisam_buf_usage" } ] }
Response example 3: The minimum rds021_myisam_buf_usage of the server whose instance_id is cd841102-f6b1-407d-a31f-235db796dcbb and proc is b28354b543375bfa94dabaeda722927f is displayed.{ "metrics": [ { "unit": "Ratio", "datapoints": [ { "min": 0, "timestamp": 1556625612000 }, { "min": 0, "timestamp": 1556625672000 } ], "namespace": "AGT.ECS", "dimensions": [ { "name": "instance_id", "value": "cd841102-f6b1-407d-a31f-235db796dcbb" }, { "name": "proc", "value": "b28354b543375bfa94dabaeda722927f" } ], "metric_name": "rds021_myisam_buf_usage" } ] }
Returned Values
- Normal
- Abnormal
Returned Value
Description
400 Bad Request
Request error.
401 Unauthorized
The authentication information is not provided or is incorrect.
403 Forbidden
Access to the requested page is forbidden.
408 Request Timeout
The request timed out.
429 Too Many Requests
Concurrent requests are excessive.
500 Internal Server Error
Failed to complete the request because of an internal service error.
503 Service Unavailable
The service is currently unavailable.
Error Codes
See Error Codes.
Feedback
Was this page helpful?
Provide feedbackThank you very much for your feedback. We will continue working to improve the documentation.See the reply and handling status in My Cloud VOC.
For any further questions, feel free to contact us through the chatbot.
Chatbot