自定义监控功能为您提供上报监控数据的接口,方便您将自己采集的时序数据上报到云监控,并配置报警规则来接收报警通知。

云监控为您提供 OpenAPI、Java SDK 和阿里云命令行工具(CLI) 三种方式上报数据。

使用限制

  • 单云账号QPS限制为100。
  • 单次最多上报100条数据,body最大为256KB。
  • metricName字段只支持字母、数字、下划线。需要以字母开头,非字母开头会替换为大写“A”,非法字符替换为“_”。
  • dimensions字段不支持“=”、“&”、“,” ,非法字符会被替换为“_”。
  • metricName dimensions的Key-value 最大均为64字节,超过64字节会被截断。
  • 其他限制请关注计费方式

OpenAPI上报数据

  • 签名算法
  • 请求参数
    名称 类型 必选 描述
    groupId long 应用分组的id
    metricName string 监控项名称,支持字母、数字、连接符“_-./\”,其他为非法字符,最大长度为64字节,超过64字节时截取前64字节
    dimensions object 维度map,key-value都为字符串, 支持字母、数字、连接符“_-./\”,键值对数量最大为10,key长度最大64字节,value长度最大64字节,超过64字节时截取前64字节
    time string 指标发生时间,支持“yyyyMMdd’T’HHmmss.SSSZ”和long型时间戳2种方式,例如 “20171012T132456.888+0800”或“1508136760000”
    type int 上报数值的类型,0为原始值,1为聚合数据。当上报聚合数据时,建议60s、300s 周期的数据均上报,否则会无法正常查询跨度大于7天的监控数据。
    period string 聚合周期,单位为秒。如果 type=1则需要传此字段,取值为60、300
    values object 指标值集合,当type=0时,key只能为”value”,上报的是原始值,云监控会按周期将原始值聚合为多个值,比如最大、计数、求和等

    通过接口上报原始数据后,云监控会按以下统计方式计算1分钟、5分钟的统计结果:

    • Average:平均值
    • Maximum:最大值
    • Minimum:最小值
    • Sum:求和
    • SampleCount:计数
    • SumPerSecond:求和/对应周期的秒数,也可以使用滑动平均计算
    • CountPerSecond:计数/对应周期的秒数,也可以使用滑动平均计算
    • LastValue:本周期最后一个采样值,类似gauge
    • P10:percentile 0.1,大于10%本周期所有采样数据
    • P20:percentile 0.2,大于20%本周期所有采样数据
    • P30:percentile 0.3,大于30%本周期所有采样数据
    • P40:percentile 0.4,大于40%本周期所有采样数据
    • P50:percentile 0.5,大于50%本周期所有采样数据,中位数
    • P60:percentile 0.6,大于60%本周期所有采样数据
    • P70:percentile 0.7,大于70%本周期所有采样数据
    • P75:percentile 0.75,大于75%本周期所有采样数据
    • P80:percentile 0.8,大于80%本周期所有采样数据
    • P90:percentile 0.9,大于90%本周期所有采样数据
    • P95:percentile 0.95,大于95%本周期所有采样数据
    • P98:percentile 0.98,大于98%本周期所有采样数据
    • P99:percentile 0.99,大于99%本周期所有采样数据
  • Java SDK 安装
    通过maven进行安装,需要添加的依赖如下:
    <dependency>
                <groupId>com.aliyun.openservices</groupId>
                <artifactId>aliyun-cms</artifactId>
                <version>0.2.4</version>
    </dependency>
  • 响应元素

    HTTP 状态码返回 200。

  • 示例
    • 请求示例
      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}}]
    • 返回示例
      {
         "code":"200",
         "msg":""//正常上报时返回msg为空
      }

示例代码

  • 上报原始数据
    CMSClientInit.groupId = 101L;//设置公共的应用组id
            CMSClient cmsClient = new CMSClient(endpoint, accKey, secret);//初始化client
            CustomMetricUploadRequest request = CustomMetricUploadRequest.builder()
                    .append(CustomMetric.builder()
                            .setMetricName("testMetric")//指标名
                            .setGroupId(102L)//设置定制的分组id
                            .setTime(new Date())
                            .setType(CustomMetric.TYPE_VALUE)//类型为原始值,
                            .appendValue(MetricAttribute.VALUE, 1f)//原始值,key只能为这个
                            .appendDimension("key", "value")//添加维度
                            .appendDimension("ip", "127.0.0.1")//添加维度
                            .build())
                    .build();
            CustomMetricUploadResponse response = cmsClient.putCustomMetric(request);//上报
            System.out.println(JSONObject.toJSONString(response));
  • 自动完成多周期聚合上报

    SDK支持在本地做聚合后再上报数据的功能,聚合周期为1分钟、5分钟。

    数据类型 描述 聚合的值 内存消耗不含名称、维度,单时间序列,单聚合周期)
    value 一般值类型 除了LastValue外的所有属性 约4K
    gauge 采样值 LastValue 4字节
    meter 求和及速率 Sum,SumPerSecond 50字节
    counter 计数 SampleCount 10字节
    timer 计算时间 SampleCount、CountPerSecond、 Average、Maximum、Minimum、PXX(P10-P99) 约4K
    histogram 分布 SampleCount、Average、Maximum、Minimum、PXX(P10-P99) 约4K
    //初始化
            CMSClientInit.groupId = 0L;
            CMSClient cmsClient = new CMSClient(accKey, secret, endpoint);//创建client
            CMSMetricRegistryBuilder builder = new CMSMetricRegistryBuilder();
            builder.setCmsClient(cmsClient);
            final MetricRegistry registry = builder.build();//创建registry 包含2个聚合周期
            //或者 final MetricRegistry registry = builder.build(RecordLevel._60S);//只创建1分钟聚合周期的
    //使用value
    ValueWrapper value = registry.value(MetricName.build("value"));
    value.update(6.5);
    //使用meter
    MeterWrapper meter = registry.meter(MetricName.build("meter"));
    meter.update(7.2);
    //使用counter
    CounterWrapper counter = registry.counter(MetricName.build("counter"));
    counter.inc(20);
    counter.dec(5);
    //使用timer
    TimerWrapper timer = registry.timer(MetricName.build("timer"));
    timer.update(30, TimeUnit.MILLISECONDS);
    //使用histogram
    HistogramWrapper histogram = registry.histogram(MetricName.build("histogram"));
    histogram.update(20);
    //使用gauge
    final List list = new ArrayList();
    registry.gauge(MetricName.build("gauge"), new Gauge() {
                            @Override
                            public Number getValue() {
                                return list.size();
                            }
                        });

命令行(CLI)方式上报数据

拥有阿里云账号,并生成具有云监控权限的子账号AK(使用子账号安全性更好)。
  • 创建子账号。

  • 为子账号生成accesskeyid, accesskeysecrret。

  • 为子账号授权云监控权限。

操作流程

  1. 安装aliyuncli工具
    系统要求:Linux、UNIX 或 Mac OS。环境要求:已安装 Python 2.7.x。
    1. 安装 Python
      • 若您的设备已安装 Python 2.7.x 版本,请跳过此步骤。
      • 若您的设备没有安装 Python 2.7.x 版本,请在命令行窗口中执行下列命令,安装 Python。注意,请确保您的设备中已安装了 wget。
        wget https://www.python.org/ftp/python/2.7.8/Python-2.7.8.tgz (或者通过其他方式下载后放在某个路径下)
        tar -zxvf Python-2.7.8.tgz
        cd Python-2.7.8
        ./configure
        make
        sudo make install
    2. 安装 pip
      • 若您的设备已安装 pip,请跳过此步骤。
      • 若您的设备没有安装 pip,在命令行窗口中执行如下命令,安装 pip。
        curl "https://bootstrap.pypa.io/get-pip.py" -o "pip-install.py"
        sudo python pip-install.py
      • 系统显示如下类似信息,则表明安装成功。
        Successfully installed pip-7.1.2 setuptools-18.7 wheel-0.26.0
    3. 安装命令行工具

      如果系统内的 pip 版本过低,会造成 CLI 安装出错。用户可以使用如下指令先对 pip 软件进行升级后再进行相关操作。请使用 pip 7.x 或更高版本。若已是最新版本的 pip,请跳过此步骤。

      1. 在命令行窗口中执行如下命令,升级 pip。
        sudo pip install -U pip

        系统显示如下类似信息,则表明升级成功。

        Successfully uninstalled pip-7.1.2
        Successfully installed pip-8.1.2
      1. 执行如下命令,安装阿里云命令行工具。
        sudo pip install aliyuncli

        系统显示如下类似信息,则表明安装成功。

        Successfully installed aliyuncli-2.1.2 colorama-0.3.3 jmespath-0.7.1
    4. 配置命令行工具
      ~ 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
  2. 安装CmsSDK
    • Windows安装方式如下。
      cd C:\Python27\Scripts
      pip install aliyun-python-sdk-cms
    • 如果需要更新SDK,则使用如下命令。
      pip install --upgrade aliyun-python-sdk-cms
    • Linux 安装方式如下。
      sudo pip install aliyun-python-sdk-cms
    • 如果需要更新SDK,则使用如下命令。
      sudo pip install —upgrade aliyun-python-sdk-cms
  3. 上报监控数据

    使用PutCustomMetric接口。

    • Windows上报示例
      aliyuncli.exe cms PutCustomMetric --MetricList "[{'groupId':1,'metricName':'testMetric','dimensions':{'sampleName1':'value1','sampleName2':'value2'},'type':0,'values':{'value':10.5}}]"
    • Linux 上报示例
      aliyuncli cms PutCustomMetric --MetricList "[{'groupId':1,'metricName':'testMetric','dimensions':{'sampleName1':'value1','sampleName2':'value2'},'type':0,'values':{'value':10.5}}]"
    • 上报成功后,返回200状态码。
      {
      "Code":"200"
      }

错误编码

错误代码 含义
200 正常
400 客户端请求中的语法错误
403 校验失败、限速、没有授权
500 服务器内部错误

子账号授权说明

使用子账号的AK上报事件数据时,需要对相应子账号授权云监控管理权限。如果子账号未授权云监控管理权限,上报数据时会提示“cannot upload data, please use ram to auth”。

  1. 登录访问控制RAM控制台。
  2. 进入用户管理 菜单。
  3. 选择需要上报数据的子账号,在操作中点击授权

  4. 在授权页面中选择管理云监控的权限,并点击确定保存授权。