doc/mgr: add Prometheus plugin docs

Signed-off-by: Dan Mick <dan.mick@redhat.com>

diff --git a/doc/dev/perf_counters.rst b/doc/dev/perf_counters.rst
index 398d51a00ee99b490ae1d51e6952ca24c941e66e..2f49f772fb846f777afe9a8bdc2e56da97d83e8a 100644 (file)
--- a/doc/dev/perf_counters.rst
+++ b/doc/dev/perf_counters.rst
@@ -4,7 +4,7 @@
 
 The perf counters provide generic internal infrastructure for gauges and counters.  The counted values can be both integer and float.  There is also an "average" type (normally float) that combines a sum and num counter which can be divided to provide an average.
 
-The intention is that this data will be collected and aggregated by a tool like ``collectd`` or ``statsd`` and fed into a tool like ``graphite`` for graphing and analysis.
+The intention is that this data will be collected and aggregated by a tool like ``collectd`` or ``statsd`` and fed into a tool like ``graphite`` for graphing and analysis.  Also, note the :doc:`../mgr/prometheus`.
 
 Access
 ------

diff --git a/doc/mgr/index.rst b/doc/mgr/index.rst
index 815371dd2f35c6762216d056d38c65dd86cdb719..29a221661040829e2991c332cbd379312b019236 100644 (file)
--- a/doc/mgr/index.rst
+++ b/doc/mgr/index.rst
@@ -29,5 +29,6 @@ sensible.
     Dashboard plugin <dashboard>
     RESTful plugin <restful>
     Zabbix plugin <zabbix>
+    Prometheus plugin <prometheus>
     Writing plugins <plugins>
 

diff --git a/doc/mgr/prometheus.rst b/doc/mgr/prometheus.rst
new file mode 100644 (file)
index 0000000..2213156
--- /dev/null
+++ b/doc/mgr/prometheus.rst
@@ -0,0 +1,50 @@
+Prometheus plugin
+=================
+
+Provides a Prometheus exporter to pass on Ceph performance counters
+from the collection point in ceph-mgr.  Ceph-mgr receives MMgrReport
+messages from all MgrClient processes (mons and OSDs, for instance)
+with performance counter schema data and actual counter data, and keeps
+a circular buffer of the last N samples.  This plugin creates an HTTP
+endpoint (like all Prometheus exporters) and retrieves the latest sample
+of every counter when polled (or "scraped" in Prometheus terminology).
+The HTTP path and query parameters are ignored; all extant counters
+for all reporting entities are returned in text exposition format.
+(See the Prometheus `documentation <https://prometheus.io/docs/instrumenting/exposition_formats/#text-format-details>`_.)
+
+Enabling
+--------
+
+The *prometheus* module is enabled with::
+
+  ceph mgr module enable prometheus
+
+Configuration
+-------------
+
+By default the module will accept HTTP requests on port ``9283`` on all
+IPv4 and IPv6 addresses on the host.  The port and listen address are both
+configurable with ``ceph config-key put``, with keys
+``mgr/prometheus/server_addr`` and ``mgr/prometheus/server_port``.
+This port is registered with Prometheus's `registry <https://github.com/prometheus/prometheus/wiki/Default-port-allocations>`_.
+
+Notes
+-----
+
+Counters and gauges are exported; currently histograms and long-running 
+averages are not.  It's possible that Ceph's 2-D histograms could be 
+reduced to two separate 1-D histograms, and that long-running averages
+could be exported as Prometheus' Summary type.
+
+The names of the stats are exactly as Ceph names them, with
+illegal characters ``.`` and ``-`` translated to ``_``.  There is one
+label applied, ``daemon``, and its value is the daemon.id for the
+daemon in question (e.g. ``{daemon=mon.hosta}`` or ``{daemon=osd.11}``).
+
+Timestamps, as with many Prometheus exporters, are established by
+the server's scrape time (Prometheus expects that it is polling the
+actual counter process synchronously).  It is possible to supply a
+timestamp along with the stat report, but the Prometheus team strongly
+advises against this.  This means that timestamps will be delayed by
+an unpredictable amount; it's not clear if this will be problematic,
+but it's worth knowing about.

diff --git a/doc/release-notes.rst b/doc/release-notes.rst
index 9b40925f6722e5dc9f83ddc5ed7d3483127631fd..03bc43d6b7e61f0d426d6f449c2c07df1830d34c 100644 (file)
--- a/doc/release-notes.rst
+++ b/doc/release-notes.rst
@@ -49,6 +49,8 @@ Major Changes from Kraken
     - The *ceph-mgr* daemon includes a REST-based management API.  The
       API is still experimental and somewhat limited but will form the basis
       for API-based management of Ceph going forward.  FIXME DOCS
+    - *ceph-mgr* also includes a Prometheus exporter plugin, which can
+      provide Ceph perfcounters to Prometheus.  See ceph-mgr docs.
 
   * The overall *scalability* of the cluster has improved. We have
     successfully tested clusters with up to 10,000 OSDs.