From b48b6f4ed8b5f5b5852cbbfd5b3d5b650efb7f1b Mon Sep 17 00:00:00 2001 From: Nathan Cutler Date: Tue, 18 Apr 2017 08:06:01 +0200 Subject: [PATCH] doc: mention --show-mappings in crushtool manpage Fixes: http://tracker.ceph.com/issues/19649 Signed-off-by: Loic Dachary Signed-off-by: Nathan Cutler --- doc/man/8/crushtool.rst | 59 +++++++++++++++++++++++++++-------------- 1 file changed, 39 insertions(+), 20 deletions(-) diff --git a/doc/man/8/crushtool.rst b/doc/man/8/crushtool.rst index 3c449476b30..c7b88f86c93 100644 --- a/doc/man/8/crushtool.rst +++ b/doc/man/8/crushtool.rst @@ -17,15 +17,15 @@ Description =========== **crushtool** is a utility that lets you create, compile, decompile - and test CRUSH map files. +and test CRUSH map files. CRUSH is a pseudo-random data distribution algorithm that efficiently -maps input values (typically data objects) across a heterogeneous, -hierarchically structured device map. The algorithm was originally -described in detail in the following paper (although it has evolved -some since then): +maps input values (which, in the context of Ceph, correspond to Placement +Groups) across a heterogeneous, hierarchically structured device map. +The algorithm was originally described in detail in the following paper +(although it has evolved some since then):: - http://www.ssrc.ucsc.edu/Papers/weil-sc06.pdf + http://www.ssrc.ucsc.edu/Papers/weil-sc06.pdf The tool has four modes of operation. @@ -46,7 +46,9 @@ The tool has four modes of operation. .. option:: --test will perform a dry run of a CRUSH mapping for a range of input - object names. See below for a detailed explanation. + values ``[--min-x,--max-x]`` (default ``[0,1023]``) which can be + thought of as simulated Placement Groups. See below for a more + detailed explanation. Unlike other Ceph tools, **crushtool** does not accept generic options such as **--debug-crush** from the command line. They can, however, be @@ -60,28 +62,30 @@ Running tests with --test ========================= The test mode will use the input crush map ( as specified with **-i -map** ) and perform a dry run of CRUSH mapping or random placement ( -if **--simulate** is set ). On completion, two kinds of reports can be +map** ) and perform a dry run of CRUSH mapping or random placement +(if **--simulate** is set ). On completion, two kinds of reports can be created. 1) The **--show-...** option outputs human readable information on stderr. 2) The **--output-csv** option creates CSV files that are documented by the **--help-output** option. +Note: Each Placement Group (PG) has an integer ID which can be obtained +from ``ceph pg dump`` (for example PG 2.2f means pool id 2, PG id 32). +The pool and PG IDs are combined by a function to get a value which is +given to CRUSH to map it to OSDs. crushtool does not know about PGs or +pools; it only runs simulations by mapping values in the range +``[--min-x,--max-x]``. + + .. option:: --show-statistics - For each rule, displays the mapping of each object. For instance:: - - CRUSH rule 1 x 24 [11,6] - - shows that object **24** is mapped to devices **[11,6]** by rule - **1**. At the end of the mapping details, a summary of the - distribution is displayed. For instance:: + Displays a summary of the distribution. For instance:: rule 1 (metadata) num_rep 5 result size == 5: 1024/1024 shows that rule **1** which is named **metadata** successfully - mapped **1024** objects to **result size == 5** devices when trying + mapped **1024** values to **result size == 5** devices when trying to map them to **num_rep 5** replicas. When it fails to provide the required mapping, presumably because the number of **tries** must be increased, a breakdown of the failures is displayed. For instance:: @@ -91,12 +95,22 @@ documented by the **--help-output** option. rule 1 (metadata) num_rep 10 result size == 10: 927/1024 shows that although **num_rep 10** replicas were required, **4** - out of **1024** objects ( **4/1024** ) were mapped to **result size + out of **1024** values ( **4/1024** ) were mapped to **result size == 8** devices only. +.. option:: --show-mappings + + Displays the mapping of each value in the range ``[--min-x,--max-x]``. + For instance:: + + CRUSH rule 1 x 24 [11,6] + + shows that value **24** is mapped to devices **[11,6]** by rule + **1**. + .. option:: --show-bad-mappings - Displays which object failed to be mapped to the required number of + Displays which value failed to be mapped to the required number of devices. For instance:: bad mapping rule 1 x 781 num_rep 7 result [8,10,2,11,6,9] @@ -113,7 +127,7 @@ documented by the **--help-output** option. device 1: stored : 963 expected : 853.333 ... - shows that device **0** stored **951** objects and was expected to store **853**. + shows that device **0** stored **951** values and was expected to store **853**. Implies **--show-statistics**. .. option:: --show-utilization-all @@ -244,6 +258,11 @@ creating a new Ceph cluster. They can be further edited with:: # recompile crushtool -c map.txt -o crushmap +Example output from --test +========================== + +See https://github.com/ceph/ceph/blob/master/src/test/cli/crushtool/set-choose.t +for sample ``crushtool --test`` commands and output produced thereby. Availability ============