Querying Monitoring Data of a Metric

Function

This API is used to query the monitoring data of a specified metric at a specified granularity in a specified time range. You can specify the dimension of data to be queried.

Debugging

You can debug the API in API Explorer which supports automatic authentication. API Explorer can automatically generate and debug example SDK code.

URI

GET /V1.0/{project_id}/metric-data

Example:

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}

• 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

  Table 2 Query parameter description

  Parameter	Mandatory	Type	Description
  namespace	Yes	String	Definition Namespace of a 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, 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
  from	Yes	String	Definition Start time for the query. The value is a UNIX timestamp, in milliseconds (ms). Constraints 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, since the period is 5 minutes, from should be at least 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	String	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	Integer	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 hour (one data point per hour). 14400: Data is aggregated every 4 hours (one data point every 4 hours). 86400: Data is aggregated every day (one data point every day). Default Value N/A
  filter	Yes	String	Definition Data aggregation method. Constraints N/A 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 NOTE: During an aggregation process, data generated within a specified time range is consolidated to the start point of the aggregation period using the relevant aggregation algorithm. Take the 5-minute period as an example. If the current time is 10:35, the raw data generated between 10:30 and 10:35 will be aggregated to 10:30.
  dim	Yes	String	Definition Dimension of a metric. Constraints A maximum of 4 hierarchical dimensions are supported. The dimensions are numbered from 0. Range The dimension format is dim.{i}=key,value. key cannot exceed 32 characters and value cannot exceed 256 characters. The following dimensions are only examples. For details about whether multiple dimensions are supported, see the metric description of each service. Single-level dimension: dim.0=instance_id,i-12345 Multi-level dimension: dim.0=instance_id,i-12345&dim.1=instance_name,i-1234 NOTE: If the dimensions of a metric have a hierarchical relationship, you need to use multi-level dimension queries. 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:

  Request example 1: View the CPU usage of ECS whose ID is 6f3c6f91-4b24-4e1b-b7d1-a94ac1cb011d from 2019-04-30 20:00:00 to 2019-04-30 22:00:00. The monitoring interval is 20 minutes.

  GET https://{Cloud Eye 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

Request

None

Response

• Response parameters

  Table 3 Parameter description

  Parameter	Type	Description
  datapoints	Array of objects	Definition Metric data list. For details, see Table 4. Since Cloud Eye rounds up from based on the level of granularity for data query, datapoints may contain more data points than expected.
  metric_name	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. Range N/A

  Table 4 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
  unit	String	Definition Metric unit. Range N/A

• Example response
  Example response 1: The dimension is SYS.ECS, and the average CPU usage of ECSs is displayed.

  {
      "datapoints": [
          {
              "average": 0.23, 
              "timestamp": 1442341200000, 
              "unit": "%"
          }
      ], 
      "metric_name": "cpu_util"
  }

  Example response 2: The dimension is SYS.ECS, and the sum CPU usage of ECSs is displayed.

  {
      "datapoints": [
          {
              "sum": 0.53, 
              "timestamp": 1442341200000, 
              "unit": "%"
          }
      ], 
      "metric_name": "cpu_util"
  }

  Example response 3: The dimension is SYS.ECS, and the maximum CPU usage of ECSs is displayed.

  {
      "datapoints": [
          {
              "max": 0.13, 
              "timestamp": 1442341200000, 
              "unit": "%"
          }
      ], 
      "metric_name": "cpu_util"
  }

Returned Values

• Normal

  200

• 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.