Custom monitoring allows you to customize metrics and alarm rules to meet your business requirements. Custom monitoring provides API operations for reporting monitoring data. You can use the API operations to report collected time series data to CloudMonitor (CMS). You can also configure alarm rules to receive notifications of corresponding exceptions.

CloudMonitor provides API operations, Java SDKs, and Alibaba Cloud command-line interface (CLI) for reporting data.

Limits

  • The upper limit of queries per second (QPS) is 200 QPS in China (Beijing), China (Shanghai), and China (Hangzhou), 100 QPS in China (Zhangjiakou-Beijing Winter Olympics) and China (Shenzhen), and 50 QPS in all other regions.
  • The system reports a maximum of 100 data entries at one time. The body size is 256 KB or less.
  • The metricName field can only contain letters, digits, and underscores (_). This field must start with a letter. If the starting character is not a letter, this character is replaced with an uppercase A. Invalid characters are replaced with underscores (_).
  • The dimensions field cannot contain equal signs (=), ampersands (&), or commas (,). Invalid characters are replaced with underscores (_).
  • The string length of the key or value of both metricName and dimensions is 64 bytes or fewer. Otherwise, the key or value string is truncated.
  • You have to pay for reporting raw data. You can obtain aggregated data free of charge. To obtain the free data, set the Type field to 1 in the request parameters.

Report data by using API operations

After you report the raw data by using API operations, CloudMonitor uses the following statistical methods to calculate the statistics at 1-minute and 5-minute intervals:

  • Average: the average value.
  • Maximum: the maximum value.
  • Minimum: the minimum value.
  • Sum: the sum value.
  • SampleCount: the count.
  • SumPerSecond: the sum divided by the total number of seconds of the corresponding aggregation period. You can also use the moving average calculation.
  • CountPerSecond: the count divided by the total number of seconds of the corresponding aggregation period. You can also use the moving average calculation.
  • LastValue: the last sampled value in the aggregation period.
  • P10: the value of the 10th percentile. This value is greater than 10% of all data in the aggregation period.
  • P20: the value of the 20th percentile. This value is greater than 20% of all data in the aggregation period.
  • P30: the value of the 30th percentile. This value is greater than 30% of all data in the aggregation period.
  • P40: the value of the 40th percentile. This value is greater than 40% of all data in the aggregation period.
  • P50: the value of the 50th percentile. This value is a median value and greater than 50% of all data in the aggregation period.
  • P60: the value of the 60th percentile. This value is greater than 60% of all data in the aggregation period.
  • P70: the value of the 70th percentile. This value is greater than 70% of all data in the aggregation period.
  • P75: the value of the 75th percentile. This value is greater than 75% of all data in the aggregation period.
  • P80: the value of the 80th percentile. This value is greater than 80% of all data in the aggregation period.
  • P90: the value of the 90th percentile. This value is greater than 90% of all data in the aggregation period.
  • P95: the value of the 95th percentile. This value is greater than 95% of all data in the aggregation period.
  • P98: the value of the 98th percentile. This value is greater than 98% of all data in the aggregation period.
  • P99: the value of the 99th percentile. This value is greater than 99% of all data in the aggregation period.
  • Endpoints

    Internet endpoint: https://metrichub-cms-cn-hangzhou.aliyuncs.com.

    The following table lists the intranet endpoints.

    Region Region ID Endpoint
    China (Hangzhou) cn-hangzhou-b http://metrichub-cn-hangzhou.aliyun.com
    China (Zhangjiakou-Beijing Winter Olympics) cn-zhangjiakou http://metrichub-cn-zhangjiakou.aliyun.com
    China (Shanghai) cn-shanghai http://metrichub-cn-shanghai.aliyun.com
    China (Beijing) cn-beijing http://metrichub-cn-beijing.aliyun.com
    China (Qingdao) cn-qingdao http://metrichub-cn-qingdao.aliyun.com
    China (Shenzhen) cn-shenzhen  http://metrichub-cn-shenzhen.aliyun.com
    China (Hong Kong) cn-hongkong http://metrichub-cn-hongkong.aliyun.com
    China (Hohhot) cn-huhehaote http://metrichub-cn-huhehaote.aliyun.com
    UAE (Dubai) me-east-1 http://metrichub-me-east-1.aliyun.com
    US (Silicon Valley) us-west-1 http://metrichub-us-west-1.aliyun.com
    US (Virginia) us-east-1 http://metrichub-us-east-1.aliyun.com
    Japan (Tokyo) ap-northeast-1 http://metrichub-ap-northeast-1.aliyun.com
    Germany (Frankfurt) eu-central-1 http://metrichub-eu-central-1.aliyun.com
    Australia (Sydney) ap-southeast-2 http://metrichub-ap-southeast-2.aliyun.com
    Singapore ap-southeast-1 http://metrichub-ap-southeast-1.aliyun.com
    Malaysia (Kuala Lumpur) ap-southeast-3 http://metrichub-ap-southeast-3.aliyun.com
    India (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":0,"metricName":"diskUtilization","dimensions":{"instanceId":"xxxxxx1","disk":"/"},"time":"20190701T12345.888+0800","type":0,"period":60,"values":{"value":60}}]
  • Signature algorithm

    CloudMonitor only supports the HMAC-SHA1 signature algorithm.

    1. Prepare an Alibaba Cloud AccessKey pair.

      To generate a digital signature for an API request, you must use an AccessKey pair that consists of the AccessKey ID and AccessKey Secret. You can use an existing AccessKey pair or create a new one. The AccessKey pair must be in the Active state.

    2. Generate a signature string for the request.

      An API signature string consists of the Method, Header, and Body fields of the HTTP request.

      SignString = VERB + "\n"
                   + CONTENT-MD5 + "\n"
                   + CONTENT-TYPE + "\n"
                   + DATE + "\n"
                   + CanonicalizedHeaders + "\n"
                   + CanonicalizedResource

      In this formula, \n indicates the newline escape character and the plus sign (+) indicates the string concatenation operator. The other parts are defined as follows:

      Parameter Description Examples
      VERB The method name of the HTTP request. PUT, GET, and POST
      CONTENT-MD5 The MD5 value of the Body field in the HTTP request. This value must be an uppercase string. 875264590688CA6171F6228AF5BBB3D2
      CONTENT-TYPE The type of the Body field in the request. application/json
      DATE The standard timestamp header of the HTTP request. This timestamp header follows the RFC 1123 specification and uses GMT standard time. Mon, 3 Jan 2010 08:33:47 GMT
      CanonicalizedHeaders The string constructed by the custom headers that are prefixed with x-cms and x-acs of the HTTP request. x-cms-api-version:0.1.0\nx-cms-signature
      CanonicalizedResource The string constructed by the HTTP request resources, as described in the following section. /event/custom/upload
      The CanonicalizedHeaders string in the preceding table is constructed as follows:
      1. Convert the names of all HTTP request headers that are prefixed with x-cms and x-acs to lowercase letters.
      2. Sort the CMS custom request headers generated in the preceding step in lexicographic order.
      3. Delete any space on either side of a delimiter between a request header and the corresponding content.
      4. Separate all headers and content with separators (\n) to form the final CanonicalizedHeaders string.

      The CanonicalizedResource string in the preceding table is constructed as follows:

      1. Set CanonicalizedResource as an empty string ("").
      2. Place the URI that you want to access, such as /event/custom/upload, between the quotation marks.
      3. If the request contains a query string in QUERY_STRING, add a question mark (?) and the query string to the end of the CanonicalizedResource string.

        In the request, QUERY_STRING is the lexicographically sorted string of the request parameters included in the URL. Equal signs (=) are used between the names and values of parameters to form a string. The parameter name-parameter value pairs are then sorted in lexicographic order and connected with ampersands (&) to form a string. The formula is as follows:

        QUERY_STRING = "KEY1=VALUE1" + "&" + "KEY2=VALUE2"
    3. Generate a digital signature for the request.
      The default signature algorithm is HMAC-SHA1. You can use the following formula to generate a signature:
      Signature = base16(hmac-sha1(UTF8-Encoding-Of(SignString), AccessKeySecret))
    4. Signature example
      SignString="POST" + \n
      +"0B9BE351E56C90FED853B32524253E8B" + \n
      +"application/json" + \n
      +"Tue, 11 Dec 2018 21:05:51 +0800" + \n
      +"x-cms-api-version:1.0" + \n
      +"x-cms-ip:127.0.0.1" + \n
      +"x-cms-signature:hmac-sha1" + \n
      +"/metric/custom/upload"
      
      accesskey="testkey"
      accessSecret="testsecret" Signature key
      
      Signature result: 1DC19ED63F755ACDE203614C8A1157EB1097E922                            
  • Request parameters
    Parameter Type Required Description
    groupId long Yes The ID of your application group.
    metricName string Yes The name of a metric that you want to monitor. A metric name can contain letters, digits, and connectors such as underscores (_), hyphens (-), periods (.), forward slashes (/), and backslashes (\). Other characters are invalid. The maximum length is 64 bytes. Excess characters are truncated from the string.
    dimensions object Yes The dimension map. All key-value pairs are strings. A string can contain letters, digits, and connectors such as underscores (_), hyphens (-), periods (.), forward slashes (/), and backslashes (\). The maximum number of key-value pairs is 10. The maximum length of a key is 64 bytes. The maximum length of a value is 64 bytes. Excess characters are truncated from the string.
    time string Yes The time when the metric value was generated. The time supports timestamps in the yyyyMMdd’T’HHmmss.SSSZ format or long format, such as 20171012T132456.888+0800 or 1508136760000.
    type int Yes

    The data type of the reported value. A value of 0 specifies raw data and a value of 1 specifies aggregate data.

    When you report aggregate data, we recommend that you report data for both 60s and 300s aggregation periods. Otherwise, you cannot query monitoring data in a time span that is more than seven days.

    period string No

    The aggregation period. Unit: seconds.

    If the type parameter is set to 1, this field is required. Valid values: 60 and 300.

    values object Yes The collection of metric values. If the type parameter is set to 0, the key of this parameter must be set to value, so raw data is reported. CloudMonitor aggregates raw data over the aggregation period into several data types, such as maximum, count, and sum.

Report data by using the Java SDK (Recommended)

  • Install the Java SDK
    When you install the Java SDK based on Maven, add the following dependency:
    <dependency>
                <groupId>com.aliyun.openservices</groupId>
                <artifactId>aliyun-cms</artifactId>
                <version>0.2.4</version>
    </dependency>
  • Response elements

    The system returns the HTTP status code 200.

  • Examples
    • Sample code (Java)
      import com.aliyuncs.DefaultAcsClient;
      import com.aliyuncs.IAcsClient;
      import com.aliyuncs.exceptions.ClientException;
      import com.aliyuncs.exceptions.ServerException;
      import com.aliyuncs.profile.DefaultProfile;
      import com.google.gson.Gson;
      import java.util.*;
      import com.aliyuncs.cms.model.v20190101.*;
      
      public class PutCustomMetric {
      
          public static void main(String[] args) {
              DefaultProfile profile = DefaultProfile.getProfile("cn-hangzhou", "<accessKeyId>", "<accessSecret>");
              IAcsClient client = new DefaultAcsClient(profile);
      
              PutCustomMetricRequest request = new PutCustomMetricRequest();
      
              List<PutCustomMetricRequest.MetricList> metricListList = new ArrayList<PutCustomMetricRequest.MetricList>();
      
              PutCustomMetricRequest.MetricList metricList1 = new PutCustomMetricRequest.MetricList();
              metricList1.setGroupId("0");
              metricList1.setMetricName("diskUtilization");
              metricList1.setDimensions("{\"hostName\":\"xxxxx\",\"disk\":\"/\"}");
              metricList1.setTime("20190612T132456.888 0800Z");
              metricList1.setType("0");
              metricList1.setPeriod("60");
              metricList1.setValues("{\"value\":20}");
              metricListList.add(metricList1);
              request.setMetricLists(metricListList);
      
              try {
                  PutCustomMetricResponse response = client.getAcsResponse(request);
                  System.out.println(new Gson().toJson(response));
              } catch (ServerException e) {
                  e.printStackTrace();
              } catch (ClientException e) {
                  System.out.println("ErrCode:" + e.getErrCode());
                  System.out.println("ErrMsg:" + e.getErrMsg());
                  System.out.println("RequestId:" + e.getRequestId());
              }
      
          }
      }                            
    • Sample code (Golang)
      package main
      
      import (
          "fmt"
            "github.com/aliyun/alibaba-cloud-sdk-go/services/cms"
      
      )
      
      func main() {
          client, err := cms.NewClientWithAccessKey("cn-hangzhou", "<accessKeyId>", "<accessSecret>")
      
          request := cms.CreatePutCustomMetricRequest()
          request.Scheme = "https"
      
        request.MetricList = &[]cms.PutCustomMetricMetricList{
          {
            GroupId: "0",
            MetricName: "diskUtilization",
            Dimensions: "{"hostName":"xxxxx","disk":"/"}",
            Time: "20190612T132456.888 0800Z",
            Type: "0",
            Period: "60",
            Values: "{"value":20}",
          },
        }
      
          response, err := client.PutCustomMetric(request)
          if err ! = nil {
              fmt.Print(err.Error())
          }
          fmt.Printf("response is %#v\n", response)
      }                            
    • Sample response
      {
          "Message": "success",
          "RequestId": "E25EE651-9C97-4EFD-AF22-A753B674E8D4",
          "Code": "200"
      }
    • Sample code for other programming languages
  • Automatically report aggregate data for multiple aggregation periods

    The Java SDK supports data reporting after local aggregation. Aggregation periods can be 60 seconds and 300 seconds.

    Data type Description Aggregate value Memory consumption (excluding the name, dimension, individual time series, and individual aggregation periods)
    value Typical value type All attributes except LastValue Approximately 4 KB
    gauge Sample value LastValue 4 bytes
    meter Sum and rate Sum, SumPerSecond 50 bytes
    counter Count SampleCount 10 bytes
    timer Computing time SampleCount, CountPerSecond, Average, Maximum, Minimum, and PXX(P10-P99) Approximately 4 KB
    histogram Distribution SampleCount, Average, Maximum, Minimum, and PXX(P10-P99) Approximately 4 KB
    //Initialization
            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 that includes two aggregation periods.
            //Or final MetricRegistry registry = builder.build(RecordLevel. _60S);//Create a registry that only includes aggregate data in a 1-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 an Alibaba Cloud account

Make sure that you have created an Alibaba Cloud account, created a RAM user for your account, and generated an AccessKey pair for the RAM user to grant CloudMonitor permissions.

  • Create a RAM user.

  • Generate an AccessKey ID and an AccessKey Secret for the RAM user.

  • Grant CloudMonitor permissions to the RAM user.

Install Alibaba Cloud CLI

Required operating systems: Linux, Unix, or macOS.

  • Method 1: download the installation package

    You can download the installation package of the latest CLI tool from Alibaba Cloud CLI GitHub, and decompress the package to use the CLI. The CLI supports Mac, Linux, and Windows (x64) terminals. After decompression, you can move the aliyun file to the /usr/local/bin directory or add the file to the $PATH environment variable.
  • Method 2: compile source code

    Install and configure the Golang environment, and follow these steps to download and compile the source code:
    ```
    $ mkdir -p $GOPATH/src/github.com/aliyun
    $ cd $GOPATH/src/github.com/aliyun
    $ git clone http://github.com/aliyun/aliyun-cli.git
    $ git clone http://github.com/aliyun/aliyun-openapi-meta.git
    $ cd aliyun-cli
    $ make install
    ```
Configure the CLI

Before using Alibaba Cloud CLI, you must run the aliyun configure command to configure the AccessKey pair, region, and language. You use the configured data to call Alibaba Cloud resources. You can create and view your AccessKey pair on the AccessKey page in the Alibaba Cloud console, or contact your system administrator to obtain the AccessKey pair.

$ aliyun configure
Configuring profile 'default' ...
Aliyun Access Key ID [None]: <Your AccessKey ID>
Aliyun Access Key Secret [None]: <Your AccessKey Secret>
Default Region Id [None]: cn-hangzhou
Default output format [json]: json
Default Language [zh]: zh

Multi-user configuration: Alibaba Cloud CLI supports multi-user configuration. You can run the $ aliyun configure --profile user1 command to specify the account used to call API operations of cloud services. Run the $ aliyun configure list command to view the current user configuration, as shown in the following table. The asterisk (*) next to the Profile field value indicates the default user configuration.

Profile Credential Valid Region Language
default * AK:***f9b Valid cn-beijing zh
aaa AK:****** Invalid
test AK:***456 Valid en
ecs EcsRamRole:EcsTest Valid cn-beijing en

To specify the authentication method, you can add the --mode <authenticationMethod> parameter to the end of the configure command in the CLI. Supported authentication methods are listed as follows:

Authentication method Description
AK Use the AccessKey ID and AccessKey Secret to authorize access permissions.
StsToken Use the Security Token Service (STS) token to authorize access permissions.
RamRoleArn Use AssumeRole of the RAM user to authorize access permissions.
EcsRamRole Use EcsRamRole on an ECS instance to access the instance with no password.
Report monitoring data

Call the PutCustomMetric API operation to report the monitoring data.

aliyun cms PutCustomMetric  --MetricList.1.MetricName cpu_total --MetricList.1.Dimensions '{"sampleName1":"value1","sampleName2":"value2"}' --MetricList.1.Time 1555390981421 --MetricList.1.Type 0 --MetricList.1.Period 60 --MetricList.1.Values '{"value":10.5}' --MetricList.1.GroupId "0"

The system returns Status code 200 to indicate successful reporting.

{
  "Message": "success",
  "RequestId": "F69F5623-DDD6-42AE-AE59-87A2B841620B",
  "Code": "200"
}
Error codes
Error code Description
200 The error message returned because you reported data successfully.
206

The error message returned because some data failed to be reported.

If the system returns "reach Max time series num", you have used up the time series quota. We recommend that you purchase a higher quota or remove unnecessary time series.

If the system returns "not allowed original value, please upgrade service", you have used a free edition. You cannot use this edition to report raw data.

If the system returns "type is invalid", the value of the type parameter was invalid. Make sure that the value of this parameter is 0 or 1.

400 The error message returned because a syntax error has occurred in the client request.
403 The error message returned because the verification failed, the target rate reached the upper limit, or the target permission was not authorized.
500 The error message returned because an internal server error has occurred.
Create a RAM user

To use the AccessKey pair of the corresponding RAM user to report event data, you must grant CloudMonitor permissions to the RAM user. If you have not granted the permissions, the system returns the error "cannot upload data, please use ram to auth" when you report data.

  1. Log on to the RAM console.
  2. In the left-side navigation pane, click Users to go to the Users page.
  3. On the Users page that appears, select the RAM user that you use to report data, and click Add Permissions in the Actions column next to the target RAM user.

  4. On the Add Permissions page, select AliyunCloudMonitorFullAccess and click OK.