From f680f5c5e8f6433378aea2e3c9448b9ab2d9369e Mon Sep 17 00:00:00 2001 From: Kefu Chai Date: Tue, 27 Apr 2021 14:26:51 +0800 Subject: [PATCH 1/2] doc/cephfs/mds-config-ref: render options using confval directive less repeating, better maintanability this way Signed-off-by: Kefu Chai --- doc/cephfs/mds-config-ref.rst | 464 ++++----------------------------- src/common/options/mds.yaml.in | 83 ++++++ 2 files changed, 130 insertions(+), 417 deletions(-) diff --git a/doc/cephfs/mds-config-ref.rst b/doc/cephfs/mds-config-ref.rst index 6f4b045c85b..9dba82815f3 100644 --- a/doc/cephfs/mds-config-ref.rst +++ b/doc/cephfs/mds-config-ref.rst @@ -15,420 +15,50 @@ .. confval:: mds_dirstat_min_interval .. confval:: mds_scatter_nudge_interval .. confval:: mds_client_prealloc_inos - -``mds_early_reply`` - -:Description: Determines whether the MDS should allow clients to see request - results before they commit to the journal. - -:Type: Boolean -:Default: ``true`` - - -``mds_default_dir_hash`` - -:Description: The function to use for hashing files across directory fragments. -:Type: 32-bit Integer -:Default: ``2`` (i.e., rjenkins) - - -``mds_log_skip_corrupt_events`` - -:Description: Determines whether the MDS should try to skip corrupt journal - events during journal replay. - -:Type: Boolean -:Default: ``false`` - - -``mds_log_max_events`` - -:Description: The maximum events in the journal before we initiate trimming. - Set to ``-1`` to disable limits. - -:Type: 32-bit Integer -:Default: ``-1`` - - -``mds_log_max_segments`` - -:Description: The maximum number of segments (objects) in the journal before - we initiate trimming. Set to ``-1`` to disable limits. - -:Type: 32-bit Integer -:Default: ``128`` - - -``mds_bal_sample_interval`` - -:Description: Determines how frequently to sample directory temperature - (for fragmentation decisions). - -:Type: Float -:Default: ``3`` - - -``mds_bal_replicate_threshold`` - -:Description: The maximum temperature before Ceph attempts to replicate - metadata to other nodes. - -:Type: Float -:Default: ``8000`` - - -``mds_bal_unreplicate_threshold`` - -:Description: The minimum temperature before Ceph stops replicating - metadata to other nodes. - -:Type: Float -:Default: ``0`` - - -``mds_bal_split_size`` - -:Description: The maximum directory size before the MDS will split a directory - fragment into smaller bits. - -:Type: 32-bit Integer -:Default: ``10000`` - - -``mds_bal_split_rd`` - -:Description: The maximum directory read temperature before Ceph splits - a directory fragment. - -:Type: Float -:Default: ``25000`` - - -``mds_bal_split_wr`` - -:Description: The maximum directory write temperature before Ceph splits - a directory fragment. - -:Type: Float -:Default: ``10000`` - - -``mds_bal_split_bits`` - -:Description: The number of bits by which to split a directory fragment. -:Type: 32-bit Integer -:Default: ``3`` - - -``mds_bal_merge_size`` - -:Description: The minimum directory size before Ceph tries to merge - adjacent directory fragments. - -:Type: 32-bit Integer -:Default: ``50`` - - -``mds_bal_interval`` - -:Description: The frequency (in seconds) of workload exchanges between MDSs. -:Type: 32-bit Integer -:Default: ``10`` - - -``mds_bal_fragment_interval`` - -:Description: The delay (in seconds) between a fragment being eligible for split - or merge and executing the fragmentation change. -:Type: 32-bit Integer -:Default: ``5`` - - -``mds_bal_fragment_fast_factor`` - -:Description: The ratio by which frags may exceed the split size before - a split is executed immediately (skipping the fragment interval) -:Type: Float -:Default: ``1.5`` - -``mds_bal_fragment_size_max`` - -:Description: The maximum size of a fragment before any new entries - are rejected with ENOSPC. -:Type: 32-bit Integer -:Default: ``100000`` - -``mds_bal_idle_threshold`` - -:Description: The minimum temperature before Ceph migrates a subtree - back to its parent. - -:Type: Float -:Default: ``0`` - - -``mds_bal_max`` - -:Description: The number of iterations to run balancer before Ceph stops. - (used for testing purposes only) - -:Type: 32-bit Integer -:Default: ``-1`` - - -``mds_bal_max_until`` - -:Description: The number of seconds to run balancer before Ceph stops. - (used for testing purposes only) - -:Type: 32-bit Integer -:Default: ``-1`` - - -``mds_bal_mode`` - -:Description: The method for calculating MDS load. - - - ``0`` = Hybrid. - - ``1`` = Request rate and latency. - - ``2`` = CPU load. - -:Type: 32-bit Integer -:Default: ``0`` - - -``mds_bal_min_rebalance`` - -:Description: The minimum subtree temperature before Ceph migrates. -:Type: Float -:Default: ``0.1`` - - -``mds_bal_min_start`` - -:Description: The minimum subtree temperature before Ceph searches a subtree. -:Type: Float -:Default: ``0.2`` - - -``mds_bal_need_min`` - -:Description: The minimum fraction of target subtree size to accept. -:Type: Float -:Default: ``0.8`` - - -``mds_bal_need_max`` - -:Description: The maximum fraction of target subtree size to accept. -:Type: Float -:Default: ``1.2`` - - -``mds_bal_midchunk`` - -:Description: Ceph will migrate any subtree that is larger than this fraction - of the target subtree size. - -:Type: Float -:Default: ``0.3`` - - -``mds_bal_minchunk`` - -:Description: Ceph will ignore any subtree that is smaller than this fraction - of the target subtree size. - -:Type: Float -:Default: ``0.001`` - - -``mds_bal_target_removal_min`` - -:Description: The minimum number of balancer iterations before Ceph removes - an old MDS target from the MDS map. - -:Type: 32-bit Integer -:Default: ``5`` - - -``mds_bal_target_removal_max`` - -:Description: The maximum number of balancer iterations before Ceph removes - an old MDS target from the MDS map. - -:Type: 32-bit Integer -:Default: ``10`` - - -``mds_replay_interval`` - -:Description: The journal poll interval when in standby-replay mode. - ("hot standby") - -:Type: Float -:Default: ``1`` - - -``mds_shutdown_check`` - -:Description: The interval for polling the cache during MDS shutdown. -:Type: 32-bit Integer -:Default: ``0`` - - -``mds_thrash_exports`` - -:Description: Ceph will randomly export subtrees between nodes (testing only). -:Type: 32-bit Integer -:Default: ``0`` - - -``mds_thrash_fragments`` - -:Description: Ceph will randomly fragment or merge directories. -:Type: 32-bit Integer -:Default: ``0`` - - -``mds_dump_cache_on_map`` - -:Description: Ceph will dump the MDS cache contents to a file on each MDSMap. -:Type: Boolean -:Default: ``false`` - - -``mds_dump_cache_after_rejoin`` - -:Description: Ceph will dump MDS cache contents to a file after - rejoining the cache (during recovery). - -:Type: Boolean -:Default: ``false`` - - -``mds_verify_scatter`` - -:Description: Ceph will assert that various scatter/gather invariants - are ``true`` (developers only). - -:Type: Boolean -:Default: ``false`` - - -``mds_debug_scatterstat`` - -:Description: Ceph will assert that various recursive stat invariants - are ``true`` (for developers only). - -:Type: Boolean -:Default: ``false`` - - -``mds_debug_frag`` - -:Description: Ceph will verify directory fragmentation invariants - when convenient (developers only). - -:Type: Boolean -:Default: ``false`` - - -``mds_debug_auth_pins`` - -:Description: The debug auth pin invariants (for developers only). -:Type: Boolean -:Default: ``false`` - - -``mds_debug_subtrees`` - -:Description: The debug subtree invariants (for developers only). -:Type: Boolean -:Default: ``false`` - - -``mds_kill_mdstable_at`` - -:Description: Ceph will inject MDS failure in MDSTable code - (for developers only). - -:Type: 32-bit Integer -:Default: ``0`` - - -``mds_kill_export_at`` - -:Description: Ceph will inject MDS failure in the subtree export code - (for developers only). - -:Type: 32-bit Integer -:Default: ``0`` - - -``mds_kill_import_at`` - -:Description: Ceph will inject MDS failure in the subtree import code - (for developers only). - -:Type: 32-bit Integer -:Default: ``0`` - - -``mds_kill_link_at`` - -:Description: Ceph will inject MDS failure in hard link code - (for developers only). - -:Type: 32-bit Integer -:Default: ``0`` - - -``mds_kill_rename_at`` - -:Description: Ceph will inject MDS failure in the rename code - (for developers only). - -:Type: 32-bit Integer -:Default: ``0`` - - -``mds_wipe_sessions`` - -:Description: Ceph will delete all client sessions on startup - (for testing only). - -:Type: Boolean -:Default: ``false`` - - -``mds_wipe_ino_prealloc`` - -:Description: Ceph will delete ino preallocation metadata on startup - (for testing only). - -:Type: Boolean -:Default: ``false`` - - -``mds_skip_ino`` - -:Description: The number of inode numbers to skip on startup - (for testing only). - -:Type: 32-bit Integer -:Default: ``0`` - - -``mds_min_caps_per_client`` - -:Description: Set the minimum number of capabilities a client may hold. -:Type: Integer -:Default: ``100`` - - -``mds_max_ratio_caps_per_client`` - -:Description: Set the maximum ratio of current caps that may be recalled during MDS cache pressure. -:Type: Float -:Default: ``0.8`` +.. confval:: mds_early_reply +.. confval:: mds_default_dir_hash +.. confval:: mds_log_skip_corrupt_events +.. confval:: mds_log_max_events +.. confval:: mds_log_max_segments +.. confval:: mds_bal_sample_interval +.. confval:: mds_bal_replicate_threshold +.. confval:: mds_bal_unreplicate_threshold +.. confval:: mds_bal_split_size +.. confval:: mds_bal_split_rd +.. confval:: mds_bal_split_wr +.. confval:: mds_bal_split_bits +.. confval:: mds_bal_merge_size +.. confval:: mds_bal_interval +.. confval:: mds_bal_fragment_interval +.. confval:: mds_bal_fragment_fast_factor +.. confval:: mds_bal_fragment_size_max +.. confval:: mds_bal_idle_threshold +.. confval:: mds_bal_max +.. confval:: mds_bal_max_until +.. confval:: mds_bal_mode +.. confval:: mds_bal_min_rebalance +.. confval:: mds_bal_min_start +.. confval:: mds_bal_need_min +.. confval:: mds_bal_need_max +.. confval:: mds_bal_midchunk +.. confval:: mds_bal_minchunk +.. confval:: mds_replay_interval +.. confval:: mds_shutdown_check +.. confval:: mds_thrash_exports +.. confval:: mds_thrash_fragments +.. confval:: mds_dump_cache_on_map +.. confval:: mds_dump_cache_after_rejoin +.. confval:: mds_verify_scatter +.. confval:: mds_debug_scatterstat +.. confval:: mds_debug_frag +.. confval:: mds_debug_auth_pins +.. confval:: mds_debug_subtrees +.. confval:: mds_kill_mdstable_at +.. confval:: mds_kill_export_at +.. confval:: mds_kill_import_at +.. confval:: mds_kill_link_at +.. confval:: mds_kill_rename_at +.. confval:: mds_wipe_sessions +.. confval:: mds_wipe_ino_prealloc +.. confval:: mds_skip_ino +.. confval:: mds_min_caps_per_client diff --git a/src/common/options/mds.yaml.in b/src/common/options/mds.yaml.in index 80edde2ff85..870cdd60a8a 100644 --- a/src/common/options/mds.yaml.in +++ b/src/common/options/mds.yaml.in @@ -441,6 +441,8 @@ options: level: advanced desc: additional reply to clients that metadata requests are complete but not yet durable + fmt_desc: Determines whether the MDS should allow clients to see request + results before they commit to the journal. default: true services: - mds @@ -459,6 +461,7 @@ options: type: int level: advanced desc: hash function to select directory fragment for dentry name + fmt_desc: The function to use for hashing files across directory fragments. # CEPH_STR_HASH_RJENKINS default: 2 services: @@ -477,11 +480,15 @@ options: default: false services: - mds + fmt_desc: Determines whether the MDS should try to skip corrupt journal + events during journal replay. with_legacy: true - name: mds_log_max_events type: int level: advanced desc: maximum number of events in the MDS journal (-1 is unlimited) + fmt_desc: The maximum events in the journal before we initiate trimming. + Set to ``-1`` to disable limits. default: -1 services: - mds @@ -507,6 +514,8 @@ options: type: uint level: advanced desc: maximum number of segments which may be untrimmed + fmt_desc: The maximum number of segments (objects) in the journal before + we initiate trimming. Set to ``-1`` to disable limits. default: 128 services: - mds @@ -581,6 +590,8 @@ options: type: float level: advanced desc: interval in seconds between balancer ticks + fmt_desc: Determines how frequently to sample directory temperature + (for fragmentation decisions). default: 3 services: - mds @@ -589,6 +600,8 @@ options: type: float level: advanced desc: hot popularity threshold to replicate a subtree + fmt_desc: The maximum temperature before Ceph attempts to replicate + metadata to other nodes. default: 8000 services: - mds @@ -597,6 +610,8 @@ options: type: float level: advanced desc: cold popularity threshold to merge subtrees + fmt_desc: The minimum temperature before Ceph stops replicating + metadata to other nodes. default: 0 services: - mds @@ -605,6 +620,8 @@ options: type: int level: advanced desc: minimum size of directory fragment before splitting + fmt_desc: The maximum directory size before the MDS will split a directory + fragment into smaller bits. default: 10000 services: - mds @@ -613,6 +630,8 @@ options: type: float level: advanced desc: hot read popularity threshold for splitting a directory fragment + fmt_desc: The maximum directory read temperature before Ceph splits + a directory fragment. default: 25000 services: - mds @@ -621,6 +640,8 @@ options: type: float level: advanced desc: hot write popularity threshold for splitting a directory fragment + fmt_desc: The maximum directory write temperature before Ceph splits + a directory fragment. default: 10000 services: - mds @@ -629,6 +650,7 @@ options: type: int level: advanced desc: power of two child fragments for a fragment on split + fmt_desc: The number of bits by which to split a directory fragment. default: 3 services: - mds @@ -639,6 +661,8 @@ options: type: int level: advanced desc: size of fragments where merging should occur + fmt_desc: The minimum directory size before Ceph tries to merge + adjacent directory fragments. default: 50 services: - mds @@ -647,6 +671,7 @@ options: type: int level: advanced desc: interval between MDS balancer cycles + fmt_desc: The frequency (in seconds) of workload exchanges between MDSs. default: 10 services: - mds @@ -654,6 +679,8 @@ options: type: int level: advanced desc: delay in seconds before interrupting client IO to perform splits + fmt_desc: The delay (in seconds) between a fragment being eligible for split + or merge and executing the fragmentation change. default: 5 services: - mds @@ -662,6 +689,8 @@ options: type: int level: advanced desc: maximum size of a directory fragment before new creat/links fail + fmt_desc: The maximum size of a fragment before any new entries + are rejected with ENOSPC. default: 100000 services: - mds @@ -671,6 +700,8 @@ options: type: float level: advanced desc: ratio of mds_bal_split_size at which fast fragment splitting occurs + fmt_desc: The ratio by which frags may exceed the split size before + a split is executed immediately (skipping the fragment interval) default: 1.5 services: - mds @@ -691,6 +722,8 @@ options: type: float level: advanced desc: idle metadata popularity threshold before rebalancing + fmt_desc: The minimum temperature before Ceph migrates a subtree + back to its parent. default: 0 services: - mds @@ -701,6 +734,8 @@ options: default: -1 services: - mds + fmt_desc: The number of iterations to run balancer before Ceph stops. + (used for testing purposes only) with_legacy: true - name: mds_bal_max_until type: int @@ -708,6 +743,8 @@ options: default: -1 services: - mds + fmt_desc: The number of seconds to run balancer before Ceph stops. + (used for testing purposes only) with_legacy: true - name: mds_bal_mode type: int @@ -715,12 +752,19 @@ options: default: 0 services: - mds + fmt_desc: | + The method for calculating MDS load. + + - ``0`` = Hybrid. + - ``1`` = Request rate and latency. + - ``2`` = CPU load. with_legacy: true # must be this much above average before we export anything - name: mds_bal_min_rebalance type: float level: dev desc: amount overloaded over internal target before balancer begins offloading + fmt_desc: The minimum subtree temperature before Ceph migrates. default: 0.1 services: - mds @@ -732,6 +776,7 @@ options: default: 0.2 services: - mds + fmt_desc: The minimum subtree temperature before Ceph searches a subtree. with_legacy: true # take within this range of what we need - name: mds_bal_need_min @@ -740,6 +785,7 @@ options: default: 0.8 services: - mds + fmt_desc: The minimum fraction of target subtree size to accept. with_legacy: true - name: mds_bal_need_max type: float @@ -747,6 +793,7 @@ options: default: 1.2 services: - mds + fmt_desc: The maximum fraction of target subtree size to accept. with_legacy: true # any sub bigger than this taken in full - name: mds_bal_midchunk @@ -755,6 +802,8 @@ options: default: 0.3 services: - mds + fmt_desc: Ceph will migrate any subtree that is larger than this fraction + of the target subtree size. with_legacy: true # never take anything smaller than this - name: mds_bal_minchunk @@ -763,6 +812,8 @@ options: default: 0.001 services: - mds + fmt_desc: Ceph will ignore any subtree that is smaller than this fraction + of the target subtree size. with_legacy: true # target decay half-life in MDSMap (2x larger is approx. 2x slower) - name: mds_bal_target_decay @@ -787,6 +838,8 @@ options: type: float level: advanced desc: time in seconds between replay of updates to journal by standby replay MDS + fmt_desc: The journal poll interval when in standby-replay mode. + ("hot standby") default: 1 services: - mds @@ -797,6 +850,7 @@ options: default: 0 services: - mds + fmt_desc: The interval for polling the cache during MDS shutdown. with_legacy: true - name: mds_thrash_exports type: int @@ -804,6 +858,7 @@ options: default: 0 services: - mds + fmt_desc: Ceph will randomly export subtrees between nodes (testing only). with_legacy: true - name: mds_thrash_fragments type: int @@ -811,6 +866,7 @@ options: default: 0 services: - mds + fmt_desc: Ceph will randomly fragment or merge directories. with_legacy: true - name: mds_dump_cache_on_map type: bool @@ -818,6 +874,7 @@ options: default: false services: - mds + fmt_desc: Ceph will dump the MDS cache contents to a file on each MDSMap. with_legacy: true - name: mds_dump_cache_after_rejoin type: bool @@ -825,6 +882,8 @@ options: default: false services: - mds + fmt_desc: Ceph will dump MDS cache contents to a file after + rejoining the cache (during recovery). with_legacy: true - name: mds_verify_scatter type: bool @@ -832,6 +891,8 @@ options: default: false services: - mds + fmt_desc: Ceph will assert that various scatter/gather invariants + are ``true`` (developers only). with_legacy: true - name: mds_debug_scatterstat type: bool @@ -839,6 +900,8 @@ options: default: false services: - mds + fmt_desc: Ceph will assert that various recursive stat invariants + are ``true`` (for developers only). with_legacy: true - name: mds_debug_frag type: bool @@ -846,6 +909,8 @@ options: default: false services: - mds + fmt_desc: Ceph will verify directory fragmentation invariants + when convenient (developers only). with_legacy: true - name: mds_debug_auth_pins type: bool @@ -853,6 +918,7 @@ options: default: false services: - mds + fmt_desc: The debug auth pin invariants (for developers only). with_legacy: true - name: mds_debug_subtrees type: bool @@ -860,6 +926,7 @@ options: default: false services: - mds + fmt_desc: The debug subtree invariants (for developers only). with_legacy: true - name: mds_kill_mdstable_at type: int @@ -867,6 +934,8 @@ options: default: 0 services: - mds + fmt_desc: Ceph will inject MDS failure in MDSTable code + (for developers only). with_legacy: true - name: mds_max_export_size type: size @@ -880,6 +949,8 @@ options: default: 0 services: - mds + fmt_desc: Ceph will inject MDS failure in the subtree export code + (for developers only). with_legacy: true - name: mds_kill_import_at type: int @@ -887,6 +958,8 @@ options: default: 0 services: - mds + fmt_desc: Ceph will inject MDS failure in the subtree import code + (for developers only). with_legacy: true - name: mds_kill_link_at type: int @@ -894,6 +967,8 @@ options: default: 0 services: - mds + fmt_desc: Ceph will inject MDS failure in hard link code + (for developers only). with_legacy: true - name: mds_kill_rename_at type: int @@ -901,6 +976,8 @@ options: default: 0 services: - mds + fmt_desc: Ceph will inject MDS failure in the rename code + (for developers only). with_legacy: true - name: mds_kill_openc_at type: int @@ -958,6 +1035,8 @@ options: default: false services: - mds + fmt_desc: Ceph will delete all client sessions on startup + (for testing only). with_legacy: true - name: mds_wipe_ino_prealloc type: bool @@ -965,6 +1044,8 @@ options: default: false services: - mds + fmt_desc: Ceph will delete ino preallocation metadata on startup + (for testing only). with_legacy: true - name: mds_skip_ino type: int @@ -972,6 +1053,8 @@ options: default: 0 services: - mds + fmt_desc: The number of inode numbers to skip on startup + (for testing only). with_legacy: true - name: mds_enable_op_tracker type: bool From a2ed53a7fa349ceaded07a7d1f4cbccbe8be87c5 Mon Sep 17 00:00:00 2001 From: Kefu Chai Date: Wed, 28 Apr 2021 10:39:04 +0800 Subject: [PATCH 2/2] doc/_ext/ceph_confval: print "false" default values before this change, we check the exisitence of default value of an option using "if default", but this is wrong. what if "default" is an empty string or a numeric value of 0, or just False? after this change, its exisitence is checked using "if default is defined", so all "false" default values are rendered as well. Signed-off-by: Kefu Chai --- doc/_ext/ceph_confval.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/_ext/ceph_confval.py b/doc/_ext/ceph_confval.py index 28f97e9975c..98c5e2ff949 100644 --- a/doc/_ext/ceph_confval.py +++ b/doc/_ext/ceph_confval.py @@ -23,7 +23,7 @@ TEMPLATE = ''' {{ desc | wordwrap(70) | indent(3) }} {% endif %} :type: ``{{opt.type}}`` -{%- if default %} +{%- if default is defined %} {%- if opt.type == 'size' %} :default: ``{{ default | eval_size | iec_size }}`` {%- elif opt.type == 'secs' %}