Add support for exporting metrics to a pushgateway

Author: mmoya

README.md

@@ -246,6 +246,22 @@ write_to_textfile('/configured/textfile/path/raid.prom', registry)
 A separate registry is used, as the default registry may contain other metrics
 such as those from the Process Collector.
 
+## Exporting to a Pushgateway
+
+The [Pushgateway](https://github.com/prometheus/pushgateway)
+allows ephemeral and batch jobs to expose their metrics to Prometheus.
+
+```python
+from prometheus_client import CollectorRegistry,Gauge,push_to_gateway
+registry = CollectorRegistry()
+g = Gauge('job_last_success_unixtime', 'Last time a batch job successfully finished', registry=registry)
+g.set_to_current_time()
+push_to_gateway(registry, job='batchA')
+```
+
+A separate registry is used, as the default registry may contain other metrics
+such as those from the Process Collector.
+
 ## Bridges
 
 It is also possible to expose metrics to systems other than Prometheus.

prometheus_client/__init__.py

@@ -4,6 +4,14 @@
 from . import exposition
 from . import process_collector
 
+try:
+    from urllib2 import urlopen, quote
+except ImportError:
+    # Python 3
+    from urllib.request import urlopen
+    from urllib.parse import quote
+
+
 __all__ = ['Counter', 'Gauge', 'Summary', 'Histogram']
 # http://stackoverflow.com/questions/19913653/no-unicode-in-all-for-a-packages-init
 __all__ = [n.encode('ascii') for n in __all__]
@@ -22,6 +30,38 @@
 start_http_server = exposition.start_http_server
 write_to_textfile = exposition.write_to_textfile
 
+
+def build_pushgateway_url(job, instance=None, host='localhost', port=9091):
+    '''
+    Build a valid pushgateway url
+    '''
+
+    if instance:
+        instancestr = '/instances/{}'.format(instance)
+    else:
+        instancestr = ''
+
+    url = 'http://{}:{}/metrics/jobs/{}{}'.format(host, port,
+                                                  quote(job),
+                                                  quote(instancestr))
+    return url
+
+
+def push_to_gateway_url(url, registry, timeout=None):
+    '''Push metrics to the given url'''
+
+    resp = urlopen(url, data=generate_latest(registry), timeout=timeout)
+    if resp.code >= 400:
+        raise IOError("error pushing to pushgateway: {0} {1}".format(
+            resp.code, resp.msg))
+
+
+def push_to_gateway(registry, job, instance=None, host='localhost', port=9091, timeout=None):
+    '''Push metrics to a pushgateway'''
+
+    url = build_pushgateway_url(job, instance, host, port)
+    push_to_gateway_url(url, registry, timeout)
+
 ProcessCollector = process_collector.ProcessCollector
 PROCESS_COLLECTOR = process_collector.PROCESS_COLLECTOR
 

tests/test_client.py

@@ -5,6 +5,7 @@
 
 from prometheus_client import Gauge, Counter, Summary, Histogram, Metric
 from prometheus_client import CollectorRegistry, generate_latest, ProcessCollector
+from prometheus_client import build_pushgateway_url
 
 
 class TestCounter(unittest.TestCase):
@@ -372,6 +373,24 @@ def test_working_fake_pid(self):
         self.assertEqual(None, self.registry.get_sample_value('process_fake_namespace'))
 
 
+class TestBuildPushgatewayUrl(unittest.TestCase):
+    def test_job_instance(self):
+        expected = 'http://localhost:9091/metrics/jobs/foojob/instances/fooinstance'
+
+        url = build_pushgateway_url('foojob', 'fooinstance')
+        self.assertEqual(url, expected)
+
+    def test_host_port(self):
+        expected = 'http://foohost:9092/metrics/jobs/foojob'
+
+        url = build_pushgateway_url('foojob', host='foohost', port=9092)
+        self.assertEqual(url, expected)
+
+    def test_url_escaping(self):
+        expected = 'http://localhost:9091/metrics/jobs/foo%20job'
+
+        url = build_pushgateway_url('foo job')
+        self.assertEqual(url, expected)
 
 
 if __name__ == '__main__':