[ceph.git] / ceph / doc / mgr / influx.rst

=============
Influx Module 
=============

The influx module continuously collects and sends time series data to an
influxdb database.

The influx module was introduced in the 13.x *Mimic* release.

--------
Enabling 
--------

To enable the module, use the following command:

::

    ceph mgr module enable influx

If you wish to subsequently disable the module, you can use the equivalent
*disable* command:

::

    ceph mgr module disable influx

-------------
Configuration 
-------------

For the influx module to send statistics to an InfluxDB server, it
is necessary to configure the servers address and some authentication
credentials.

Set configuration values using the following command:

::

    ceph config set mgr mgr/influx/<key> <value>


The most important settings are ``hostname``, ``username`` and ``password``.  
For example, a typical configuration might look like this:

::

    ceph config set mgr mgr/influx/hostname influx.mydomain.com
    ceph config set mgr mgr/influx/username admin123
    ceph config set mgr mgr/influx/password p4ssw0rd
    
Additional optional configuration settings are:

:interval: Time between reports to InfluxDB.  Default 30 seconds.
:database: InfluxDB database name.  Default "ceph".  You will need to create this database and grant write privileges to the configured username or the username must have admin privileges to create it.  
:port: InfluxDB server port.  Default 8086
:ssl: Use https connection for InfluxDB server. Use "true" or "false". Default false
:verify_ssl: Verify https cert for InfluxDB server. Use "true" or "false". Default true
:threads: How many worker threads should be spawned for sending data to InfluxDB. Default is 5
:batch_size: How big batches of data points should be when sending to InfluxDB. Default is 5000

---------
Debugging 
---------

By default, a few debugging statements as well as error statements have been set to print in the log files. Users can add more if necessary.
To make use of the debugging option in the module:

- Add this to the ceph.conf file.::

    [mgr]
        debug_mgr = 20  

- Use this command ``ceph influx self-test``.
- Check the log files. Users may find it easier to filter the log files using *mgr[influx]*.

--------------------
Interesting counters
--------------------

The following tables describe a subset of the values output by
this module.

^^^^^
Pools
^^^^^

+---------------+-----------------------------------------------------+
|Counter        | Description                                         |
+===============+=====================================================+
|stored         | Bytes stored in the pool not including copies       |
+---------------+-----------------------------------------------------+
|max_avail      | Max available number of bytes in the pool           |
+---------------+-----------------------------------------------------+
|objects        | Number of objects in the pool                       |
+---------------+-----------------------------------------------------+
|wr_bytes       | Number of bytes written in the pool                 |
+---------------+-----------------------------------------------------+
|dirty          | Number of bytes dirty in the pool                   |
+---------------+-----------------------------------------------------+
|rd_bytes       | Number of bytes read in the pool                    |
+---------------+-----------------------------------------------------+
|stored_raw     | Bytes used in pool including copies made            |
+---------------+-----------------------------------------------------+

^^^^
OSDs
^^^^

+------------+------------------------------------+
|Counter     | Description                        |
+============+====================================+
|op_w        | Client write operations            |
+------------+------------------------------------+
|op_in_bytes | Client operations total write size |
+------------+------------------------------------+
|op_r        | Client read operations             |
+------------+------------------------------------+
|op_out_bytes| Client operations total read size  |
+------------+------------------------------------+


+------------------------+--------------------------------------------------------------------------+
|Counter                 | Description                                                              |
+========================+==========================================================================+
|op_wip                  | Replication operations currently being processed (primary)               |
+------------------------+--------------------------------------------------------------------------+
|op_latency              | Latency of client operations (including queue time)                      |
+------------------------+--------------------------------------------------------------------------+
|op_process_latency      | Latency of client operations (excluding queue time)                      |           
+------------------------+--------------------------------------------------------------------------+
|op_prepare_latency      | Latency of client operations (excluding queue time and wait for finished)|
+------------------------+--------------------------------------------------------------------------+
|op_r_latency            | Latency of read operation (including queue time)                         |
+------------------------+--------------------------------------------------------------------------+
|op_r_process_latency    | Latency of read operation (excluding queue time)                         |
+------------------------+--------------------------------------------------------------------------+
|op_w_in_bytes           | Client data written                                                      |
+------------------------+--------------------------------------------------------------------------+
|op_w_latency            | Latency of write operation (including queue time)                        |
+------------------------+--------------------------------------------------------------------------+
|op_w_process_latency    | Latency of write operation (excluding queue time)                        |
+------------------------+--------------------------------------------------------------------------+
|op_w_prepare_latency    | Latency of write operations (excluding queue time and wait for finished) |
+------------------------+--------------------------------------------------------------------------+
|op_rw                   | Client read-modify-write operations                                      |
+------------------------+--------------------------------------------------------------------------+
|op_rw_in_bytes          | Client read-modify-write operations write in                             |
+------------------------+--------------------------------------------------------------------------+
|op_rw_out_bytes         | Client read-modify-write operations read out                             |
+------------------------+--------------------------------------------------------------------------+
|op_rw_latency           | Latency of read-modify-write operation (including queue time)            |
+------------------------+--------------------------------------------------------------------------+
|op_rw_process_latency   | Latency of read-modify-write operation (excluding queue time)            |
+------------------------+--------------------------------------------------------------------------+
|op_rw_prepare_latency   | Latency of read-modify-write operations (excluding queue time            |
|                        | and wait for finished)                                                   |
+------------------------+--------------------------------------------------------------------------+
|op_before_queue_op_lat  | Latency of IO before calling queue (before really queue into ShardedOpWq)|
|                        | op_before_dequeue_op_lat                                                 |
+------------------------+--------------------------------------------------------------------------+
|op_before_dequeue_op_lat| Latency of IO before calling dequeue_op(already dequeued and get PG lock)|
+------------------------+--------------------------------------------------------------------------+

Latency counters are measured in microseconds unless otherwise specified in the description.
Commit	Line	Data
3efd9988	1	=============
11fdf7f2	2	Influx Module
3efd9988 FG	3	=============
3efd9988 FG	4
11fdf7f2	5	The influx module continuously collects and sends time series data to an
3efd9988 FG	6	influxdb database.
3efd9988 FG	7
11fdf7f2	8	The influx module was introduced in the 13.x Mimic release.
3efd9988 FG	9
	10	--------
	11	Enabling
	12	--------
	13
	14	To enable the module, use the following command:
	15
	16	::
	17
	18	ceph mgr module enable influx
	19
	20	If you wish to subsequently disable the module, you can use the equivalent
	21	disable command:
	22
	23	::
	24
	25	ceph mgr module disable influx
	26
	27	-------------
	28	Configuration
	29	-------------
	30
	31	For the influx module to send statistics to an InfluxDB server, it
	32	is necessary to configure the servers address and some authentication
	33	credentials.
	34
	35	Set configuration values using the following command:
	36
	37	::
	38
11fdf7f2	39	ceph config set mgr mgr/influx/<key> <value>
3efd9988 FG	40
	41
	42	The most important settings are ``hostname``, ``username`` and ``password``.
	43	For example, a typical configuration might look like this:
	44
	45	::
	46
11fdf7f2 TL	47	ceph config set mgr mgr/influx/hostname influx.mydomain.com
	48	ceph config set mgr mgr/influx/username admin123
	49	ceph config set mgr mgr/influx/password p4ssw0rd
3efd9988 FG	50
	51	Additional optional configuration settings are:
	52
11fdf7f2	53	:interval: Time between reports to InfluxDB. Default 30 seconds.
3efd9988 FG	54	:database: InfluxDB database name. Default "ceph". You will need to create this database and grant write privileges to the configured username or the username must have admin privileges to create it.
3efd9988 FG	55	:port: InfluxDB server port. Default 8086
28e407b8 AA	56	:ssl: Use https connection for InfluxDB server. Use "true" or "false". Default false
28e407b8 AA	57	:verify_ssl: Verify https cert for InfluxDB server. Use "true" or "false". Default true
11fdf7f2 TL	58	:threads: How many worker threads should be spawned for sending data to InfluxDB. Default is 5
11fdf7f2 TL	59	:batch_size: How big batches of data points should be when sending to InfluxDB. Default is 5000
3efd9988 FG	60
	61	---------
	62	Debugging
	63	---------
	64
11fdf7f2	65	By default, a few debugging statements as well as error statements have been set to print in the log files. Users can add more if necessary.
3efd9988 FG	66	To make use of the debugging option in the module:
	67
	68	- Add this to the ceph.conf file.::
	69
	70	[mgr]
	71	debug_mgr = 20
	72
9f95a23c	73	- Use this command ``ceph influx self-test``.
3efd9988 FG	74	- Check the log files. Users may find it easier to filter the log files using mgr[influx].
	75
	76	--------------------
	77	Interesting counters
	78	--------------------
	79
	80	The following tables describe a subset of the values output by
	81	this module.
	82
	83	^^^^^
	84	Pools
	85	^^^^^
	86
	87	+---------------+-----------------------------------------------------+
	88	\|Counter \| Description \|
	89	+===============+=====================================================+
11fdf7f2	90	\|stored \| Bytes stored in the pool not including copies \|
3efd9988 FG	91	+---------------+-----------------------------------------------------+
	92	\|max_avail \| Max available number of bytes in the pool \|
	93	+---------------+-----------------------------------------------------+
	94	\|objects \| Number of objects in the pool \|
	95	+---------------+-----------------------------------------------------+
	96	\|wr_bytes \| Number of bytes written in the pool \|
	97	+---------------+-----------------------------------------------------+
	98	\|dirty \| Number of bytes dirty in the pool \|
	99	+---------------+-----------------------------------------------------+
	100	\|rd_bytes \| Number of bytes read in the pool \|
	101	+---------------+-----------------------------------------------------+
11fdf7f2	102	\|stored_raw \| Bytes used in pool including copies made \|
3efd9988 FG	103	+---------------+-----------------------------------------------------+
	104
	105	^^^^
	106	OSDs
	107	^^^^
	108
	109	+------------+------------------------------------+
	110	\|Counter \| Description \|
	111	+============+====================================+
	112	\|op_w \| Client write operations \|
	113	+------------+------------------------------------+
	114	\|op_in_bytes \| Client operations total write size \|
	115	+------------+------------------------------------+
	116	\|op_r \| Client read operations \|
	117	+------------+------------------------------------+
	118	\|op_out_bytes\| Client operations total read size \|
	119	+------------+------------------------------------+
	120
	121
	122	+------------------------+--------------------------------------------------------------------------+
	123	\|Counter \| Description \|
	124	+========================+==========================================================================+
	125	\|op_wip \| Replication operations currently being processed (primary) \|
	126	+------------------------+--------------------------------------------------------------------------+
	127	\|op_latency \| Latency of client operations (including queue time) \|
	128	+------------------------+--------------------------------------------------------------------------+
	129	\|op_process_latency \| Latency of client operations (excluding queue time) \|
	130	+------------------------+--------------------------------------------------------------------------+
	131	\|op_prepare_latency \| Latency of client operations (excluding queue time and wait for finished)\|
	132	+------------------------+--------------------------------------------------------------------------+
	133	\|op_r_latency \| Latency of read operation (including queue time) \|
	134	+------------------------+--------------------------------------------------------------------------+
	135	\|op_r_process_latency \| Latency of read operation (excluding queue time) \|
	136	+------------------------+--------------------------------------------------------------------------+
	137	\|op_w_in_bytes \| Client data written \|
	138	+------------------------+--------------------------------------------------------------------------+
	139	\|op_w_latency \| Latency of write operation (including queue time) \|
	140	+------------------------+--------------------------------------------------------------------------+
	141	\|op_w_process_latency \| Latency of write operation (excluding queue time) \|
	142	+------------------------+--------------------------------------------------------------------------+
	143	\|op_w_prepare_latency \| Latency of write operations (excluding queue time and wait for finished) \|
	144	+------------------------+--------------------------------------------------------------------------+
	145	\|op_rw \| Client read-modify-write operations \|
	146	+------------------------+--------------------------------------------------------------------------+
	147	\|op_rw_in_bytes \| Client read-modify-write operations write in \|
	148	+------------------------+--------------------------------------------------------------------------+
	149	\|op_rw_out_bytes \| Client read-modify-write operations read out \|
	150	+------------------------+--------------------------------------------------------------------------+
	151	\|op_rw_latency \| Latency of read-modify-write operation (including queue time) \|
	152	+------------------------+--------------------------------------------------------------------------+
	153	\|op_rw_process_latency \| Latency of read-modify-write operation (excluding queue time) \|
	154	+------------------------+--------------------------------------------------------------------------+
	155	\|op_rw_prepare_latency \| Latency of read-modify-write operations (excluding queue time \|
	156	\| \| and wait for finished) \|
	157	+------------------------+--------------------------------------------------------------------------+
	158	\|op_before_queue_op_lat \| Latency of IO before calling queue (before really queue into ShardedOpWq)\|
	159	\| \| op_before_dequeue_op_lat \|
	160	+------------------------+--------------------------------------------------------------------------+
	161	\|op_before_dequeue_op_lat\| Latency of IO before calling dequeue_op(already dequeued and get PG lock)\|
	162	+------------------------+--------------------------------------------------------------------------+
	163
	164	Latency counters are measured in microseconds unless otherwise specified in the description.
	165