Add memory.available metric

Add a new memory.available compute pollster metric that exposes
the memory available as seen by the instance itself.

This is different from the memory metric, which tracks the amount
of raw memory allocated to an instance by the hypervisor (and matches
the amount of memory configured in the instance flavour).

The memory.available and memory.usage metrics can be used in
Gnocchi aggregate queries to get the RAM usage of an instance
as a percentage, without needing to know the amount of RAM
allocated to, or actually available in, the instance beforehand.

Change-Id: I3be6dea1e81238d5d70a0c48e35013d0d4ec4e9e
Signed-off-by: Callum Dickinson <callum.dickinson@catalystcloud.nz>

ceilometer/compute/pollsters/instance_stats.py

@@ -50,6 +50,12 @@ class MemoryPollster(InstanceStatsPollster):
     sample_stats_key = 'memory_actual'
 
 
+class MemoryAvailablePollster(InstanceStatsPollster):
+    sample_name = 'memory.available'
+    sample_unit = 'MB'
+    sample_stats_key = 'memory_available'
+
+
 class MemoryUsagePollster(InstanceStatsPollster):
     sample_name = 'memory.usage'
     sample_unit = 'MB'

ceilometer/publisher/data/gnocchi_resources.yaml

@@ -77,6 +77,7 @@ resources:
   - resource_type: instance
     metrics:
       memory:
+      memory.available:
       memory.usage:
       memory.resident:
       memory.swap.in:

ceilometer/tests/unit/compute/pollsters/test_memory.py

@@ -62,6 +62,49 @@ class TestMemoryPollster(base.TestPollsterBase):
             return list(pollster.get_samples(mgr, {}, [self.instance]))
 
 
+class TestMemoryAvailablePollster(base.TestPollsterBase):
+
+    def test_get_samples(self):
+        self._mock_inspect_instance(
+            virt_inspector.InstanceStats(memory_available=1024.0),
+            virt_inspector.InstanceStats(memory_available=2048.0),
+            virt_inspector.InstanceStats(),
+            virt_inspector.InstanceShutOffException(),
+        )
+
+        mgr = manager.AgentManager(0, self.CONF)
+        pollster = instance_stats.MemoryAvailablePollster(self.CONF)
+
+        @mock.patch('ceilometer.compute.pollsters.LOG')
+        def _verify_memory_available_metering(expected_count,
+                                              expected_memory_mb,
+                                              expected_warnings,
+                                              mylog):
+            samples = list(pollster.get_samples(mgr, {}, [self.instance]))
+            self.assertEqual(expected_count, len(samples))
+            if expected_count > 0:
+                self.assertEqual({'memory.available'},
+                                 {s.name for s in samples})
+                self.assertEqual(expected_memory_mb, samples[0].volume)
+            else:
+                self.assertEqual(expected_warnings, mylog.warning.call_count)
+            self.assertEqual(0, mylog.exception.call_count)
+
+        _verify_memory_available_metering(1, 1024.0, 0)
+        _verify_memory_available_metering(1, 2048.0, 0)
+        _verify_memory_available_metering(0, 0, 1)
+        _verify_memory_available_metering(0, 0, 0)
+
+    def test_get_samples_with_empty_stats(self):
+
+        self._mock_inspect_instance(virt_inspector.NoDataException())
+        mgr = manager.AgentManager(0, self.CONF)
+        pollster = instance_stats.MemoryPollster(self.CONF)
+
+        def all_samples():
+            return list(pollster.get_samples(mgr, {}, [self.instance]))
+
+
 class TestMemoryUsagePollster(base.TestPollsterBase):
 
     def test_get_samples(self):

doc/source/admin/telemetry-measurements.rst

@@ -228,6 +228,14 @@ The following meters are collected for OpenStack Compute.
 | power.sta\| Gauge | state| instance | Pollster | Libvirt | virDomainState   |
 | te        |       |      | ID       |          |         | of the VM        |
 +-----------+-------+------+----------+----------+---------+------------------+
+| **Meters added in the Flamingo release**                                    |
++-----------+-------+------+----------+----------+---------+------------------+
+| memory.\  | Gauge | MB   | instance | Pollster | Libvirt | Volume of RAM    |
+| available |       |      | ID       |          |         | available to the |
+|           |       |      |          |          |         | instance as seen |
+|           |       |      |          |          |         | from within the  |
+|           |       |      |          |          |         | instance         |
++-----------+-------+------+----------+----------+---------+------------------+
 
 .. note::
 

etc/ceilometer/polling.yaml

@@ -5,6 +5,7 @@ sources:
       meters:
         - power.state
         - cpu
+        - memory.available
         - memory.usage
         - network.incoming.bytes
         - network.incoming.packets

releasenotes/notes/add-memory-available-metric-d59dc787c485efd3.yaml

@@ -0,0 +1,7 @@
+---
+features:
+  - |
+    Added a new ``memory.available`` compute pollster metric, for tracking the
+    amount of memory available within the instance, as seen by the instance.
+    This can be combined with ``memory.usage`` in Gnocchi aggregate queries to
+    get memory usage for an instance as a percentage.

setup.cfg

@@ -90,6 +90,7 @@ ceilometer.poll.compute =
     network.incoming.packets.error = ceilometer.compute.pollsters.net:IncomingErrorsPollster
     network.outgoing.packets.error = ceilometer.compute.pollsters.net:OutgoingErrorsPollster
     memory = ceilometer.compute.pollsters.instance_stats:MemoryPollster
+    memory.available = ceilometer.compute.pollsters.instance_stats:MemoryAvailablePollster
     memory.usage = ceilometer.compute.pollsters.instance_stats:MemoryUsagePollster
     memory.resident = ceilometer.compute.pollsters.instance_stats:MemoryResidentPollster
     memory.swap.in = ceilometer.compute.pollsters.instance_stats:MemorySwapInPollster