Custom monitoring provides an API that you can use for reporting monitoring data. Specifically, the API allows you to report the time series data you have collected to CloudMonitor and configure alarm rules to receive alarm notifications.

CloudMonitor provides three methods for reporting data: OpenAPI, Java SDK, and Alibaba Cloud CLI.

Limits

  • QPS is limited to 200 in the regions Beijing, Shanghai, and Hangzhou, 100 in the regions Zhangjiakou and Shenzhen, and 50 in all other regions.
  • A maximum of 100 data entries can be reported at one time. The body size cannot exceed 256 KB.
  • The metricName field only supports letters, numbers, and underscores. The field must start with a letter. A non-letter start is replaced with an uppercase "A" and all other invalid characters are replaced with underscores (_).
  • The dimensions field does not support "=", "&", or ",". Invalid characters are replaced with underscores (_).
  • metricName and dimensions cannot exceed 64 bytes. Otherwise, the key-value is truncated.
  • Reporting raw data incurs fees. The free edition supports aggregate data reporting (that is, when reporting data, you need to pass "1" for the type field to the request parameter).

Report data by using OpenAPI

After you report raw data by using OpenAPI, CloudMonitor calculates the statistics in one-minute and five-minute intervals by using the following statistical methods:

  • Average: the average value
  • Maximum: the maximum value
  • Minimum: the minimum value
  • Sum: sum value
  • SampleCount: count
  • SumPerSecond: sum/total seconds of the corresponding aggregation period. You can also use the moving average calculation.
  • CountPerSecond: count/total seconds of the corresponding aggregation period. You can also use the moving average calculation.
  • LastValue: the last sampling value in the aggregation period, which is similar to gauge.
  • P10: percentile 0.1, greater than 10% of all sampling data in the aggregation period
  • P20: percentile 0.2, greater than 20% of all sampling data in the aggregation period
  • P30: percentile 0.3, greater than 30% of all sampling data in the aggregation period
  • P40: percentile 0.4, greater than 40% of all sampling data in the aggregation period
  • P50: percentile 0.5, greater than 50% of all sampling data in the aggregation period, also known as the median
  • P60: percentile 0.6, greater than 60% of all sampling data in the aggregation period
  • P70: percentile 0.7, greater than 70% of all sampling data in the aggregation period
  • P75: percentile 0.75, greater than 75% of all sampling data in the aggregation period
  • P80: percentile 0.8, greater than 80% of all sampling data in the aggregation period
  • P90: percentile 0.9, greater than 90% of all sampling data in the aggregation period
  • P95: percentile 0.95, greater than 95% of all sampling data in the aggregation period
  • P98: percentile 0.98, greater than 98% of all sampling data in the aggregation period
  • P99: percentile 0.99, greater than 99% of all sampling data in the aggregation period
  • Service addresses

    Internet address of the service: https://metrichub-cms-cn-hangzhou.aliyuncs.com

    The intranet addresses of the service is as follows:

    Region RegionId Endpoints
    China East 1 (Hangzhou) cn-hangzhou http://metrichub-cn-hangzhou.aliyun.com
    China North 3 (Zhangjiakou) cn-zhangjiakou http://metrichub-cn-zhangjiakou.aliyun.com
    China East 2 (Shanghai) cn-shanghai http://metrichub-cn-shanghai.aliyun.com
    China North 2 (Beijing) cn-beijing http://metrichub-cn-beijing.aliyun.com
    China North 1 (Qingdao) cn-qingdao http://metrichub-cn-qingdao.aliyun.com
    China South 1 (Shenzhen) cn-shenzhen http://metrichub-cn-shenzhen.aliyun.com
    Hong Kong (China) cn-hongkong http://metrichub-cn-hongkong.aliyun.com
    China North 5 cn-huhehaote http://metrichub-cn-huhehaote.aliyun.com
    Middle East 1 (Dubai) me-east-1 http://metrichub-me-east-1.aliyun.com
    US West 1 (Silicon valley) us-west-1 http://metrichub-us-west-1.aliyun.com
    US East 1 (Virginia) us-east-1 http://metrichub-us-east-1.aliyun.com
    Asia Pacific NE 1 (Tokyo) ap-northeast-1 http://metrichub-ap-northeast-1.aliyun.com
    EU Central 1 (Frankfurt) eu-central-1 http://metrichub-eu-central-1.aliyun.com
    Asia Pacific SE 2 (Sydney) ap-southeast-2 http://metrichub-ap-southeast-2.aliyun.com
    Asia Pacific SE 1 (Singapore) ap-southeast-1 http://metrichub-ap-southeast-1.aliyun.com
    Asia Pacific SE 3 (Kuala Lumpur) ap-southeast-3 http://metrichub-ap-southeast-3.aliyun.com
    Asia Pacific SOU 1 (Mumbai) ap-south-1 http://metrichub-ap-south-1.aliyuncs.com
  • Request syntax
    POST /metric/custom/upload HTTP/1.1 
    Authorization:<AuthorizationString>
    Content-Length:<Content Length>
    Content-MD5:<Content MD5>
    Content-Type:application/json
    Date:<GMT Date>
    Host: metrichub-cms-cn-hangzhou.aliyuncs.com
    x-cms-signature:hmac-sha1
    x-cms-api-version:1.0
    x-cms-ip:30.27.84.196
    User-Agent:cms-java-sdk-v-1.0
    [{"groupId":101,"metricName":"","dimensions":{"sampleName1":"value1","sampleName2":"value2"},"time":"","type":0,"period":60,"values":{"value":10.5,"Sum":100}}]
  • Signature algorithm

    For more information, see Signature algorithm.

  • Request parameters
    Name Type Required or not Description
    groupId long Yes ID of an application group
    metricName string Yes Name of a monitoring metric. The name can be up to 64 bytes in length and can contain letters, numbers, and connectors "_-./\". Characters that exceed the limit are truncated.
    dimensions object Yes Dimension map. The key-value is a string where the key and the value can be up to 64 bytes in length separately, and can contain letters, numbers, and connectors "_-./\". Characters that exceed the limit are truncated. The maximum number of key-value pairs is 10.
    time string Yes Time of the metric data. It supports "yyyyMMdd'T'HHmmss.SSSZ" and long format timestamps, for example, 20171012T132456.888+0800 or 1508136760000.
    type int Yes

    Type of the reported data. 0 represents raw data, and 1 indicates aggregate data.

    When you report aggregate data, we recommend that you report the data in both 60s and 300s aggregation periods. Otherwise, you will not be able to query monitoring data that is older than seven days.

    period string No

    Aggregation period in seconds.

    If type=1, this field is required. The value can be 60 or 300.

    values object Yes Collection of metric values. If type=0, the key must be "value" and raw data is reported. CloudMonitor aggregates raw data into multiple types of data on the basis of aggregation periods, for example, maximum, count, and sum.

Report data by using the Java SDK

  • Install the Java SDK
    When you install the Java SDK through Maven, the following dependencies must be added:
    <dependency>
                <groupId>com.aliyun.openservices</groupId>
                <artifactId>aliyun-cms</artifactId>
                <version>0.2.4</version>
    </dependency>
  • Response element

    The system returns the HTTP status code 200.

  • Examples
    • Request example
      POST /metric/custom/upload HTTP/1.1 
      Host: metrichub-cms-cn-hangzhou.aliyuncs.com
      x-cms-api-version:1.0
      Authorization:yourAccessKeyId:yourAccessKeySecret  
      Host:metrichub-cms-cn-hangzhou.aliyuncs.com"
      Date:Mon, 23 Oct 2017 06:51:11 GMT
      Content-Length:180
      x-cms-signature:hmac-sha1
      Content-MD5:E9EF574D1AEAAA370860FE37856995CD
      x-cms-ip:30.27.84.196
      User-Agent:cms-java-sdk-v-1.0
      Content-Type:application/json
      [{"groupId":101,"metricName":"","dimensions":{"sampleName1":"value1","sampleName2":"value2"},"time":"","type":0,"period":60,"values":{"value":10.5,"Sum":100}}]
    • Response example
      {
         "code":"200",
         "msg":""//The returned msg is null when the reporting is normal.
      }
  • Code example
    • Report raw data
      CMSClientInit.groupId = 101L;//Set a common group ID.
              CMSClient cmsClient = new CMSClient(endpoint, accKey, secret);//Initialize the client.
              CustomMetricUploadRequest request = CustomMetricUploadRequest.builder()
                      .append(CustomMetric.builder()
                              .setMetricName("testMetric")//Metric name
                              .setGroupId(102L)//Set a custom group ID.
                              .setTime(new Date())
                              .setType(CustomMetric.TYPE_VALUE)//The type is raw data.
                              .appendValue(MetricAttribute.VALUE, 1f)//The key must be this when the type is raw data.
                              .appendDimension("key", "value")//Add a dimension.
                              .appendDimension("ip", "127.0.0.1")//Add a dimension.
                              .build())
                      .build();
              CustomMetricUploadResponse response = cmsClient.putCustomMetric(request);//Report data.
              System.out.println(JSONObject.toJSONString(response));
    • Automatically report aggregate data of multiple aggregation periods

      SDK supports data reporting after local aggregation. The aggregation periods are one minute and five minutes.

      Data type Description Aggregated value Memory usage (excluding names, dimensions, individual time series, and individual aggregation periods)
      value Typical value All properties except LastValue About 4 KB
      gauge Sample value LastValue 4 bytes
      meter Sum and speed Sum, SumPerSecond 50 bytes
      counter Count SampleCount 10 bytes
      timer Computing time SampleCount, CountPerSecond, Average, Maximum, Minimum, PXX(P10–P99) About 4 KB
      histogram Distribution SampleCount, Average, Maximum, Minimum, PXX(P10–P99) About 4 KB
      //Initialize
              CMSClientInit.groupId = 0L;
              CMSClient cmsClient = new CMSClient(accKey, secret, endpoint);//Create a client.
              CMSMetricRegistryBuilder builder = new CMSMetricRegistryBuilder();
              builder.setCmsClient(cmsClient);
              final MetricRegistry registry = builder.build();//Create a registry which contains two aggregation periods.
              //or final MetricRegistry registry = builder.build(RecordLevel._60S);//Create a registry which contains only the one-minute aggregation period.
      //Use value.
      ValueWrapper value = registry.value(MetricName.build("value"));
      value.update(6.5);
      //Use meter.
      MeterWrapper meter = registry.meter(MetricName.build("meter"));
      meter.update(7.2);
      //Use counter.
      CounterWrapper counter = registry.counter(MetricName.build("counter"));
      counter.inc(20);
      counter.dec(5);
      //Use timer.
      TimerWrapper timer = registry.timer(MetricName.build("timer"));
      timer.update(30, TimeUnit.MILLISECONDS);
      //Use histogram.
      HistogramWrapper histogram = registry.histogram(MetricName.build("histogram"));
      histogram.update(20);
      //Use gauge.
      final List list = new ArrayList();
      registry.gauge(MetricName.build("gauge"), new Gauge() {
                              @Override
                              public Number getValue() {
                                  return list.size();
                              }
                          });

Report data by using Alibaba Cloud CLI

Prepare your Alibaba Cloud account

Make sure that you have created a RAM user under your Alibaba Cloud account and have generated a RAM user Access Key (AK) with CloudMonitor permissions.

  • Create a RAM user

  • Generate an AccessKeyID and AccessKeySecret for the RAM user.

  • Grant CloudMonitor permissions to the RAM user.

Install Alibaba Cloud CLI

System requirement: Linux, UNIX, or Mac OS

Environment requirement: You have installed Python 2.7.x.

  1. Install Python.
    • If you have installed Python 2.7.x, skip this step.
    • Otherwise, run the following command in your command line interface:
      Note Make sure that you have installed wget.
      wget https://www.python.org/ftp/python/2.7.8/Python-2.7.8.tgz (or download it in some other way and put it in a certain path)
      tar -zxvf Python-2.7.8.tgz
      cd Python-2.7.8
      ./configure
      make
      sudo make install
  2. Install pip.
    • Run the following command in your command line interface:
      Note If you have installed pip, you can skip this step.
      curl "https://bootstrap.pypa.io/get-pip.py" -o "pip-install.py"
      sudo python pip-install.py
    • If the system displays the following or similar information, the installation is successful.
      Successfully installed pip-7.1.2 setuptools-18.7 wheel-0.26.0
  3. Install Alibaba Cloud CLI.
    • An earlier version of pip can cause installation failure of Alibaba Cloud CLI. Make sure that you use pip 7.x or a later version. You can run the following command in your command line interface to upgrade pip:
      sudo pip install -U pip
      If the system displays the following or similar information, the upgrade is successful.
      Successfully uninstalled pip-7.1.2
      Successfully installed pip-8.1.2
    • Run the following command to install Alibaba Cloud CLI:
      sudo pip install aliyuncli
      If the system displays the following or similar information, the installation is successful.
      Successfully installed aliyuncli-2.1.2 colorama-0.3.3 jmespath-0.7.1
  4. Configure Alibaba Cloud CLI. Run the following command to configure Alibaba Cloud CLI:
    ~ sudo aliyuncli configure
    Aliyun Access Key ID [*******************a]: youraccesskeyid
    Aliyun Access Key Secret [*******************b]: youraccesskeysecret
    Default Region Id [cn-hangzhou]: cn-hangzhou
    Default output format [json]: json
Install CMS SDK
  • The installation method for a Windows system is as follows:
    cd C:\Python27\Scripts
    pip install aliyun-python-sdk-cms
  • To update the SDK in a Windows system, use the following command:
    pip install --upgrade aliyun-python-sdk-cms
  • The installation method for a Linux system is as follows:
    sudo pip install aliyun-python-sdk-cms
  • To update the SDK in a Linux system, use the following command:
    sudo pip install —upgrade aliyun-python-sdk-cms

Report monitoring data

Use the PutCustomMetric interface to report monitoring data.

  • Example for a Windows system
    aliyuncli.exe cms PutCustomMetric --MetricList "[{'groupId':1,'metricName':'testMetric','dimensions':{'sampleName1':'value1','sampleName2':'value2'},'type':0,'values':{'value':10.5}}]"
  • Example for a Linux system
    aliyuncli cms PutCustomMetric --MetricList "[{'groupId':1,'metricName':'testMetric','dimensions':{'sampleName1':'value1','sampleName2':'value2'},'type':0,'values':{'value':10.5}}]"
  • If the data is reported successfully, status code 200 is returned.
    {
    "Code":"200"
    }

Error codes

Error code Description
200 Normal
206

Partially successful.

If "reach max time series num" is returned, it indicates that your time series quota has run out. We recommend that you pay for a higher quota or remove unnecessary time series.

If "not allowed original value, please upgrade service" is returned, it indicates that you are using the free edition, which does not support raw data reporting.

If "type is invalid" is returned, it indicates that the type value is invalid. Please check if a number other than 0 or 1 is passed in.

400 Syntax errors in the client request
403 Verification failure, speed limit, or not authorized
500 Internal server error

RAM user authorization

You must grant CloudMonitor permissions to the corresponding RAM user before you can report event data by using the RAM user AK. If you do not grant the permissions, when you report data, the prompt "cannot upload, please use ram to auth" is displayed.

  1. Log on to the RAM console.
  2. In the left-side navigation pane, click Users.
  3. Find the target user and click Authorize.

  4. On the authorization page, select the AliyunCloudMonitorFullAccess policy and click OK.