Merge pull request #15 from faucetsdn/v0.20.0

Upgrade python3-prometheus-client to v0.20.0.

Author: gizmoguy

docs/content/exporting/http/_index.md

@@ -18,6 +18,15 @@ start_http_server(8000)
 
 Visit [http://localhost:8000/](http://localhost:8000/) to view the metrics.
 
+The function will return the HTTP server and thread objects, which can be used
+to shutdown the server gracefully:
+
+```python
+server, t = start_http_server(8000)
+server.shutdown()
+t.join()
+```
+
 To add Prometheus exposition to an existing HTTP server, see the `MetricsHandler` class
 which provides a `BaseHTTPRequestHandler`. It also serves as a simple example of how
 to write a custom endpoint.

docs/content/instrumenting/_index.md

@@ -13,4 +13,8 @@ on how to use them.
 By default counters, histograms, and summaries export an additional series
 suffixed with `_created` and a value of the unix timestamp for when the metric
 was created. If this information is not helpful, it can be disabled by setting
-the environment variable `PROMETHEUS_DISABLE_CREATED_SERIES=True`.
+the environment variable `PROMETHEUS_DISABLE_CREATED_SERIES=True` or in code:
+```python
+from prometheus_client import disable_created_metrics
+disable_created_metrics()
+```

docs/content/multiprocess/_index.md

@@ -18,6 +18,7 @@ This comes with a number of limitations:
 - The pushgateway cannot be used
 - Gauges cannot use the `pid` label
 - Exemplars are not supported
+- Remove and Clear of labels are currently not supported in multiprocess mode.
 
 There's several steps to getting this working:
 

prometheus_client/exposition.py

@@ -154,7 +154,7 @@ def _get_best_family(address, port):
     # binding an ipv6 address is requested.
     # This function is based on what upstream python did for http.server
     # in https://github.com/python/cpython/pull/11767
-    infos = socket.getaddrinfo(address, port)
+    infos = socket.getaddrinfo(address, port, type=socket.SOCK_STREAM, flags=socket.AI_PASSIVE)
     family, _, _, _, sockaddr = next(iter(infos))
     return family, sockaddr[0]
 
@@ -210,7 +210,7 @@ def start_wsgi_server(
         client_capath: Optional[str] = None,
         protocol: int = ssl.PROTOCOL_TLS_SERVER,
         client_auth_required: bool = False,
-) -> None:
+) -> Tuple[WSGIServer, threading.Thread]:
     """Starts a WSGI server for prometheus metrics as a daemon thread."""
 
     class TmpServer(ThreadingWSGIServer):
@@ -226,6 +226,8 @@ class TmpServer(ThreadingWSGIServer):
     t.daemon = True
     t.start()
 
+    return httpd, t
+
 
 start_http_server = start_wsgi_server
 

prometheus_client/metrics.py

@@ -6,6 +6,7 @@
     Any, Callable, Dict, Iterable, List, Literal, Optional, Sequence, Tuple,
     Type, TypeVar, Union,
 )
+import warnings
 
 from . import values  # retain this import style for testability
 from .context_managers import ExceptionCounter, InprogressTracker, Timer
@@ -210,6 +211,11 @@ def labels(self: T, *labelvalues: Any, **labelkwargs: Any) -> T:
             return self._metrics[labelvalues]
 
     def remove(self, *labelvalues: Any) -> None:
+        if 'prometheus_multiproc_dir' in os.environ or 'PROMETHEUS_MULTIPROC_DIR' in os.environ:
+            warnings.warn(
+                "Removal of labels has not been implemented in  multi-process mode yet.",
+                UserWarning)
+
         if not self._labelnames:
             raise ValueError('No label names were set when constructing %s' % self)
 
@@ -222,6 +228,10 @@ def remove(self, *labelvalues: Any) -> None:
 
     def clear(self) -> None:
         """Remove all labelsets from the metric"""
+        if 'prometheus_multiproc_dir' in os.environ or 'PROMETHEUS_MULTIPROC_DIR' in os.environ:
+            warnings.warn(
+                "Clearing labels has not been implemented in multi-process mode yet",
+                UserWarning)
         with self._lock:
             self._metrics = {}
 
@@ -282,6 +292,12 @@ def f():
         # Count only one type of exception
         with c.count_exceptions(ValueError):
             pass
+            
+    You can also reset the counter to zero in case your logical "process" restarts
+    without restarting the actual python process.
+
+       c.reset()
+
     """
     _type = 'counter'
 
@@ -300,6 +316,11 @@ def inc(self, amount: float = 1, exemplar: Optional[Dict[str, str]] = None) -> N
             _validate_exemplar(exemplar)
             self._value.set_exemplar(Exemplar(exemplar, amount, time.time()))
 
+    def reset(self) -> None:
+        """Reset the counter to zero. Use this when a logical process restarts without restarting the actual python process."""
+        self._value.set(0)
+        self._created = time.time()
+
     def count_exceptions(self, exception: Union[Type[BaseException], Tuple[Type[BaseException], ...]] = Exception) -> ExceptionCounter:
         """Count exceptions in a block of code or function.
 

prometheus_client/openmetrics/exposition.py

@@ -3,7 +3,7 @@
 
 from ..utils import floatToGoString
 
-CONTENT_TYPE_LATEST = 'application/openmetrics-text; version=0.0.1; charset=utf-8'
+CONTENT_TYPE_LATEST = 'application/openmetrics-text; version=1.0.0; charset=utf-8'
 """Content type of the latest OpenMetrics text format"""
 
 

setup.py

@@ -8,7 +8,7 @@
 
 setup(
     name="prometheus_client",
-    version="0.19.0",
+    version="0.20.0",
     author="Brian Brazil",
     author_email="brian.brazil@robustperception.io",
     description="Python client for the Prometheus monitoring system.",

tests/test_core.py

@@ -43,6 +43,16 @@ def test_increment(self):
         self.counter.inc(7)
         self.assertEqual(8, self.registry.get_sample_value('c_total'))
 
+    def test_reset(self):
+        self.counter.inc()
+        self.assertNotEqual(0, self.registry.get_sample_value('c_total'))
+        created = self.registry.get_sample_value('c_created')
+        time.sleep(0.05)
+        self.counter.reset()        
+        self.assertEqual(0, self.registry.get_sample_value('c_total'))
+        created_after_reset = self.registry.get_sample_value('c_created')
+        self.assertLess(created, created_after_reset)       
+
     def test_repr(self):
         self.assertEqual(repr(self.counter), "prometheus_client.metrics.Counter(c)")
 

tests/test_multiprocess.py

@@ -381,6 +381,22 @@ def test_missing_gauge_file_during_merge(self):
             os.path.join(self.tempdir, 'gauge_livesum_9999999.db'),
         ]))
 
+    def test_remove_clear_warning(self):
+        os.environ['PROMETHEUS_MULTIPROC_DIR'] = self.tempdir
+        with warnings.catch_warnings(record=True) as w:
+            values.ValueClass = get_value_class()
+            registry = CollectorRegistry()
+            collector = MultiProcessCollector(registry)
+            counter = Counter('c', 'help', labelnames=['label'], registry=None)
+            counter.labels('label').inc()
+            counter.remove('label')
+            counter.clear()
+            assert os.environ['PROMETHEUS_MULTIPROC_DIR'] == self.tempdir
+            assert issubclass(w[0].category, UserWarning)
+            assert "Removal of labels has not been implemented" in str(w[0].message)
+            assert issubclass(w[-1].category, UserWarning)
+            assert "Clearing labels has not been implemented" in str(w[-1].message)
+
 
 class TestMmapedDict(unittest.TestCase):
     def setUp(self):