Add Info metric type.

brian-brazil · brian-brazil · commit 1807665a0eda · 2018-09-07T17:17:03.000+01:00
Signed-off-by: Brian Brazil &lt;brian.brazil@robustperception.io&gt;
diff --git a/README.md b/README.md
@@ -67,7 +67,7 @@ Counters go up, and reset when the process restarts.
 
 ```python
 from prometheus_client import Counter
-c = Counter('my_failures_total', 'Description of counter')
+c = Counter('my_failures', 'Description of counter')
 c.inc()     # Increment by 1
 c.inc(1.6)  # Increment by given value
 ```
@@ -169,6 +169,17 @@ with h.time():
   pass
 ```
 
+
+### Info
+
+Info tracks key-value information, usually about a whole target.
+
+```python
+from prometheus_client import Info
+i = Info('my_build_version', 'Description of info')
+i.info({'version': '1.2.3', 'buildhost': 'foo@bar'})
+```
+
 ### Labels
 
 All metrics can have labels, allowing grouping of related time series.
@@ -414,6 +425,7 @@ This comes with a number of limitations:
 
 - Registries can not be used as normal, all instantiated metrics are exported
 - Custom collectors do not work (e.g. cpu and memory metrics)
+- Info metrics do not work
 - The pushgateway cannot be used
 - Gauges cannot use the `pid` label
 
diff --git a/prometheus_client/__init__.py b/prometheus_client/__init__.py
@@ -5,7 +5,7 @@
 from . import process_collector
 from . import platform_collector
 
-__all__ = ['Counter', 'Gauge', 'Summary', 'Histogram']
+__all__ = ['Counter', 'Gauge', 'Summary', 'Histogram', 'Info']
 
 CollectorRegistry = core.CollectorRegistry
 REGISTRY = core.REGISTRY
@@ -14,6 +14,7 @@
 Gauge = core.Gauge
 Summary = core.Summary
 Histogram = core.Histogram
+Info = core.Info
 
 CONTENT_TYPE_LATEST = exposition.CONTENT_TYPE_LATEST
 generate_latest = exposition.generate_latest
diff --git a/prometheus_client/core.py b/prometheus_client/core.py
@@ -87,7 +87,8 @@ def _get_names(self, collector):
         type_suffixes = {
             'counter': ['_total', '_created'],
             'summary': ['', '_sum', '_count', '_created'],
-            'histogram': ['_bucket', '_sum', '_count', '_created']
+            'histogram': ['_bucket', '_sum', '_count', '_created'],
+            'info': ['_info'],
         }
         for metric in desc_func():
             for suffix in type_suffixes.get(metric.type, ['']):
@@ -150,7 +151,7 @@ def get_sample_value(self, name, labels=None):
 REGISTRY = CollectorRegistry(auto_describe=True)
 '''The default registry.'''
 
-_METRIC_TYPES = ('counter', 'gauge', 'summary', 'histogram', 'untyped')
+_METRIC_TYPES = ('counter', 'gauge', 'summary', 'histogram', 'untyped', 'info')
 
 
 class Metric(object):
@@ -327,6 +328,32 @@ def add_metric(self, labels, buckets, sum_value):
         self.samples.append((self.name + '_sum', dict(zip(self._labelnames, labels)), sum_value))
 
 
+class InfoMetricFamily(Metric):
+    '''A single info and its samples.
+
+    For use by custom collectors.
+    '''
+    def __init__(self, name, documentation, value=None, labels=None):
+        Metric.__init__(self, name, documentation, 'info')
+        if labels is not None and value is not None:
+            raise ValueError('Can only specify at most one of value and labels.')
+        if labels is None:
+            labels = []
+        self._labelnames = tuple(labels)
+        if value is not None:
+            self.add_metric([], value)
+
+    def add_metric(self, labels, value):
+        '''Add a metric to the metric family.
+
+        Args:
+          labels: A list of label values
+          value: A dict of labels
+        '''
+        self.samples.append((self.name + '_info', 
+            dict(dict(zip(self._labelnames, labels)), **value), 1))
+
+
 class _MutexValue(object):
     '''A float protected by a mutex.'''
 
@@ -899,7 +926,7 @@ def create_response(request):
     **NB** The Python client doesn't store or expose quantile information at this time.
     '''
     _type = 'histogram'
-    _reserved_labelnames = ['histogram']
+    _reserved_labelnames = ['le']
 
     def __init__(self, name, labelnames, labelvalues, buckets=(.005, .01, .025, .05, .075, .1, .25, .5, .75, 1.0, 2.5, 5.0, 7.5, 10.0, _INF)):
         self._sum = _ValueClass(self._type, name, name + '_sum', labelnames, labelvalues)
@@ -944,6 +971,46 @@ def _samples(self):
         return tuple(samples)
 
 
+@_MetricWrapper
+class Info(object):
+    '''Info metric, key-value pairs.
+
+     Examples of Info include:
+        - Build information
+        - Version information
+        - Potential target metadata
+
+     Example usage:
+        from prometheus_client import Info
+
+        g = Info('my_build_info', 'Description of info')
+        g.info({'version': '1.2.3', 'buildhost': 'foo@bar'})
+
+     Info metrics do not work in multiprocess mode.
+    '''
+    _type = 'info'
+    _reserved_labelnames = []
+    _labelnames = []
+    _value = {}
+
+    def __init__(self, name, labelnames, labelvalues):
+        self._labelnames = set(labelnames)
+        self._lock = Lock()
+
+    def info(self, val):
+        '''Set info metric.'''
+        if self._labelnames.intersection(val.keys()):
+            raise ValueError('Overlapping labels for Info metric, metric: %s child: %s' % (
+                self._labelnames, val))
+        with self._lock:
+            self._value = dict(val)
+
+
+    def _samples(self):
+        with self._lock:
+            return (('_info', self._value, 1.0,), )
+
+
 class _ExceptionCounter(object):
     def __init__(self, counter, exception):
         self._counter = counter
diff --git a/prometheus_client/exposition.py b/prometheus_client/exposition.py
@@ -10,8 +10,8 @@
 from contextlib import closing
 from wsgiref.simple_server import make_server, WSGIRequestHandler
 
-from . import core
-import openmetrics.exposition
+from prometheus_client import core
+from prometheus_client import openmetrics
 try:
     from BaseHTTPServer import BaseHTTPRequestHandler, HTTPServer
     from SocketServer import ThreadingMixIn
@@ -70,11 +70,15 @@ def generate_latest(registry=core.REGISTRY):
     output = []
     for metric in registry.collect():
         mname = metric.name
-        if metric.type == 'counter':
+        mtype = metric.type
+        if mtype == 'counter':
             mname = mname + '_total'
+        elif mtype == 'info':
+            mname = mname + '_info'
+            mtype = 'gauge'
         output.append('# HELP {0} {1}'.format(
             mname, metric.documentation.replace('\\', r'\\').replace('\n', r'\n')))
-        output.append('\n# TYPE {0} {1}\n'.format(mname, metric.type))
+        output.append('\n# TYPE {0} {1}\n'.format(mname, mtype))
         for name, labels, value in metric.samples:
             if name == metric.name + '_created':
                 continue  # Ignore OpenMetrics specific sample.
diff --git a/setup.py b/setup.py
@@ -15,6 +15,7 @@
     packages=[
         'prometheus_client',
         'prometheus_client.bridge',
+        'prometheus_client.openmetrics',
         'prometheus_client.twisted',
     ],
     extras_require={
diff --git a/tests/test_core.py b/tests/test_core.py
@@ -18,6 +18,8 @@
     GaugeMetricFamily,
     Histogram,
     HistogramMetricFamily,
+    Info,
+    InfoMetricFamily,
     Metric,
     Summary,
     SummaryMetricFamily,
@@ -287,6 +289,8 @@ def test_setting_buckets(self):
         self.assertRaises(ValueError, Histogram, 'h', 'help', registry=None, buckets=[3, 1])
 
     def test_labels(self):
+        self.assertRaises(ValueError, Histogram, 'h2', 'help', registry=None, labelnames=['le'])
+
         self.labels.labels('a').observe(2)
         self.assertEqual(0, self.registry.get_sample_value('hl_bucket', {'le': '1.0', 'l': 'a'}))
         self.assertEqual(1, self.registry.get_sample_value('hl_bucket', {'le': '2.5', 'l': 'a'}))
@@ -295,6 +299,7 @@ def test_labels(self):
         self.assertEqual(1, self.registry.get_sample_value('hl_count', {'l': 'a'}))
         self.assertEqual(2, self.registry.get_sample_value('hl_sum', {'l': 'a'}))
 
+
     def test_function_decorator(self):
         self.assertEqual(0, self.registry.get_sample_value('h_count'))
         self.assertEqual(0, self.registry.get_sample_value('h_bucket', {'le': '+Inf'}))
@@ -339,6 +344,25 @@ def test_block_decorator(self):
         self.assertEqual(1, self.registry.get_sample_value('h_bucket', {'le': '+Inf'}))
 
 
+class TestInfo(unittest.TestCase):
+    def setUp(self):
+        self.registry = CollectorRegistry()
+        self.info = Info('i', 'help', registry=self.registry)
+        self.labels = Info('il', 'help', ['l'], registry=self.registry)
+
+    def test_info(self):
+        self.assertEqual(1, self.registry.get_sample_value('i_info', {}))
+        self.info.info({'a': 'b', 'c': 'd'})
+        self.assertEqual(None, self.registry.get_sample_value('i_info', {}))
+        self.assertEqual(1, self.registry.get_sample_value('i_info', {'a': 'b', 'c': 'd'}))
+
+    def test_labels(self):
+        self.assertRaises(ValueError, self.labels.labels('a').info, {'l': ''})
+
+        self.labels.labels('a').info({'foo': 'bar'})
+        self.assertEqual(1, self.registry.get_sample_value('il_info', {'l': 'a', 'foo': 'bar'}))
+
+
 class TestMetricWrapper(unittest.TestCase):
     def setUp(self):
         self.registry = CollectorRegistry()
@@ -490,6 +514,16 @@ def test_histogram_labels(self):
         self.assertEqual(2, self.registry.get_sample_value('h_count', {'a': 'b'}))
         self.assertEqual(3, self.registry.get_sample_value('h_sum', {'a': 'b'}))
 
+    def test_info(self):
+        self.custom_collector(InfoMetricFamily('i', 'help', value={'a': 'b'}))
+        self.assertEqual(1, self.registry.get_sample_value('i_info', {'a': 'b'}))
+
+    def test_info_labels(self):
+        cmf = InfoMetricFamily('i', 'help', labels=['a'])
+        cmf.add_metric(['b'], {'c': 'd'})
+        self.custom_collector(cmf)
+        self.assertEqual(1, self.registry.get_sample_value('i_info', {'a': 'b', 'c': 'd'}))
+
     def test_bad_constructors(self):
         self.assertRaises(ValueError, UntypedMetricFamily, 'u', 'help', value=1, labels=[])
         self.assertRaises(ValueError, UntypedMetricFamily, 'u', 'help', value=1, labels=['a'])
@@ -513,6 +547,9 @@ def test_bad_constructors(self):
         self.assertRaises(ValueError, HistogramMetricFamily, 'h', 'help', buckets={}, sum_value=1, labels=['a'])
         self.assertRaises(KeyError, HistogramMetricFamily, 'h', 'help', buckets={}, sum_value=1)
 
+        self.assertRaises(ValueError, InfoMetricFamily, 'i', 'help', value={}, labels=[])
+        self.assertRaises(ValueError, InfoMetricFamily, 'i', 'help', value={}, labels=['a'])
+
     def test_labelnames(self):
         cmf = UntypedMetricFamily('u', 'help', labels=iter(['a']))
         self.assertEqual(('a',), cmf._labelnames)
diff --git a/tests/test_exposition.py b/tests/test_exposition.py
@@ -9,7 +9,7 @@
 else:
     import unittest
 
-from prometheus_client import Gauge, Counter, Summary, Histogram, Metric
+from prometheus_client import Gauge, Counter, Summary, Histogram, Info, Metric
 from prometheus_client import CollectorRegistry, generate_latest
 from prometheus_client import push_to_gateway, pushadd_to_gateway, delete_from_gateway
 from prometheus_client import CONTENT_TYPE_LATEST, instance_ip_grouping_key
@@ -72,6 +72,11 @@ def test_histogram(self):
 hh_sum 0.05
 ''', generate_latest(self.registry))
 
+    def test_info(self):
+        i = Info('ii', 'A info', ['a', 'b'], registry=self.registry)
+        i.labels('c', 'd').info({'foo': 'bar'})
+        self.assertEqual(b'# HELP ii_info A info\n# TYPE ii_info gauge\nii_info{a="c",b="d",foo="bar"} 1.0\n', generate_latest(self.registry))
+
     def test_unicode(self):
         c = Counter('cc', '\u4500', ['l'], registry=self.registry)
         c.labels('\u4500').inc()
