From: Dan Mick Date: Fri, 21 Jul 2017 03:14:42 +0000 (-0700) Subject: doc/mgr: add Prometheus plugin docs X-Git-Tag: v12.1.2~187^2 X-Git-Url: http://git-server-git.apps.pok.os.sepia.ceph.com/?a=commitdiff_plain;h=refs%2Fpull%2F16406%2Fhead;p=ceph.git doc/mgr: add Prometheus plugin docs Signed-off-by: Dan Mick --- diff --git a/doc/dev/perf_counters.rst b/doc/dev/perf_counters.rst index 398d51a00ee9..2f49f772fb84 100644 --- 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 815371dd2f35..29a221661040 100644 --- a/doc/mgr/index.rst +++ b/doc/mgr/index.rst @@ -29,5 +29,6 @@ sensible. Dashboard plugin RESTful plugin Zabbix plugin + Prometheus plugin Writing plugins diff --git a/doc/mgr/prometheus.rst b/doc/mgr/prometheus.rst new file mode 100644 index 000000000000..2213156bf1a3 --- /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 `_.) + +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 `_. + +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 9b40925f6722..03bc43d6b7e6 100644 --- 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.