Merge pull request #10 from faucetsdn/v0.17.0

Upgrade python3-prometheus-client to v0.17.0.

Author: gizmoguy

MANIFEST.in

@@ -1,2 +1,4 @@
-recursive-include tests *
-prune tests/__pycache__
+graft tests
+global-exclude *.py[cod]
+prune __pycache__
+prune */__pycache__

README.md

@@ -416,6 +416,55 @@ uwsgi --http 127.0.0.1:8000 --wsgi-file myapp.py --callable app
 
 Visit http://localhost:8000/metrics to see the metrics
 
+#### FastAPI + Gunicorn
+
+To use Prometheus with [FastAPI](https://fastapi.tiangolo.com/) and [Gunicorn](https://gunicorn.org/) we need to serve metrics through a Prometheus ASGI application.
+
+Save the snippet below in a `myapp.py` file
+
+```python
+from fastapi import FastAPI
+from prometheus_client import make_asgi_app
+
+# Create app
+app = FastAPI(debug=False)
+
+# Add prometheus asgi middleware to route /metrics requests
+metrics_app = make_asgi_app()
+app.mount("/metrics", metrics_app)
+```
+
+For Multiprocessing support, use this modified code snippet. Full multiprocessing intstructions are provided [here](https://github.com/prometheus/client_python#multiprocess-mode-eg-gunicorn).
+
+```python
+from fastapi import FastAPI
+from prometheus_client import make_asgi_app
+
+app = FastAPI(debug=False)
+
+# Using multiprocess collector for registry
+def make_metrics_app():
+    registry = CollectorRegistry()
+    multiprocess.MultiProcessCollector(registry)
+    return make_asgi_app(registry=registry)
+
+
+metrics_app = make_metrics_app()
+app.mount("/metrics", metrics_app)
+```
+
+Run the example web application like this
+
+```bash
+# Install gunicorn if you do not have it
+pip install gunicorn
+# If using multiple workers, add `--workers n` parameter to the line below
+gunicorn -b 127.0.0.1:8000 myapp:app -k uvicorn.workers.UvicornWorker
+```
+
+Visit http://localhost:8000/metrics to see the metrics
+
+
 ### Node exporter textfile collector
 
 The [textfile collector](https://github.com/prometheus/node_exporter#textfile-collector)

prometheus_client/context_managers.py

@@ -46,7 +46,7 @@ def __enter__(self):
     def __exit__(self, typ, value, traceback):
         self._gauge.dec()
 
-    def __call__(self, f):
+    def __call__(self, f: "F") -> "F":
         def wrapped(func, *args, **kwargs):
             with self:
                 return func(*args, **kwargs)
@@ -75,7 +75,7 @@ def __exit__(self, typ, value, traceback):
     def labels(self, *args, **kw):
         self._metric = self._metric.labels(*args, **kw)
 
-    def __call__(self, f):
+    def __call__(self, f: "F") -> "F":
         def wrapped(func, *args, **kwargs):
             # Obtaining new instance of timer every time
             # ensures thread safety and reentrancy.

prometheus_client/gc_collector.py

@@ -22,7 +22,7 @@ def collect(self) -> Iterable[Metric]:
         )
         uncollectable = CounterMetricFamily(
             'python_gc_objects_uncollectable',
-            'Uncollectable object found during GC',
+            'Uncollectable objects found during GC',
             labels=['generation'],
         )
 

prometheus_client/parser.py

@@ -1,11 +1,12 @@
 import io as StringIO
 import re
+from typing import Dict, Iterable, List, Match, Optional, TextIO, Tuple
 
 from .metrics_core import Metric
 from .samples import Sample
 
 
-def text_string_to_metric_families(text):
+def text_string_to_metric_families(text: str) -> Iterable[Metric]:
     """Parse Prometheus text format from a unicode string.
 
     See text_fd_to_metric_families.
@@ -20,32 +21,32 @@ def text_string_to_metric_families(text):
 }
 
 
-def replace_escape_sequence(match):
+def replace_escape_sequence(match: Match[str]) -> str:
     return ESCAPE_SEQUENCES[match.group(0)]
 
 
 HELP_ESCAPING_RE = re.compile(r'\\[\\n]')
 ESCAPING_RE = re.compile(r'\\[\\n"]')
 
 
-def _replace_help_escaping(s):
+def _replace_help_escaping(s: str) -> str:
     return HELP_ESCAPING_RE.sub(replace_escape_sequence, s)
 
 
-def _replace_escaping(s):
+def _replace_escaping(s: str) -> str:
     return ESCAPING_RE.sub(replace_escape_sequence, s)
 
 
-def _is_character_escaped(s, charpos):
+def _is_character_escaped(s: str, charpos: int) -> bool:
     num_bslashes = 0
     while (charpos > num_bslashes
            and s[charpos - 1 - num_bslashes] == '\\'):
         num_bslashes += 1
     return num_bslashes % 2 == 1
 
 
-def _parse_labels(labels_string):
-    labels = {}
+def _parse_labels(labels_string: str) -> Dict[str, str]:
+    labels: Dict[str, str] = {}
     # Return if we don't have valid labels
     if "=" not in labels_string:
         return labels
@@ -95,7 +96,7 @@ def _parse_labels(labels_string):
 
 
 # If we have multiple values only consider the first
-def _parse_value_and_timestamp(s):
+def _parse_value_and_timestamp(s: str) -> Tuple[float, Optional[float]]:
     s = s.lstrip()
     separator = " "
     if separator not in s:
@@ -108,7 +109,7 @@ def _parse_value_and_timestamp(s):
     return value, timestamp
 
 
-def _parse_sample(text):
+def _parse_sample(text: str) -> Sample:
     # Detect the labels in the text
     try:
         label_start, label_end = text.index("{"), text.rindex("}")
@@ -133,7 +134,7 @@ def _parse_sample(text):
         return Sample(name, {}, value, timestamp)
 
 
-def text_fd_to_metric_families(fd):
+def text_fd_to_metric_families(fd: TextIO) -> Iterable[Metric]:
     """Parse Prometheus text format from a file descriptor.
 
     This is a laxer parser than the main Go parser,
@@ -145,10 +146,10 @@ def text_fd_to_metric_families(fd):
     name = ''
     documentation = ''
     typ = 'untyped'
-    samples = []
+    samples: List[Sample] = []
     allowed_names = []
 
-    def build_metric(name, documentation, typ, samples):
+    def build_metric(name: str, documentation: str, typ: str, samples: List[Sample]) -> Metric:
         # Munge counters into OpenMetrics representation
         # used internally.
         if typ == 'counter':

setup.py

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