diff --git a/etc/emqx.conf b/etc/emqx.conf
index d3a1e7a67..692725314 100644
--- a/etc/emqx.conf
+++ b/etc/emqx.conf
@@ -2268,6 +2268,32 @@ broker.shared_dispatch_ack_enabled = false
 ## Value: Flag
 broker.route_batch_clean = off
 
+## Performance toggle for subscribe/unsubscribe wildcard topic
+## change this toggle only when there are many wildcard topics.
+## Value: Enum
+##  - key:   mnesia translational updates with per-key locks. recommended for single node setup.
+##  - tab:   mnesia translational updates with table lock. recommended for multi-nodes setup.
+##  - global: global lock protected updates. recommended for larger cluster.
+## NOTE: when changing from/to 'global' lock, it requires all nodes in the cluster
+## to be stopped before the change.
+# broker.perf.route_lock_type = key
+
+## Enable trie path compaction.
+## Enabling it significantly improves wildcard topic subscribe rate,
+## if wildcard topics have unique prefixes like: 'sensor/{{id}}/+/',
+## where ID is unique per subscriber.
+##
+## Topic match performance (when publishing) may degrade if messages
+## are mostly published to topics with large number of levels.
+##
+## NOTE: This is a cluster-wide configuration.
+## It rquires all nodes to be stopped before changing it.
+##
+## Value: Enum
+##  - true: enable trie path compaction
+##  - false: disable trie path compaction
+# broker.perf.trie_compaction = true
+
 ## CONFIG_SECTION_BGN=sys_mon ==================================================
 
 ## Enable Long GC monitoring. Disable if the value is 0.
diff --git a/priv/emqx.schema b/priv/emqx.schema
index 79811be67..e759a3950 100644
--- a/priv/emqx.schema
+++ b/priv/emqx.schema
@@ -2255,7 +2255,7 @@ end}.
 ]}.
 
 %% @doc performance toggle for subscribe/unsubscribe wildcard topic
-%%      change this toggle only if you have many wildcard topics.
+%%      change this toggle only when there are many wildcard topics.
 %% key:   mnesia translational updates with per-key locks. recommended for single node setup.
 %% tab:   mnesia translational updates with table lock. recommended for multi-nodes setup.
 %% global: global lock protected updates. recommended for larger cluster.
@@ -2271,6 +2271,9 @@ end}.
 %%
 %% Topic match performance (when publishing) may degrade if messages
 %% are mostly published to topics with large number of levels.
+%%
+%% NOTE: This is a cluster-wide configuration.
+%% It rquires all nodes to be stopped before changing it.
 {mapping, "broker.perf.trie_compaction", "emqx.trie_compaction", [
   {default, true},
   {datatype, {enum, [true, false]}}