To get help at the command line just type: 


To get help on a specific command: 

ceilometer help COMMAND

For example: 

ceilometer help meter-list


A meter measures an aspect of resource usage.

A meter has a name, a type and a unit of measurement associated with it

List all the meters ever created in your tenancyceilometer meter-list
List all the meters for a given resourceceilometer meter-list -q 'resource_id=RESOURCE_ID'


Samples are data points associated with a meter, so they have the same attributes as a meter (name, a type, and unit), but to these attributes is added a timestamp and a value (termed the 'volume').

Meters and samples will live on beyond the life of the resource that they are associated with.

List all the samples for a given meterceilometer sample-list -m METER_NAME
To narrow the samples down to a specific instanceceilometer sample-list -m instance -q 'resource_id=RESOURCE_ID'
To narrow the samples down to a specific instance between two timesceilometer sample-list -m instance -q 'resource_id=RESOURCE_ID;timestamp>2014-05-29T05:47;timestamp<2014-05-29T06:01'

The format of a query string argument is: 

-q ';...;'

where operator_1..operator_n are one of <, <=, =, !=, >= >


A 'statistic' is the aggregation of a set of samples between a start time and an end time grouped by period. There are 5 different functions that are applied to all the samples falling within the period that is set:

  • Average: The average of the samples

  • Count: The number of samples recorded

  • Maximum: The largest of the samples recorded

  • Min: The smallest of the samples recorded

  • Sum: The sum of the samples recorded.

Calculate the statistics for a given meter, resource and periodceilometer statistics --meter METER_NAME --period SOME_PERIOD -q 'resource_id=RESOURCE_ID'


An alarm is a monitor of a statistic that will trigger when a threshold condition is breached.

Any alarm you define will have one of the following states:

  • alarm the threshold condition is breached.

  • ok the threshold condition is not met.

  • insufficient data not enough data has been gathered to determine if the alarm should fire or not.

The transition into each of these states can have an action associated with it. That action is a http post to a url of your choosing.

To see the current alarmsceilometer alarm-list
To drill down to a specific alarmceilometer alarm-show -a ALARM_ID
To the history of an alarmceilometer alarm-history -a ALARM_ID
To delete an alarm$ ceilometer alarm-delete -a ALARM_ID

Sample create alarm calls: 

ceilometer alarm-threshold-create --name warn_on_high_cpu --description 'alert on heavy usage' \ --meter-name cpu_util --threshold 30 --comparison-operator ge --statistic max --period 600 \ --evaluation-periods 1 --alarm-action '' \ --insufficient-data-action '' \ --ok-action '' \ --query resource_id=40d1ea5a-562d-4bb9-822a-912f16a978c2
ceilometer alarm-threshold-create --name warn_on_high_instance_count \ --description 'squeal if too many instances' \ --meter-name instance --threshold 2 --comparison-operator ge --statistic count --period 20 \ --evaluation-period 1 \ --alarm-action 'log://'


The NeCTAR Ceilometer documentation:

Notes on installing DevStack in a Vagrant VM: