[ceph.git] / ceph / doc / rados / operations / read-balancer.rst

.. _read_balancer:

=======================================
Operating the Read (Primary) Balancer
=======================================

You might be wondering: How can I improve performance in my Ceph cluster?
One important data point you can check is the ``read_balance_score`` on each
of your replicated pools.

This metric, available via ``ceph osd pool ls detail`` (see :ref:`rados_pools`
for more details) indicates read performance, or how balanced the primaries are
for each replicated pool. In most cases, if a ``read_balance_score`` is above 1
(for instance, 1.5), this means that your pool has unbalanced primaries and that
you may want to try improving your read performance with the read balancer.

Online Optimization
===================

At present, there is no online option for the read balancer. However, we plan to add
the read balancer as an option to the :ref:`balancer` in the next Ceph version
so it can be enabled to run automatically in the background like the upmap balancer.

Offline Optimization
====================

Primaries are updated with an offline optimizer that is built into the
:ref:`osdmaptool`.

#. Grab the latest copy of your osdmap:

   .. prompt:: bash $

      ceph osd getmap -o om

#. Run the optimizer:

   .. prompt:: bash $

      osdmaptool om --read out.txt --read-pool <pool name> [--vstart] 

   It is highly recommended that you run the capacity balancer before running the
   balancer to ensure optimal results. See :ref:`upmap` for details on how to balance
   capacity in a cluster.

#. Apply the changes:

   .. prompt:: bash $

      source out.txt

   In the above example, the proposed changes are written to the output file
   ``out.txt``. The commands in this procedure are normal Ceph CLI commands
   that can be run in order to apply the changes to the cluster.

   If you are working in a vstart cluster, you may pass the ``--vstart`` parameter
   as shown above so the CLI commands are formatted with the `./bin/` prefix.

   Note that any time the number of pgs changes (for instance, if the pg autoscaler [:ref:`pg-autoscaler`]
   kicks in), you should consider rechecking the scores and rerunning the balancer if needed.

To see some details about what the tool is doing, you can pass
``--debug-osd 10`` to ``osdmaptool``. To see even more details, pass
``--debug-osd 20`` to ``osdmaptool``.
Commit	Line	Data
aee94f69 TL	1	.. _read_balancer:
	2
	3	=======================================
	4	Operating the Read (Primary) Balancer
	5	=======================================
	6
	7	You might be wondering: How can I improve performance in my Ceph cluster?
	8	One important data point you can check is the ``read_balance_score`` on each
	9	of your replicated pools.
	10
	11	This metric, available via ``ceph osd pool ls detail`` (see :ref:`rados_pools`
	12	for more details) indicates read performance, or how balanced the primaries are
	13	for each replicated pool. In most cases, if a ``read_balance_score`` is above 1
	14	(for instance, 1.5), this means that your pool has unbalanced primaries and that
	15	you may want to try improving your read performance with the read balancer.
	16
	17	Online Optimization
	18	===================
	19
	20	At present, there is no online option for the read balancer. However, we plan to add
	21	the read balancer as an option to the :ref:`balancer` in the next Ceph version
	22	so it can be enabled to run automatically in the background like the upmap balancer.
	23
	24	Offline Optimization
	25	====================
	26
	27	Primaries are updated with an offline optimizer that is built into the
	28	:ref:`osdmaptool`.
	29
	30	#. Grab the latest copy of your osdmap:
	31
	32	.. prompt:: bash $
	33
	34	ceph osd getmap -o om
	35
	36	#. Run the optimizer:
	37
	38	.. prompt:: bash $
	39
	40	osdmaptool om --read out.txt --read-pool <pool name> [--vstart]
	41
	42	It is highly recommended that you run the capacity balancer before running the
	43	balancer to ensure optimal results. See :ref:`upmap` for details on how to balance
	44	capacity in a cluster.
	45
	46	#. Apply the changes:
	47
	48	.. prompt:: bash $
	49
	50	source out.txt
	51
	52	In the above example, the proposed changes are written to the output file
	53	``out.txt``. The commands in this procedure are normal Ceph CLI commands
	54	that can be run in order to apply the changes to the cluster.
	55
	56	If you are working in a vstart cluster, you may pass the ``--vstart`` parameter
	57	as shown above so the CLI commands are formatted with the `./bin/` prefix.
	58
	59	Note that any time the number of pgs changes (for instance, if the pg autoscaler [:ref:`pg-autoscaler`]
	60	kicks in), you should consider rechecking the scores and rerunning the balancer if needed.
	61
	62	To see some details about what the tool is doing, you can pass
	63	``--debug-osd 10`` to ``osdmaptool``. To see even more details, pass
	64	``--debug-osd 20`` to ``osdmaptool``.