Migrate documentation from ironic-lib

This was the only meaningful documentation from ironic-lib.

Change-Id: I8c40433edd0c3664488887034a49f687605093c1

doc/source/contributor/metrics.rst

@@ -0,0 +1,58 @@
+Metrics
+=======
+
+Ironic provides a pluggable metrics library as of the 2.0.0 release.
+The metrics backend to be used is configured via ``CONF.metrics.backend``.
+Not all backends support all metrics types or metric sources.
+
+The typical usage of metrics is to initialize and cache a metrics logger,
+using the ``get_metrics_logger()`` method in ``metrics_utils``, then
+use that object to decorate functions or create context managers to gather
+metrics. The general convention is to provide the name of the module as the
+first argument to set it as the prefix, then set the actual metric name to the
+method name. For example:
+
+.. code-block:: python
+
+  from ironic import metrics_utils
+
+  METRICS = metrics_utils.get_metrics_logger(__name__)
+
+  @METRICS.timer('my_simple_method')
+  def my_simple_method(arg, matey):
+      pass
+
+  def my_complex_method(arg, matey):
+      with METRICS.timer('complex_method_pt_1'):
+          do_some_work()
+
+      with METRICS.timer('complex_method_pt_2'):
+          do_more_work()
+
+There are three different kinds of metrics:
+  - **Timers** measure how long the code in the decorated method or context
+    manager takes to execute, and emits the value as a timer metric. These
+    are useful for measuring performance of a given block of code.
+  - **Counters** increment a counter each time a decorated method or context
+    manager is executed. These are useful for counting the number of times a
+    method is called, or the number of times an event occurs.
+  - **Gauges** return the value of a decorated method as a metric. This is
+    useful when you want to monitor the value returned by a method over time.
+
+Additionally, metrics can be sent directly, rather than using a context
+manager or decorator, when appropriate. When used in this way, we will
+simply emit the value provided as the requested metric type. For example:
+
+.. code-block:: python
+
+  from ironic import metrics_utils
+
+  METRICS = metrics_utils.get_metrics_logger(__name__)
+
+  def my_node_failure_method(node):
+      if node.failed:
+          METRICS.send_counter(node.uuid, 1)
+
+The provided statsd backend natively supports all three metric types. For more
+information about how statsd changes behavior based on the metric type, see
+`statsd metric types <https://github.com/etsy/statsd/blob/master/docs/metric_types.md>`_