Merge pull request #21 from claws/docs

update docs and minor cleanups

README.rst

@@ -27,7 +27,10 @@ Install
 Example
 -------
 
-.. code-block:: console
+The example below shows a single Counter metric collector being created
+and exposed via a HTTP endpoint.
+
+.. code-block:: python
 
     #!/usr/bin/env python
     '''
@@ -41,60 +44,59 @@ Example
 
     if __name__ == '__main__':
 
-        def on_timer_expiry(loop, events_collector):
-            ''' Update the metric periodically '''
-            events_collector.inc({'kind': 'timer_expiry'})
-            loop.call_later(1.0, on_timer_expiry, loop, events_collector)
-
         loop = asyncio.get_event_loop()
 
-        svr = Service(loop=loop)
+        svr = Service()
 
-        events_collector = Counter(
+        events_counter = Counter(
             "events",
             "Number of events.",
             const_labels={'host': socket.gethostname()})
 
-        svr.registry.register(events_collector)
+        svr.register(events_counter)
 
-        loop.run_until_complete(svr.start())
-        print('Serving prometheus metrics on: {}'.format(svr.metrics_url))
+        loop.run_until_complete(svr.start(addr="127.0.0.1"))
+        print(f'Serving prometheus metrics on: {svr.metrics_url}')
 
-        loop.call_later(1.0, on_timer_expiry, loop, events_collector)
+        async def updater(m: Counter):
+            # Periodically update the metric to simulate some progress
+            # happening in a real application.
+            while True:
+                m.inc({'kind': 'timer_expiry'})
+                await asyncio.sleep(1.0)
 
         try:
-            loop.run_forever()
+            loop.run_until_complete(updater(events_counter))
         except KeyboardInterrupt:
             pass
         finally:
             loop.run_until_complete(svr.stop())
         loop.close()
 
-The example above shows a single Counter metric collector being created
-and exposed via a HTTP endpoint.
-
-The counter metric is created to track the number of iterations. This
-example uses a timer callback to periodically increment the metric
-tracking iterations. In a realistic application a metric might track the
-number of requests, etc.
+In this simple example the counter metric is tracking the number of
+while loop iterations executed by the updater coroutine. In a realistic
+application a metric might track the number of requests, etc.
 
 Following typical ``asyncio`` usage, an event loop is instantiated first
 then a metrics service is instantiated. The metrics service is responsible
-for managing the various metrics collectors and responding to Prometheus
-server when it requests metrics.
+for managing metric collectors and responding to metrics requests.
+
+The service accepts various arguments such as the interface and port to bind
+to. A collector registry is used within the service to hold metrics
+collectors that will be exposed by the service. The service will create a new
+collector registry if one is not passed in.
 
-The server accepts various arguments such as the interface and port to bind
-to. The service will create a new collector registry if one is not passed
-in. A collector registry holds the various metrics collectors that will be
-exposed by the service.
+A counter metric is created and registered with the service. The service is
+started and then a coroutine is started to periodically update the metric
+to simulate progress.
 
 The example script can be run using:
 
 .. code-block:: console
 
-    (env) $ cd examples
-    (env) $ python simple-example.py
-    Serving prometheus metrics on: http://0.0.0.0:50624/metrics
+    (venv) $ cd examples
+    (venv) $ python simple-example.py
+    Serving prometheus metrics on: http://127.0.0.1:50624/metrics
 
 In another terminal fetch the metrics using the ``curl`` command line tool
 to verify they can be retrieved by Prometheus server.
@@ -103,29 +105,35 @@ By default metrics will be returned in plan text format.
 
 .. code-block:: console
 
-    $ curl http://0.0.0.0:50624/metrics
+    $ curl http://127.0.0.1:50624/metrics
     # HELP events Number of events.
     # TYPE events counter
     events{host="alpha",kind="timer_expiry"} 33
-    $ curl http://0.0.0.0:50624/metrics -H 'Accept: text/plain; version=0.0.4'
-    # HELP events Number of events.
-    # TYPE events counter
-    events{host="alpha",kind="timer_expiry"} 36
 
 Similarly, you can request metrics in binary format, though this will be hard
 to read on the command line.
 
 .. code-block:: console
 
-    $ curl http://0.0.0.0:50624/metrics -H "ACCEPT: application/vnd.google.protobuf; proto=io.prometheus.client.MetricFamily; encoding=delimited"
+    $ curl http://127.0.0.1:50624/metrics -H "ACCEPT: application/vnd.google.protobuf; proto=io.prometheus.client.MetricFamily; encoding=delimited"
 
-There are more examples in the ``examples`` directory. The ``app-example.py``
-file will likely be of interest as it provides a more representative
-application example.
+The metrics service also responds to requests sent to its ``/`` route. The
+response is simple HTML. This route can be useful as a Kubernetes ``/healthz``
+style health indicator as it does not incur any overhead within the service
+to serialize a full metrics response.
+
+.. code-block:: console
+
+    $ curl http://127.0.0.1:50624/
+    <html><body><a href='/metrics'>metrics</a></body></html>
 
 A number of convenience decorator functions are also available to assist with
 updating metrics.
 
+There are more examples in the ``examples`` directory. The ``app-example.py``
+file will likely be of interest as it provides a more representative
+application example.
+
 
 License
 -------

docs/index.rst

@@ -32,33 +32,35 @@ The project source code can be found `here <https://github.com/claws/aiopromethe
 Example
 -------
 
+The example below shows a single Counter metric collector being created
+and exposed via a HTTP endpoint.
+
 .. literalinclude:: ../examples/simple-example.py
     :language: python3
 
-The example above shows a single Counter metric collector being created
-and exposed via a HTTP endpoint.
-
-The counter metric is created to track the number of iterations. This
-example uses a timer callback to periodically increment the metric
-tracking iterations. In a realistic application a metric might track the
-number of requests, etc.
+In this simple example the counter metric is tracking the number of
+while loop iterations executed by the updater coroutine. In a realistic
+application a metric might track the number of requests, etc.
 
 Following typical ``asyncio`` usage, an event loop is instantiated first
 then a metrics service is instantiated. The metrics service is responsible
-for managing the various metrics collectors and responding to Prometheus
-server when it requests metrics.
+for managing metric collectors and responding to metrics requests.
 
-The server accepts various arguments such as the interface and port to bind
-to. The service will create a new collector registry if one is not passed
-in. A collector registry holds the various metrics collectors that will be
-exposed by the service.
+The service accepts various arguments such as the interface and port to bind
+to. A collector registry is used within the service to hold metrics
+collectors that will be exposed by the service. The service will create a new
+collector registry if one is not passed in.
+
+A counter metric is created and registered with the service. The service is
+started and then a coroutine is started to periodically update the metric
+to simulate progress.
 
 The example script can be run using:
 
 .. code-block:: console
 
-    (env) $ cd examples
-    (env) $ python simple-example.py
+    (venv) $ cd examples
+    (venv) $ python simple-example.py
     Serving prometheus metrics on: http://127.0.0.1:50624/metrics
 
 In another terminal fetch the metrics using the ``curl`` command line tool
@@ -72,6 +74,7 @@ By default metrics will be returned in plan text format.
     # HELP events Number of events.
     # TYPE events counter
     events{host="alpha",kind="timer_expiry"} 33
+
     $ curl http://127.0.0.1:50624/metrics -H 'Accept: text/plain; version=0.0.4'
     # HELP events Number of events.
     # TYPE events counter
@@ -84,13 +87,23 @@ to read on the command line.
 
     $ curl http://127.0.0.1:50624/metrics -H "ACCEPT: application/vnd.google.protobuf; proto=io.prometheus.client.MetricFamily; encoding=delimited"
 
-There are more examples in the ``examples`` directory. The ``app-example.py``
-file will likely be of interest as it provides a more representative
-application example.
+The metrics service also responds to requests sent to its ``/`` route. The
+response is simple HTML. This route can be useful as a Kubernetes ``/healthz``
+style health indicator as it does not incur any overhead within the service
+to serialize a full metrics response.
+
+.. code-block:: console
+
+    $ curl http://127.0.0.1:50624/
+    <html><body><a href='/metrics'>metrics</a></body></html>
 
 A number of convenience decorator functions are also available to assist with
 updating metrics.
 
+There are more examples in the ``examples`` directory. The ``app-example.py``
+file will likely be of interest as it provides a more representative
+application example.
+
 
 License
 -------

docs/user/index.rst

@@ -8,7 +8,7 @@ This section of the documentation provides information about how to use
 Install
 -------
 
-The current realease of `aioprometheus` is available from PyPI. Use ``pip``
+The current release of `aioprometheus` is available from PyPI. Use ``pip``
 to install it.
 
 .. code-block:: console
@@ -161,40 +161,46 @@ is the same as this one with const labels:
 Exporting Metrics
 -----------------
 
+Metrics are exposed to the Prometheus server via a HTTP endpoint. The metrics
+can retrieved in two different formats; text and binary.
 
 
 Simple Example
 ++++++++++++++
 
-Metrics are exposed to the Prometheus server via a HTTP endpoint. The metrics
-can retrieved in two different formats; text and binary.
+The example below shows a single Counter metric collector being created
+and exposed via a HTTP endpoint.
 
-The following example shows how a metrics service can be instantiated along
-with a Counter. Following typical ``asyncio`` usage, an event loop is
-instantiated first then a Prometheus metrics service is instantiated.
-The server accepts various arguments such as the interface and port to bind
-to.
+.. literalinclude:: ../examples/simple-example.py
+    :language: python3
 
-The service can also be passed a specific registry to use or if none is
-explicitly defined it will create a registry. A registry holds the
-various metrics collectors that will be exposed by the service.
+In this simple example the counter metric is tracking the number of
+while loop iterations executed by the updater coroutine. In a realistic
+application a metric might track the number of requests, etc.
 
-Next, a counter metric is created to track the number of iterations. This
-example uses a timer callback to periodically increment the metric
-tracking iterations. In a realistic application a metric might track the
-number of requests, etc.
+Following typical ``asyncio`` usage, an event loop is instantiated first
+then a metrics service is instantiated. The metrics service is responsible
+for managing metric collectors and responding to metrics requests.
 
-.. literalinclude:: ../../examples/simple-example.py
-    :language: python3
+The service accepts various arguments such as the interface and port to bind
+to. A collector registry is used within the service to hold metrics
+collectors that will be exposed by the service. The service will create a new
+collector registry if one is not passed in.
 
-The example can be run using
+A counter metric is created and registered with the service. The service is
+started and then a coroutine is started to periodically update the metric
+to simulate progress.
+
+The example script can be run using:
 
 .. code-block:: console
 
-    (env) $ python simple-example.py
+    (venv) $ cd examples
+    (venv) $ python simple-example.py
     Serving prometheus metrics on: http://127.0.0.1:50624/metrics
 
-In another terminal fetch the metrics using the ``curl`` command line tool.
+In another terminal fetch the metrics using the ``curl`` command line tool
+to verify they can be retrieved by Prometheus server.
 
 By default metrics will be returned in plan text format.
 
@@ -204,6 +210,7 @@ By default metrics will be returned in plan text format.
     # HELP events Number of events.
     # TYPE events counter
     events{host="alpha",kind="timer_expiry"} 33
+
     $ curl http://127.0.0.1:50624/metrics -H 'Accept: text/plain; version=0.0.4'
     # HELP events Number of events.
     # TYPE events counter
@@ -216,6 +223,16 @@ to read on the command line.
 
     $ curl http://127.0.0.1:50624/metrics -H "ACCEPT: application/vnd.google.protobuf; proto=io.prometheus.client.MetricFamily; encoding=delimited"
 
+The metrics service also responds to requests sent to its ``/`` route. The
+response is simple HTML. This route can be useful as a Kubernetes ``/healthz``
+style health indicator as it does not incur any overhead within the service
+to serialize a full metrics response.
+
+.. code-block:: console
+
+    $ curl http://127.0.0.1:50624/
+    <html><body><a href='/metrics'>metrics</a></body></html>
+
 
 Application Example
 +++++++++++++++++++
@@ -238,8 +255,8 @@ You can use the ``curl`` command line tool to fetch metrics manually or use
 the helper script described in the next section.
 
 
-Checking Example using helper script
-------------------------------------
+Checking examples using helper script
+-------------------------------------
 
 There is a script in the examples directory that emulates Prometheus server
 scraping a metrics service endpoint. You can specify a particular format to

examples/decorator_count_exceptions.py

@@ -54,7 +54,7 @@ async def handle_requests():
     loop = asyncio.get_event_loop()
 
     svr = Service(loop=loop)
-    svr.registry.register(REQUESTS)
+    svr.register(REQUESTS)
 
     try:
         loop.run_until_complete(handle_requests())

examples/decorator_inprogress.py

@@ -47,7 +47,7 @@ async def handle_requests():
     loop = asyncio.get_event_loop()
 
     svr = Service(loop=loop)
-    svr.registry.register(REQUESTS)
+    svr.register(REQUESTS)
 
     try:
         loop.run_until_complete(handle_requests())

examples/decorator_timer.py

@@ -52,7 +52,7 @@ async def handle_requests():
     loop = asyncio.get_event_loop()
 
     svr = Service(loop=loop)
-    svr.registry.register(REQUEST_TIME)
+    svr.register(REQUEST_TIME)
 
     try:
         loop.run_until_complete(handle_requests())