From b3ae6e479160a4eb547b5632b1de6901defa8614 Mon Sep 17 00:00:00 2001
From: Markus Hosch <Markus.Hosch@bmw.de>
Date: Thu, 9 Aug 2018 11:37:12 +0200
Subject: [PATCH] Add list of metrics provided to statsd

This change provides a list of currently available metrics that are
reported by the laucher and the builder.

Change-Id: I51bc38c746cab5374095cc80e77db4534c041119
---
 doc/requirements.txt        |   1 +
 doc/source/conf.py          |   1 +
 doc/source/installation.rst |   2 +
 doc/source/operation.rst    | 103 ++++++++++++++++++++++++++++++++++++
 4 files changed, 107 insertions(+)

diff --git a/doc/requirements.txt b/doc/requirements.txt
index 66b45ef75..b083c6c6d 100644
--- a/doc/requirements.txt
+++ b/doc/requirements.txt
@@ -2,3 +2,4 @@ sphinx>=1.5.1,<1.6
 sphinxcontrib-programoutput
 sphinxcontrib-httpdomain
 reno>=2.5.0 # Apache-2.0
+zuul-sphinx
diff --git a/doc/source/conf.py b/doc/source/conf.py
index e429d1d72..21f5fc191 100644
--- a/doc/source/conf.py
+++ b/doc/source/conf.py
@@ -29,6 +29,7 @@ extensions = [
     'sphinx.ext.autodoc',
     'sphinxcontrib.programoutput',
     'sphinxcontrib.httpdomain',
+    'zuul_sphinx',
     'reno.sphinxext']
 #extensions = ['sphinx.ext.intersphinx']
 #intersphinx_mapping = {'python': ('http://docs.python.org/2.7', None)}
diff --git a/doc/source/installation.rst b/doc/source/installation.rst
index f80847f27..194cf5e92 100644
--- a/doc/source/installation.rst
+++ b/doc/source/installation.rst
@@ -21,6 +21,8 @@ usually recommended.
 Nodepool only needs to be told how to contact the ZooKeeper cluster;
 it will automatically populate the ZNode structure as needed.
 
+.. _statsd_configuration:
+
 Statsd and Graphite
 ~~~~~~~~~~~~~~~~~~~
 
diff --git a/doc/source/operation.rst b/doc/source/operation.rst
index fc8ab8ca6..313ef8fde 100644
--- a/doc/source/operation.rst
+++ b/doc/source/operation.rst
@@ -272,3 +272,106 @@ launchers, all will provide the same information.
    :reqheader Accept: ``application/json`` or ``text/*``
    :resheader Content-Type: ``application/json`` or ``text/plain``
                             depending on the :http:header:`Accept` header
+
+Monitoring
+----------
+
+Nodepool provides monitoring information to statsd. See
+:ref:`statsd_configuration` to learn how to enable statsd support. Currently,
+these metrics are supported:
+
+Nodepool builder
+~~~~~~~~~~~~~~~~
+
+.. zuul:stat:: nodepool.dib_image_build.<diskimage_name>.<ext>.size
+   :type: gauge
+
+   This stat reports the size of the built image in bytes.
+
+.. zuul:stat:: nodepool.image_update.<image name>.<provider name>
+   :type: counter, timer
+
+   Number of image uploads to a specific provider in the cloud plus the time in
+   seconds spent to upload the image.
+
+Nodepool launcher
+~~~~~~~~~~~~~~~~~
+
+.. zuul:stat:: nodepool.provider.<provider>.max_servers
+   :type: gauge
+
+   Current setting of the max-server configuration parameter for the respective
+   provider.
+
+.. _nodepool_nodes:
+
+.. zuul:stat:: nodepool.nodes.<state>
+  :type: counter
+
+   Number of nodes in a specific state.
+
+   state can be:
+
+   * building
+   * deleting
+   * failed
+   * in-use
+   * ready
+   * used
+
+.. zuul:stat:: nodepool.provider.<provider>.nodes.<state>
+   :type: gauge
+
+   Number of nodes per provider that are in one specific state. See
+   :ref:`nodepool.nodes <nodepool_nodes>` for a list of possible states.
+
+.. zuul:stat:: nodepool.label.<label>.nodes.<state>
+   :type: counter
+
+   Number of nodes with a specific label in a specific state. See
+   :ref:`nodepool.nodes <nodepool_nodes>` for a list of possible states.
+
+.. zuul:stat:: nodepool.task.<provider>.<task>
+   :type: counter, timer
+
+   Number of tasks executed per provider plus the duration of the task
+   execution.
+
+.. _nodepool_launch:
+
+.. zuul:stat:: nodepool.launch.<result>
+   :type: counter, timer
+
+   Number of launches, categorized by the launch result plus the duration
+   of the launch.
+
+   *result* can be:
+
+   * ready: launch was successful
+   * error.zksession: Zookeeper session was lost
+   * error.quota: Quota of the provider was reached
+   * error.unknown: Some other error during launch
+
+.. zuul:stat:: nodepool.launch.provider.<provider>.<az>.<result>
+   :type: counter, timer
+
+   Number of launches per provider per availability zone, categorized
+   by the launch result plus duration of the launch.
+
+   See :ref:`nodepool.launch <nodepool_launch>` for a list of possible results.
+
+.. zuul:stat:: nodepool.launch.image.<image>.<result>
+   :type: counter, timer
+
+   Number of launches per image, categorized by the launch result plus duration
+   of the launch.
+
+   See :ref:`nodepool.launch <nodepool_launch>` for a list of possible results.
+
+.. zuul:stat:: nodepool.launch.requestor.<requestor>.<result>
+   :type: counter, timer
+
+   Number of launches per requestor, categorized by the launch result plus the
+   duration of the launch.
+
+   See :ref:`nodepool.launch <nodepool_launch>` for a list of possible results.