Merge pull request prometheus#23 from brian-brazil/serverthread

brian-brazil · brian-brazil · commit f608ea442691 · 2015-04-06T14:01:57.000+01:00
Make it simpler to start a http server. Update docs.
diff --git a/README.md b/README.md
@@ -1,14 +1,57 @@
 # Prometheus Python Client
 
-This client is under active development.
+The official Python 2 and 3 client for [Prometheus](http://prometheus.io).
+
+## Three Step Demo
+
+**One**: Install the client:
+```
+pip install prometheus_client
+```
+
+**Two**: Paste the following into a Python interpreter:
+```python
+from prometheus_client import start_http_server,Summary
+import random
+import time
+
+# Create a metric to track time spent and requests made.
+REQUEST_TIME = Summary('request_processing_seconds', 'Time spent processing request')
+
+# Decorate function with metric.
+@REQUEST_TIME.time()
+def process_request(t):
+    """A dummy function that takes some time."""
+    time.sleep(t)
+
+if __name__ == '__main__':
+    # Start up the server to expose the metrics.
+    start_http_server(8000)
+    # Generate some requests.
+    while True:
+        process_request(random.random())
+```
+
+**Three**: Visit [http://localhost:8000/](http://localhost:8000/) to view the metrics.
+
+From one easy to use decorator you get:
+  * `request_processing_seconds_count`: Number of times this function was called.
+  * `request_processing_seconds_sum`: Total amount of time spent in this function.
+
+Prometheus's `rate` function allows calculation of both requests per second,
+and latency over time from this data.
+
+In addition if you're on Linux the `process` metrics expose CPU, memory and 
+other information about the process for free!
 
 ## Installation
 
 ```
 pip install prometheus_client
 ```
 
-This package can be found on [PyPI](https://pypi.python.org/pypi/prometheus_client).
+This package can be found on
+[PyPI](https://pypi.python.org/pypi/prometheus_client).
 
 ## Instrumenting
 
@@ -48,7 +91,6 @@ with c.count_exceptions(ValueError):
 
 Gauges can go up and down.
 
-
 ```python
 from prometheus_client import Gauge
 g = Gauge('my_inprogress_requests', 'Description of gauge')
@@ -136,7 +178,7 @@ c.labels('post', '/submit').inc()
 ### 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
+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
@@ -149,32 +191,24 @@ ProcessCollector(namespace='mydaemon', pid=lambda: open('/var/run/daemon.pid').r
 
 There are several options for exporting metrics.
 
-## HTTP handler
+## HTTP
 
-Metrics are usually exposed over HTTP, to be read by the Prometheus server. For example:
+Metrics are usually exposed over HTTP, to be read by the Prometheus server.
 
-Python 2:
+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 MetricsHandler
-from BaseHTTPServer import HTTPServer
-server_address = ('', 8000)
-httpd = HTTPServer(server_address, MetricsHandler)
-httpd.serve_forever()
-```
-
-Python 3:
-
-```python
-from prometheus_client import MetricsHandler
-from http.server import HTTPServer
-server_address = ('', 8000)
-httpd = HTTPServer(server_address, MetricsHandler)
-httpd.serve_forever()
+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 `MetricsServlet` class
+which provides a `BaseHTTPRequestHandler`. It also serves as a simple example of how
+to write a custom endpoint.
+
 ## Node exporter textfile collector
 
 The [textfile collector](https://github.com/prometheus/node_exporter#textfile-collector)
diff --git a/prometheus_client/__init__.py b/prometheus_client/__init__.py
@@ -10,10 +10,12 @@
 import threading
 try:
     from BaseHTTPServer import BaseHTTPRequestHandler
+    from BaseHTTPServer import HTTPServer
 except ImportError:
     # Python 3
     unicode = str
     from http.server import BaseHTTPRequestHandler
+    from http.server import HTTPServer
 from functools import wraps
 from threading import Lock
 
@@ -437,6 +439,20 @@ def do_GET(self):
         self.end_headers()
         self.wfile.write(generate_latest(REGISTRY))
 
+    def log_message(self, format, *args):
+        return
+
+
+def start_http_server(port, addr=''):
+    """Starts a HTTP server for prometheus metrics as a daemon thread."""
+    class PrometheusMetricsServer(threading.Thread):
+        def run(self):
+            httpd = HTTPServer((addr, port), MetricsHandler)
+            httpd.serve_forever()
+    t = PrometheusMetricsServer()
+    t.daemon = True
+    t.start()
+
 
 def write_to_textfile(path, registry):
     '''Write metrics to the given path.
