Merge pull request #14 from faucetsdn/v0.19.0

Upgrade python3-prometheus-client to v0.19.0.

docs/.gitignore

@@ -0,0 +1 @@
+.hugo_build.lock

docs/README.md

@@ -0,0 +1,37 @@
+Docs
+----
+
+This directory contains [hugo](https://gohugo.io) documentation to be published in Github pages.
+
+Run Locally
+-----------
+
+```
+hugo server -D
+```
+
+This will serve the docs on [http://localhost:1313](http://localhost:1313).
+
+Deploy to Github Pages
+----------------------
+
+Changes to the `main` branch will be deployed automatically with Github actions.
+
+Update Geekdocs
+---------------
+
+The docs use the [Geekdocs](https://geekdocs.de/) theme. The theme is checked in to Github in the `./docs/themes/hugo-geekdoc/` folder. To update [Geekdocs](https://geekdocs.de/), remove the current folder and create a new one with the latest [release](https://github.com/thegeeklab/hugo-geekdoc/releases). There are no local modifications in `./docs/themes/hugo-geekdoc/`.
+
+Notes
+-----
+
+Here's how the initial `docs/` folder was set up:
+
+```
+hugo new site docs
+cd docs/
+mkdir -p themes/hugo-geekdoc/
+curl -L https://github.com/thegeeklab/hugo-geekdoc/releases/download/v0.41.1/hugo-geekdoc.tar.gz | tar -xz -C themes/hugo-geekdoc/ --strip-components=1
+```
+
+Create the initial `hugo.toml` file as described in [https://geekdocs.de/usage/getting-started/](https://geekdocs.de/usage/getting-started/).

docs/archetypes/default.md

@@ -0,0 +1,5 @@
++++
+title = '{{ replace .File.ContentBaseName "-" " " | title }}'
+date = {{ .Date }}
+draft = true
++++

docs/content/_index.md

@@ -0,0 +1,5 @@
+---
+title: "client_python"
+---
+
+This is the documentation for the [Prometheus Python client library](https://github.com/prometheus/client_python).

docs/content/bridges/_index.md

@@ -0,0 +1,8 @@
+---
+title: Bridges
+weight: 5
+---
+
+It is also possible to expose metrics to systems other than Prometheus.
+This allows you to take advantage of Prometheus instrumentation even
+if you are not quite ready to fully transition to Prometheus yet.

docs/content/bridges/graphite.md

@@ -0,0 +1,27 @@
+---
+title: Graphite
+weight: 1
+---
+
+Metrics are pushed over TCP in the Graphite plaintext format.
+
+```python
+from prometheus_client.bridge.graphite import GraphiteBridge
+
+gb = GraphiteBridge(('graphite.your.org', 2003))
+# Push once.
+gb.push()
+# Push every 10 seconds in a daemon thread.
+gb.start(10.0)
+```
+
+Graphite [tags](https://grafana.com/blog/2018/01/11/graphite-1.1-teaching-an-old-dog-new-tricks/) are also supported.
+
+```python
+from prometheus_client.bridge.graphite import GraphiteBridge
+
+gb = GraphiteBridge(('graphite.your.org', 2003), tags=True)
+c = Counter('my_requests_total', 'HTTP Failures', ['method', 'endpoint'])
+c.labels('get', '/').inc()
+gb.push()
+```

docs/content/collector/_index.md

@@ -0,0 +1,36 @@
+---
+title: Collector
+weight: 3
+---
+
+# Process Collector
+
+The Python client automatically exports metrics about process CPU usage, RAM,
+file descriptors and start time. These all have the prefix `process`, and
+are only currently available on Linux.
+
+The namespace and pid constructor arguments allows for exporting metrics about
+other processes, for example:
+```
+ProcessCollector(namespace='mydaemon', pid=lambda: open('/var/run/daemon.pid').read())
+```
+
+# Platform Collector
+
+The client also automatically exports some metadata about Python. If using Jython,
+metadata about the JVM in use is also included. This information is available as 
+labels on the `python_info` metric. The value of the metric is 1, since it is the 
+labels that carry information.
+
+# Disabling Default Collector metrics
+
+By default the collected `process`, `gc`, and `platform` collector metrics are exported.
+If this information is not helpful, it can be disabled using the following:
+
+```python
+import prometheus_client
+
+prometheus_client.REGISTRY.unregister(prometheus_client.GC_COLLECTOR)
+prometheus_client.REGISTRY.unregister(prometheus_client.PLATFORM_COLLECTOR)
+prometheus_client.REGISTRY.unregister(prometheus_client.PROCESS_COLLECTOR)
+```

docs/content/collector/custom.md

@@ -0,0 +1,38 @@
+---
+title: Custom Collectors
+weight: 1
+---
+
+Sometimes it is not possible to directly instrument code, as it is not
+in your control. This requires you to proxy metrics from other systems.
+
+To do so you need to create a custom collector, for example:
+
+```python
+from prometheus_client.core import GaugeMetricFamily, CounterMetricFamily, REGISTRY
+from prometheus_client.registry import Collector
+
+class CustomCollector(Collector):
+    def collect(self):
+        yield GaugeMetricFamily('my_gauge', 'Help text', value=7)
+        c = CounterMetricFamily('my_counter_total', 'Help text', labels=['foo'])
+        c.add_metric(['bar'], 1.7)
+        c.add_metric(['baz'], 3.8)
+        yield c
+
+REGISTRY.register(CustomCollector())
+```
+
+`SummaryMetricFamily`, `HistogramMetricFamily` and `InfoMetricFamily` work similarly.
+
+A collector may implement a `describe` method which returns metrics in the same
+format as `collect` (though you don't have to include the samples). This is
+used to predetermine the names of time series a `CollectorRegistry` exposes and
+thus to detect collisions and duplicate registrations.
+
+Usually custom collectors do not have to implement `describe`. If `describe` is
+not implemented and the CollectorRegistry was created with `auto_describe=True`
+(which is the case for the default registry) then `collect` will be called at
+registration time instead of `describe`. If this could cause problems, either
+implement a proper `describe`, or if that's not practical have `describe`
+return an empty list.

docs/content/exporting/_index.md

@@ -0,0 +1,6 @@
+---
+title: Exporting
+weight: 4
+---
+
+There are several options for exporting metrics.

docs/content/exporting/http/_index.md

@@ -0,0 +1,46 @@
+---
+title: HTTP/HTTPS
+weight: 1
+---
+
+# HTTP
+
+Metrics are usually exposed over HTTP, to be read by the Prometheus server.
+
+The easiest way to do this is via `start_http_server`, which will start a HTTP
+server in a daemon thread on the given port:
+
+```python
+from prometheus_client import start_http_server
+
+start_http_server(8000)
+```
+
+Visit [http://localhost:8000/](http://localhost:8000/) to view the metrics.
+
+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.
+
+# HTTPS
+
+By default, the prometheus client will accept only HTTP requests from Prometheus.
+To enable HTTPS, `certfile` and `keyfile` need to be provided. The certificate is
+presented to Prometheus as a server certificate during the TLS handshake, and
+the private key in the key file must belong to the public key in the certificate.
+
+When HTTPS is enabled, you can enable mutual TLS (mTLS) by setting `client_auth_required=True`
+(i.e. Prometheus is required to present a client certificate during TLS handshake) and the
+client certificate including its hostname is validated against the CA certificate chain.
+
+`client_cafile` can be used to specify a certificate file containing a CA certificate
+chain that is used to validate the client certificate. `client_capath` can be used to
+specify a certificate directory containing a CA certificate chain that is used to
+validate the client certificate. If neither of them is provided, a default CA certificate
+chain is used (see Python [ssl.SSLContext.load_default_certs()](https://docs.python.org/3/library/ssl.html#ssl.SSLContext.load_default_certs))
+
+```python
+from prometheus_client import start_http_server
+
+start_http_server(8000, certfile="server.crt", keyfile="server.key")
+```

docs/content/exporting/http/asgi.md

@@ -0,0 +1,23 @@
+---
+title: ASGI
+weight: 3
+---
+
+To use Prometheus with [ASGI](http://asgi.readthedocs.org/en/latest/), there is
+`make_asgi_app` which creates an ASGI application.
+
+```python
+from prometheus_client import make_asgi_app
+
+app = make_asgi_app()
+```
+Such an application can be useful when integrating Prometheus metrics with ASGI
+apps.
+
+By default, the WSGI application will respect `Accept-Encoding:gzip` headers used by Prometheus
+and compress the response if such a header is present. This behaviour can be disabled by passing 
+`disable_compression=True` when creating the app, like this:
+
+```python
+app = make_asgi_app(disable_compression=True)
+```

docs/content/exporting/http/fastapi-gunicorn.md

@@ -0,0 +1,50 @@
+---
+title: FastAPI + Gunicorn
+weight: 5
+---
+
+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 instructions 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

docs/content/exporting/http/flask.md

@@ -0,0 +1,32 @@
+---
+title: Flask
+weight: 4
+---
+
+To use Prometheus with [Flask](http://flask.pocoo.org/) we need to serve metrics through a Prometheus WSGI application. This can be achieved using [Flask's application dispatching](http://flask.pocoo.org/docs/latest/patterns/appdispatch/). Below is a working example.
+
+Save the snippet below in a `myapp.py` file
+
+```python
+from flask import Flask
+from werkzeug.middleware.dispatcher import DispatcherMiddleware
+from prometheus_client import make_wsgi_app
+
+# Create my app
+app = Flask(__name__)
+
+# Add prometheus wsgi middleware to route /metrics requests
+app.wsgi_app = DispatcherMiddleware(app.wsgi_app, {
+    '/metrics': make_wsgi_app()
+})
+```
+
+Run the example web application like this
+
+```bash
+# Install uwsgi if you do not have it
+pip install uwsgi
+uwsgi --http 127.0.0.1:8000 --wsgi-file myapp.py --callable app
+```
+
+Visit http://localhost:8000/metrics to see the metrics

docs/content/exporting/http/twisted.md

@@ -0,0 +1,20 @@
+---
+title: Twisted
+weight: 1
+---
+
+To use prometheus with [twisted](https://twistedmatrix.com/), there is `MetricsResource` which exposes metrics as a twisted resource.
+
+```python
+from prometheus_client.twisted import MetricsResource
+from twisted.web.server import Site
+from twisted.web.resource import Resource
+from twisted.internet import reactor
+
+root = Resource()
+root.putChild(b'metrics', MetricsResource())
+
+factory = Site(root)
+reactor.listenTCP(8000, factory)
+reactor.run()
+```

docs/content/exporting/http/wsgi.md

@@ -0,0 +1,36 @@
+---
+title: WSGI
+weight: 2
+---
+
+To use Prometheus with [WSGI](http://wsgi.readthedocs.org/en/latest/), there is
+`make_wsgi_app` which creates a WSGI application.
+
+```python
+from prometheus_client import make_wsgi_app
+from wsgiref.simple_server import make_server
+
+app = make_wsgi_app()
+httpd = make_server('', 8000, app)
+httpd.serve_forever()
+```
+
+Such an application can be useful when integrating Prometheus metrics with WSGI
+apps.
+
+The method `start_wsgi_server` can be used to serve the metrics through the
+WSGI reference implementation in a new thread.
+
+```python
+from prometheus_client import start_wsgi_server
+
+start_wsgi_server(8000)
+```
+
+By default, the WSGI application will respect `Accept-Encoding:gzip` headers used by Prometheus
+and compress the response if such a header is present. This behaviour can be disabled by passing
+`disable_compression=True` when creating the app, like this:
+
+```python
+app = make_wsgi_app(disable_compression=True)
+```