From 47726f8b6642cbd66b435064a3bf031c5d6ba707 Mon Sep 17 00:00:00 2001 From: Dan Mick Date: Thu, 20 Jul 2017 20:14:42 -0700 Subject: [PATCH] doc/mgr: add Prometheus plugin docs Signed-off-by: Dan Mick --- doc/dev/perf_counters.rst | 2 +- doc/mgr/index.rst | 1 + doc/mgr/prometheus.rst | 50 +++++++++++++++++++++++++++++++++++++++ doc/release-notes.rst | 2 ++ 4 files changed, 54 insertions(+), 1 deletion(-) create mode 100644 doc/mgr/prometheus.rst diff --git a/doc/dev/perf_counters.rst b/doc/dev/perf_counters.rst index 398d51a00ee..2f49f772fb8 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 815371dd2f3..29a22166104 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 00000000000..2213156bf1a --- /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 9b40925f672..03bc43d6b7e 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. -- 2.39.5