These are the API calls for listing, creating, updating and deleting Metric Groups.
A Metric for the purposes of this document is simply a quantity that we want to measure, record, chart and alert on. Each metric, whether ‘built-in’ or user-defined, is an object, characterized by a hash:
Metric Hash
{ "type"=> METRIC_TYPE, # "ce_counter", "ce_gauge" or "ce_gauge_f"
"name" => METRIC_NAME, # built-in or user-defined, string
"position" => METRIC_ARRAY_INDEX, # position is an array index, assigned by Uptime Cloud Monitor
"label" => METRIC_LABEL, # user-friendly text describing the metric, string
"unit" => METRIC_UNIT # the units being measured, string
}
For example, you will see this (Ruby-formatted) metric hash in a subsequent example:
{
"type"=>"ce_counter", # METRIC_TYPE
"name"=>"uptime", # METRIC_NAME
"position"=>0, # METRIC_ARRAY_INDEX
"label"=>"Uptime", # METRIC_LABEL
"unit"=>"Seconds" # METRIC_UNIT
}
A Metric Group is a built-in or user-defined collection of Metrics, along with some metadata describing the group. Every Metric Group includes an array of metric hashes. The array of metric hashes must have at least one element. In fact, a Metric Group is an object characterized by a hash:
Metric Group Hash (Ruby-formatted)
{
"id"=>METRIC_GROUP_ID, # a unique Metric Group ID, assigned by Uptime Cloud Monitor
"name"=>METRIC_GROUP_NAME, # a unique name, built-in or user-defined, string
"idp"=>INTERNAL_USE, # internal use
"label"=>METRIC_GROUP_LABEL, # user-friendly text describing the metric group, string
"frequency"=>POLLING_INTERVAL, # polling interval in seconds; defaults to 60
"metrics"=>[ # the array of metrics that define this group (see above)
{METRIC_HASH},
{METRIC_HASH}
]
}
Metric Group Hash (JSON-formatted)
{
"id":"redis", # METRIC_GROUP_ID
"name":"redis", # METRIC_GROUP_NAME
"idp":"custom|",
"label":"Redis Metrics", # METRIC_GROUP_LABEL
"frequency":60, # POLLING_INTERVAL
"metrics":[ {}, {} ] # array of metrics hashes
}
Summing up:
List all defined Custom Metrics Metric Groups.
None.
None.
curl -su <APIKEY>:U https://api.copperegg.com/v2/revealmetrics/metric_groups.json
curl -s https://<APIKEY>:U@api.copperegg.com/v2/revealmetrics/metric_groups.json
Response is a JSON array of Metric Group hashes. In this example, there is one metric group defined, which contains 6 metrics.
[
{
"id":"redis", # METRIC_GROUP_ID, a unique identifier assigned by Uptime Cloud Monitor
"name":"redis", # METRIC_GROUP_NAME, user-defined metric group name
"idp":"custom|", # internal use only
"label":"Redis Metrics", # METRIC_GROUP_LABEL
"frequency":60, # POLLING_INTERVAL, defaults to 60 seconds.
"metrics":[ # the array of metrics in this group
{
"type":"ce_counter", # METRIC_TYPE
"name":"uptime", # METRIC_NAME
"position":0, # METRIC_ARRAY_INDEX
"label":"Uptime", # METRIC_LABEL
"unit":"Seconds" # the units of this metric
},
{
"type":"ce_gauge_f",
"name":"used_cpu_sys",
"position":1,
"label":"Used cpu sys",
"unit":"Percent"
},
{
"type":"ce_gauge_f",
"name":"used_cpu_user",
"position":2,
"label":"Used cpu user",
"unit":"Percent"
},
{
"type":"ce_gauge",
"name":"connected_clients",
"position":3,
"label":"Connected clients",
"unit":"Clients"
},
{
"type":"ce_gauge",
"name":"connected_slaves",
"position":4,
"label":"Connected slaves",
"unit":"Slaves"
},
{
"type":"ce_gauge",
"name":"blocked_clients",
"position":5,
"label":"Blocked clients",
"unit":"Clients"
}
]
}
]
Show all details of a single Metric Group.
METRIC_GROUP_ID as part of the path
None.
curl -su <APIKEY>:U https://api.copperegg.com/v2/revealmetrics/metric_groups/METRIC_GROUP_ID.json
Response is single Metric Group Hash. In this example, the metric group is the same as that returned in the Index example.
[
{
"id":"redis",
"name":"redis",
"idp":"custom|",
"label":"Redis Metrics",
"frequency":60,
"metrics":[
{
"type":"ce_counter",
"name":"uptime",
"position":0,
"label":"Uptime",
"unit":"Seconds"
},
{
"type":"ce_gauge_f",
"name":"used_cpu_sys",
"position":1,
"label":"Used cpu sys",
"unit":"Percent"
},
{
"type":"ce_gauge_f",
"name":"used_cpu_user",
"position":2,
"label":"Used cpu user",
"unit":"Percent"
},
{
"type":"ce_gauge",
"name":"connected_clients",
"position":3,
"label":"Connected clients",
"unit":"Clients"
},
{
"type":"ce_gauge",
"name":"connected_slaves",
"position":4,
"label":"Connected slaves",
"unit":"Slaves"
},
{
"type":"ce_gauge",
"name":"blocked_clients",
"position":5,
"label":"Blocked clients",
"unit":"Clients"
}
]
}
]
Create a new Metric Group.
You must include a metric group “name” string and an array of metrics. The metric group name can not contain spaces or periods.
Each Metric hash must contain 3 key-value pairs: type, name, and unit. You can optionally specify a label.
frequency if not included, the polling frequency will be once per minute. (polling period 60 seconds)
label if not included, a default label will be created. Be descriptive!!!
We’ll also use the bare minimum required parameters, to demonstrate the defaults.
curl -su <APIKEY>:U -H "Content-type: application/json" -XPOST https://api.copperegg.com/v2/revealmetrics/metric_groups.json -d '{"name":"myredis","metrics":[{"type":"ce_counter","name":"uptime","unit":"Seconds"},{"type":"ce_gauge","name":"connected_clients","unit":"Clients"}]}'
Response is Status 200, and the metric group hash created:
{
"id":"myredis",
"name":"myredis",
"idp":"custom|",
"label":"Myredis",
"frequency":60,
"metrics":[
{
"type":"ce_counter",
"name":"uptime",
"position":0,
"label":"Uptime",
"unit":"Seconds"
},
{
"type":"ce_gauge",
"name":"connected_clients",
"position":1,
"label":"Connected clients",
"unit":"Clients"
}
]
}
This time we’ll specify frequency and labels.
curl -su <APIKEY>:U -H "Content-type: application/json" -XPOST https://api.copperegg.com/v2/revealmetrics/metric_groups.json -d '{"name":"newredis","frequency":15,"label":"Well-Labelled Redis","metrics":[{"type":"ce_counter","name":"uptime","label":"UPTIME","unit":"Seconds"},{"type":"ce_gauge","name":"connected_clients","unit":"Clients"}]}'
Response is Status 200, and the metric group hash created:
{
"id":"newredis",
"name":"newredis",
"idp":"custom|",
"label":"Well-Labelled Redis", # our verbose label
"frequency":15, # our non-default polling frequency
"metrics":[
{
"type":"ce_counter",
"name":"uptime",
"position":0,
"label":"UPTIME", # our non-default label
"unit":"Seconds"
},
{
"type":"ce_gauge",
"name":"connected_clients",
"position":1,
"label":"Connected clients",
"unit":"Clients"
}
]
}
curl -su <APIKEY>:U -H "Content-type: application/json" -XPOST https://api.copperegg.com/v2/revealmetrics/metric_groups.json -d '{"name":"new redis","frequency":15,"label":"Well-Labelled Redis","metrics":[{"type":"ce_counter","name":"uptime","label":"UPTIME","unit":"Seconds"},{"type":"ce_gauge","name":"connected_clients","unit":"Clients"}]}'
Response is Status 403 and an error message is returned:
{
"error": true,
"error_type": "message",
"message": "error: Metric Group name can not contain spaces or periods."
}
Update an existing Metric Group.
METRIC_GROUP_ID as part of the path
frequency, if you want to alter it
any labels that you want to alter
add new metrics
curl -su <APIKEY>:U -H "Content-type: application/json" -XPUT https://api.copperegg.com/v2/revealmetrics/metric_groups/<METRIC_GROUP_ID> -d '{<UPDATED_VALUES_HASH>}'
curl -su <APIKEY>:U -H "Content-type: application/json" -XPUT https://api.copperegg.com/v2/revealmetrics/metric_groups/myredis.json -d '{"frequency":15}'
Response is Status 200, updated metric group hash:
{
"id":"myredis",
"name":"myredis",
"idp":"custom|",
"label":"Myredis",
"frequency":15,
"metrics":[
{
"type":"ce_counter",
"name":"uptime",
"position":0,
"label":"Uptime",
"unit":"Seconds"
},
{
"type":"ce_gauge",
"name":"connected_clients",
"position":1,
"label":"Connected clients",
"unit":"Clients"
}
]
}
NOTE: You don’t need to repeat the already-existing metrics.
curl -su <APIKEY>:U -H "Content-type: application/json" -XPUT https://api.copperegg.com/v2/revealmetrics/metric_groups/myredis4.json -d '{"metrics":[{"type":"ce_gauge","name":"connected_slaves","unit":"Slaves"}]}'
Response is Status 200, updated metric group hash:
{
"id":"myredis",
"name":"myredis",
"idp":"custom|",
"label":"Myredis",
"frequency":15,
"metrics":[
{
"type":"ce_counter",
"name":"uptime",
"position":0,
"label":"Uptime",
"unit":"Seconds"
},
{
"type":"ce_gauge",
"name":"connected_clients",
"position":1,
"label":"Connected clients",
"unit":"Clients"
},
{
"type":"ce_gauge",
"name":"connected_slaves",
"position":2,
"label":"Connected slaves",
"unit":"Slaves"
}
]
}
Delete the specified Metric Group.
METRIC_GROUP_ID as part of the path
None
curl -su <APIKEY>:U -XDELETE https://api.copperegg.com/v2/revealmetrics/metric_groups/<METRICGROUP_ID>.json
Response is Status 200, empty JSON:
{}