Add the NOTNUMBOOL mutator

The "NOTNUMBOOL" mutator returns 1.0 when quantity is 0 and 0.0
otherwise.

Change-Id: I16f2b05dcd089b214e18762e1f87d0dbcc2cb7cc
(cherry picked from commit bf43a11)

Author: mkarpiarz

cloudkitty/collector/__init__.py

@@ -89,10 +89,11 @@ def MetricDict(value):
     Required('metadata', default=list): [
         All(str, Length(min=1))
     ],
-    # Mutate collected value. May be any of (NONE, NUMBOOL, FLOOR, CEIL).
+    # Mutate collected value. May be any of:
+    # (NONE, NUMBOOL, NOTNUMBOOL, FLOOR, CEIL).
     # Defaults to NONE
     Required('mutate', default='NONE'):
-        In(['NONE', 'NUMBOOL', 'FLOOR', 'CEIL']),
+        In(['NONE', 'NUMBOOL', 'NOTNUMBOOL', 'FLOOR', 'CEIL']),
     # Collector-specific args. Should be overriden by schema provided for
     # the given collector
     Optional('extra_args'): dict,

cloudkitty/utils/__init__.py

@@ -257,6 +257,9 @@ def mutate(value, mode='NONE'):
     if mode == 'NUMBOOL':
         return float(value != 0.0)
 
+    if mode == 'NOTNUMBOOL':
+        return float(value == 0.0)
+
     if mode == 'FLOOR':
         return math.floor(value)
 

doc/source/admin/configuration/collector.rst

@@ -186,6 +186,9 @@ Four values are accepted for this parameter:
 
 * ``NUMBOOL``: If the collected qty equals 0, leave it at 0. Else, set it to 1.
 
+* ``NOTNUMBOOL``: If the collected qty equals 0, set it to 1. Else, set it to
+  0.
+
 .. warning::
 
    Quantity mutation is done **after** conversion. Example::
@@ -214,6 +217,21 @@ then defined based on the instance metadata. Example:
        metadata:
          - flavor_id
 
+The ``NOTNUMBOOL`` mutator is useful for status-like metrics where 0 denotes
+the billable state. For example the following Prometheus metric has value of 0
+when the instance is in ACTIVE state but 4 if the instance is in ERROR state:
+
+.. code-block:: yaml
+
+   metrics:
+     openstack_nova_server_status:
+       unit: instance
+       mutate: NOTNUMBOOL
+       groupby:
+         - id
+       metadata:
+         - flavor_id
+
 Display name
 ~~~~~~~~~~~~
 

releasenotes/notes/notnumbool-mutator-ab056e86f2bc843d.yaml

@@ -0,0 +1,6 @@
+---
+features:
+  - |
+    The new "NOTNUMBOOL" mutator has been added. This mutator is, essentially,
+    an opposite of the "NUMBOOL" mutator as it returns 1.0 when quantity is 0
+    and 0.0 otherwise.