docs(schema): Add descriptions of the records

apps/emqx/etc/emqx.conf

@@ -894,9 +894,9 @@ conn_congestion {
   ## Whether to alarm the congested connections.
   ##
   ## Sometimes the mqtt connection (usually an MQTT subscriber) may
-  ## get "congested" because there're too many packets to sent.
+  ## get "congested", because there're too many packets to sent.
   ## The socket tries to buffer the packets until the buffer is
-  ## full. If more packets comes after that, the packets will be
+  ## full. If more packets come after that, the packets will be
   ## "pending" in a queue and we consider the connection is
   ## "congested".
   ##
@@ -1100,7 +1100,7 @@ sys_topics {
   ## Default: 30s | disabled
   sys_heartbeat_interval = 30s
 
-  ## Whether to enable Client lifecycle event messages publish.
+  ## Whether to enable Client lifecycle event messages publishing.
   ## The following options are not only for enabling MQTT client event messages
   ## publish but also for Gateway clients. However, these kinds of clients type
   ## are distinguished by the Topic prefix:

apps/emqx/src/emqx_schema.erl

@@ -93,7 +93,7 @@
     comma_separated_atoms/0
 ]).
 
--export([namespace/0, roots/0, roots/1, fields/1]).
+-export([namespace/0, roots/0, roots/1, fields/1, desc/1]).
 -export([conf_get/2, conf_get/3, keys/2, filter/1]).
 -export([server_ssl_opts_schema/2, client_ssl_opts_schema/1, ciphers_schema/1, default_ciphers/1]).
 -export([sc/2, map/2]).
@@ -116,7 +116,7 @@ roots(high) ->
         {"listeners",
             sc(
                 ref("listeners"),
-                #{desc => "MQTT listeners identified by their protocol type and assigned names"}
+                #{}
             )},
         {"zones",
             sc(
@@ -133,12 +133,7 @@ roots(high) ->
         {"mqtt",
             sc(
                 ref("mqtt"),
-                #{
+                #{}
-                    desc =>
-                        "Global MQTT configuration.<br>\n"
-                        "The configs here work as default values which can be overridden\n"
-                        "in <code>zone</code> configs"
-                }
             )},
         {?EMQX_AUTHENTICATION_CONFIG_ROOT_NAME,
             authentication(
@@ -203,29 +198,17 @@ roots(low) ->
         {"force_gc",
             sc(
                 ref("force_gc"),
-                #{
+                #{}
-                    desc =>
-                        "Force the MQTT connection process garbage collection after\n"
-                        "this number of messages or bytes have passed through."
-                }
             )},
         {"conn_congestion",
             sc(
                 ref("conn_congestion"),
-                #{
+                #{}
-                    desc => "Congestion alarm settings"
-                }
             )},
         {"stats",
             sc(
                 ref("stats"),
-                #{
+                #{}
-                    desc =>
-                        "Enable/disable statistic data collection.\n"
-                        "Statistic data such as message receive/send count/rate etc. "
-                        "It provides insights of system performance and helps to diagnose issues. "
-                        "You can find statistic data from the dashboard, or from the '/stats' API."
-                }
             )},
         {"sysmon",
             sc(
@@ -250,10 +233,7 @@ roots(low) ->
         {"trace",
             sc(
                 ref("trace"),
-                #{
+                #{}
-                    desc =>
-                        "Real-time filtering logs for the ClientID or Topic or IP for debugging."
-                }
             )}
     ].
 
@@ -337,13 +317,10 @@ fields("authorization") ->
                     default => allow,
                     %% TODO: make sources a reference link
                     desc =>
-                        ""
-                        "\n"
                         "Default access control action if the user or client matches no ACL rules,\n"
                         "or if no such user or client is found by the configurable authorization\n"
                         "sources such as built_in_database, an HTTP API, or a query against PostgreSQL.\n"
-                        "Find more details in 'authorization.sources' config.\n"
+                        "Find more details in 'authorization.sources' config."
-                        ""
                 }
             )},
         {"deny_action",
@@ -667,11 +644,7 @@ fields("flapping_detect") ->
                 #{
                     default => false,
                     desc =>
-                        "Enable flapping connection detection feature.<br/>\n"
+                        "Enable flapping connection detection feature."
-                        "This config controls the allowed maximum number of `CONNECT` packets received\n"
-                        "from the same clientid in a time frame defined by `window_time`.\n"
-                        "After the limit is reached, successive `CONNECT` requests are forbidden\n"
-                        "(banned) until the end of the time period defined by `ban_time`."
                 }
             )},
         {"max_count",
@@ -858,7 +831,7 @@ fields("mqtt_tcp_listener") ->
         {"tcp",
             sc(
                 ref("tcp_opts"),
-                #{desc => "TCP listener options"}
+                #{}
             )}
     ] ++ mqtt_listener();
 fields("mqtt_ssl_listener") ->
@@ -1268,7 +1241,7 @@ fields("broker") ->
         {"perf",
             sc(
                 ref("broker_perf"),
-                #{desc => "Broker performance tuning parameters"}
+                #{}
             )}
     ];
 fields("broker_perf") ->
@@ -1299,17 +1272,7 @@ fields("sys_topics") ->
         {"sys_event_messages",
             sc(
                 ref("event_names"),
-                #{
+                #{}
-                    desc =>
-                        "Whether to enable Client lifecycle event messages publish.<br/>\n"
-                        "The following options are not only for enabling MQTT client event messages\n"
-                        "publish but also for Gateway clients. However, these kinds of clients type\n"
-                        "are distinguished by the Topic prefix:\n"
-                        "- For the MQTT client, its event topic format is:<br/>\n"
-                        "  <code>$SYS/broker/<node>/clients/<clientid>/<event></code><br/>\n"
-                        "- For the Gateway client, it is\n"
-                        "  <code>$SYS/broker/<node>/gateway/<gateway-name>/clients/<clientid>/<event></code>"
-                }
             )}
     ];
 fields("event_names") ->
@@ -1352,31 +1315,17 @@ fields("sysmon") ->
         {"vm",
             sc(
                 ref("sysmon_vm"),
-                #{
+                #{}
-                    desc =>
-                        "This part of the configuration is responsible for collecting\n"
-                        " BEAM VM events, such as long garbage collection, traffic congestion in the inter-broker\n"
-                        " communication, etc."
-                }
             )},
         {"os",
             sc(
                 ref("sysmon_os"),
-                #{
+                #{}
-                    desc =>
-                        "This part of the configuration is responsible for monitoring\n"
-                        " the host OS health, such as free memory, disk space, CPU load, etc."
-                }
             )},
         {"top",
             sc(
                 ref("sysmon_top"),
-                #{
+                #{}
-                    desc =>
-                        "This part of the configuration is responsible for monitoring\n"
-                        " the Erlang processes in the VM. This information can be sent to an external\n"
-                        " PostgreSQL database. This feature is inactive unless the PostgreSQL sink is configured."
-                }
             )}
     ];
 fields("sysmon_vm") ->
@@ -1747,6 +1696,144 @@ base_listener() ->
             sc(map("ratelimit's type", emqx_limiter_schema:bucket_name()), #{default => #{}})}
     ].
 
+desc("persistent_session_store") ->
+    "Settings for message persistence.";
+desc("stats") ->
+    "Enable/disable statistic data collection.\n"
+    "Statistic data such as message receive/send count/rate etc. "
+    "It provides insights of system performance and helps to diagnose issues. "
+    "You can find statistic data from the dashboard, or from the '/stats' API.";
+desc("authorization") ->
+    "Settings for client authorization.";
+desc("mqtt") ->
+    "Global MQTT configuration.<br>\n"
+    "The configs here work as default values which can be overridden\n"
+    "in <code>zone</code> configs";
+desc("cache") ->
+    "Settings for the authorization cache.";
+desc("zone") ->
+    "A `Zone` defines a set of configuration items (such as the maximum number of connections)"
+    " that can be shared between multiple listeners.\n\n"
+    "`Listener` can refer to a `Zone` through the configuration item"
+    " <code>listener.<Protocol>.<Listener Name>.zone</code>.\n\n"
+    "The configs defined in the zones will override the global configs with the same key.\n\n"
+    "For example, given the following config:\n"
+    "```\n"
+    "a {\n"
+    "    b: 1, c: 1\n"
+    "}\n"
+    "zone.my_zone {\n"
+    "  a {\n"
+    "    b:2\n"
+    "  }\n"
+    "}\n"
+    "```\n\n"
+    "The global config `a` is overridden by the configs `a` inside the zone `my_zone`.\n\n"
+    "If there is a listener uses the zone `my_zone`, the value of config `a` will be: "
+    "`{b:2, c: 1}`.\n"
+    "Note that although the default value of `a.c` is `0`, the global value is used,"
+    " i.e. configs in the zone have no default values. To override `a.c` one must configure"
+    " it explicitly in the zone.\n\n"
+    "All the global configs that can be overridden in zones are:\n"
+    " - `stats.*`\n"
+    " - `mqtt.*`\n"
+    " - `authorization.*`\n"
+    " - `flapping_detect.*`\n"
+    " - `force_shutdown.*`\n"
+    " - `conn_congestion.*`\n"
+    " - `force_gc.*`\n\n";
+desc("rate_limit") ->
+    "Rate limit settings.";
+desc("flapping_detect") ->
+    "This config controls the allowed maximum number of `CONNECT` packets received\n"
+    "from the same clientid in a time frame defined by `window_time`.\n"
+    "After the limit is reached, successive `CONNECT` requests are forbidden\n"
+    "(banned) until the end of the time period defined by `ban_time`.";
+desc("force_shutdown") ->
+    "When the process message queue length, or the memory bytes\n"
+    "reaches a certain value, the process is forced to close.\n\n"
+    "Note: \"message queue\" here refers to the \"message mailbox\"\n"
+    "of the Erlang process, not the `mqueue` of QoS 1 and QoS 2.";
+desc("overload_protection") ->
+    "Overload protection mechanism monitors the load of the system and temporarily\n"
+    "disables some features (such as accepting new connections) when the load is high.";
+desc("conn_congestion") ->
+    "Settings for `conn_congestion` alarm.\n\n"
+    "Sometimes the MQTT connection (usually an MQTT subscriber) may\n"
+    "get \"congested\", because there are too many packets to sent.\n"
+    "The socket tries to buffer the packets until the buffer is\n"
+    "full. If more packets arrive after that, the packets will be\n"
+    "\"pending\" in the queue and we consider the connection\n"
+    "congested.\n\n"
+    "Note: `sndbuf` can be set to larger value if the\n"
+    "alarm is triggered too often.\n"
+    "The name of the alarm is of format `conn_congestion/<ClientID>/<Username>`,\n"
+    "where the `<ClientID>` is the client ID of the congested MQTT connection,\n"
+    "and `<Username>` is the username or `unknown_user`.";
+desc("force_gc") ->
+    "Force garbage collection in MQTT connection process after\n"
+    " they process certain number of messages or bytes of data.";
+desc("listeners") ->
+    "MQTT listeners identified by their protocol type and assigned names";
+desc("mqtt_tcp_listener") ->
+    "Settings for the MQTT over TCP listener.";
+desc("mqtt_ssl_listener") ->
+    "Settings for the MQTT over SSL listener.";
+desc("mqtt_ws_listener") ->
+    "Settings for the MQTT over WebSocket listener.";
+desc("mqtt_wss_listener") ->
+    "Settings for the MQTT over WebSocket/SSL listener.";
+desc("mqtt_quic_listener") ->
+    "Settings for the MQTT over QUIC listener.";
+desc("ws_opts") ->
+    "WebSocket listener options.";
+desc("tcp_opts") ->
+    "TCP listener options.";
+desc("listener_ssl_opts") ->
+    "Socket options for SSL connections.";
+desc("listener_wss_opts") ->
+    "Socket options for WebSocket/SSL connections.";
+desc(ssl_client_opts) ->
+    "Socket options for SSL clients.";
+desc("deflate_opts") ->
+    "Compression options.";
+desc("broker") ->
+    "Message broker options.";
+desc("broker_perf") ->
+    "Broker performance tuning parameters.";
+desc("sys_topics") ->
+    "The EMQX Broker periodically publishes its own status, message statistics,\n"
+    "client online and offline events to the system topic starting with `$SYS/`.\n\n"
+    "The following options control the behavior of `$SYS` topics.";
+desc("event_names") ->
+    "Enable or disable client lifecycle event publishing.\n\n"
+    "The following options affect MQTT clients as well as\n"
+    "gateway clients. The types of the clients\n"
+    "are distinguished by the topic prefix:\n\n"
+    "- For the MQTT clients, the format is:\n"
+    "`$SYS/broker/<node>/clients/<clientid>/<event>`\n"
+    "- For the Gateway clients, it is\n"
+    "`$SYS/broker/<node>/gateway/<gateway-name>/clients/<clientid>/<event>`\n";
+desc("sysmon") ->
+    "Features related to system monitoring and introspection.";
+desc("sysmon_vm") ->
+    "This part of the configuration is responsible for collecting\n"
+    " BEAM VM events, such as long garbage collection, traffic congestion in the inter-broker\n"
+    " communication, etc.";
+desc("sysmon_os") ->
+    "This part of the configuration is responsible for monitoring\n"
+    " the host OS health, such as free memory, disk space, CPU load, etc.";
+desc("sysmon_top") ->
+    "This part of the configuration is responsible for monitoring\n"
+    " the Erlang processes in the VM. This information can be sent to an external\n"
+    " PostgreSQL database. This feature is inactive unless the PostgreSQL sink is configured.";
+desc("alarm") ->
+    "Settings for the alarms.";
+desc("trace") ->
+    "Real-time filtering logs for the ClientID or Topic or IP for debugging.";
+desc(_) ->
+    undefined.
+
 %% utils
 -spec conf_get(string() | [string()], hocon:config()) -> term().
 conf_get(Key, Conf) ->

apps/emqx_conf/src/emqx_conf_schema.erl

@@ -36,7 +36,7 @@
                 file/0,
                 cipher/0]).
 
--export([namespace/0, roots/0, fields/1, translations/0, translation/1, validations/0]).
+-export([namespace/0, roots/0, fields/1, translations/0, translation/1, validations/0, desc/1]).
 -export([conf_get/2, conf_get/3, keys/2, filter/1]).
 
 %% Static apps which merge their configs into the merged emqx.conf
@@ -73,34 +73,23 @@ roots() ->
     emqx_schema_high_prio_roots() ++
     [ {"node",
        sc(ref("node"),
-          #{ desc => "Node name, cookie, config & data directories "
+          #{ translate_to => ["emqx"]
-                     "and the Erlang virtual machine (BEAM) boot parameters."
-           , translate_to => ["emqx"]
            })}
     , {"cluster",
        sc(ref("cluster"),
-          #{ desc => "EMQX nodes can form a cluster to scale up the total capacity.<br>"
+          #{  translate_to => ["ekka"]
-                     "Here holds the configs to instruct how individual nodes "
-                     "can discover each other."
-            , translate_to => ["ekka"]
            })}
     , {"log",
        sc(ref("log"),
-          #{ desc => "Configure logging backends (to console or to file), "
+          #{ translate_to => ["kernel"]
-                     "and logging level for each logger backend."
-           , translate_to => ["kernel"]
            })}
     , {"rpc",
        sc(ref("rpc"),
-          #{ desc => "EMQX uses a library called <code>gen_rpc</code> for "
+          #{ translate_to => ["gen_rpc"]
-                     "inter-broker communication.<br/>Most of the time the default config "
-                     "should work, but in case you need to do performance "
-                     "fine-turning or experiment a bit, this is where to look."
-           , translate_to => ["gen_rpc"]
            })}
     , {"db",
        sc(ref("db"),
-          #{ desc => "Settings of the embedded database."
+          #{
            })}
     ] ++
     emqx_schema:roots(medium) ++
@@ -148,24 +137,23 @@ fields("cluster") ->
           })}
     , {"static",
        sc(ref(cluster_static),
-          #{ desc => "Service discovery via static nodes. The new node joins the cluster by
+          #{
- connecting to one of the bootstrap nodes."
            })}
     , {"mcast",
        sc(ref(cluster_mcast),
-          #{ desc => "Service discovery via UDP multicast."
+          #{
            })}
     , {"dns",
        sc(ref(cluster_dns),
-          #{ desc => "Service discovery via DNS SRV records."
+          #{
            })}
     , {"etcd",
        sc(ref(cluster_etcd),
-          #{ desc => "Service discovery using 'etcd' service."
+          #{
            })}
     , {"k8s",
        sc(ref(cluster_k8s),
-          #{ desc => "Service discovery via Kubernetes API server."
+          #{
            })}
     ];
 
@@ -420,9 +408,7 @@ a crash dump"
          )}
     , {"cluster_call",
       sc(ref("cluster_call"),
-        #{ desc => "Options for the 'cluster call' feature that allows to execute a callback
+        #{ 'readOnly' => true
- on all nodes in the cluster."
-         , 'readOnly' => true
          }
         )}
     ];
@@ -742,6 +728,62 @@ fields("authorization") ->
     emqx_schema:fields("authorization") ++
     emqx_authz_schema:fields("authorization").
 
+
+desc("cluster") ->
+    "EMQX nodes can form a cluster to scale up the total capacity.<br>"
+    "Here holds the configs to instruct how individual nodes "
+    "can discover each other.";
+desc(cluster_static) ->
+     "Service discovery via static nodes. The new node joins the cluster by "
+     "connecting to one of the bootstrap nodes.";
+desc(cluster_mcast) ->
+    "Service discovery via UDP multicast.";
+desc(cluster_dns) ->
+     "Service discovery via DNS SRV records.";
+desc(cluster_etcd) ->
+    "Service discovery using 'etcd' service.";
+desc(cluster_k8s) ->
+    "Service discovery via Kubernetes API server.";
+desc("node") ->
+    "Node name, cookie, config & data directories "
+    "and the Erlang virtual machine (BEAM) boot parameters.";
+desc("db") ->
+    "Settings for the embedded database.";
+desc("cluster_call") ->
+    "Options for the 'cluster call' feature that allows to execute a callback "
+    "on all nodes in the cluster.";
+desc("rpc") ->
+    "EMQX uses a library called <code>gen_rpc</code> for "
+    "inter-broker communication.<br/>Most of the time the default config "
+    "should work, but in case you need to do performance "
+    "fine-turning or experiment a bit, this is where to look.";
+desc("log") ->
+    "EMQX logging supports multiple sinks for the log events."
+    " Each sink is represented by a _log handler_, which can be configured independently.";
+desc("console_handler") ->
+    "Log handler that prints log events to the EMQX console.";
+desc("log_file_handler") ->
+    "Log handler that prints log events to files.";
+desc("log_rotation") ->
+    "By default, the logs are stored in `./log` directory (for installation from zip file)"
+    " or in `/var/log/emqx` (for binary installation).<br/>"
+    "This section of the configuration controls the number of files kept for each log handler.";
+desc("log_overload_kill") ->
+    "Log overload kill feature an overload protection that activates when"
+    " the log handlers use too much memory or have too many buffered log messages.<br/>"
+    "When the overload is detected, the log handler is terminated and restarted after a"
+    " cooldown period.";
+desc("log_burst_limit") ->
+    "Large bursts of log events produced in a short time can potentially cause problems, such as:\n"
+     " - Log files grow very large\n"
+     " - Log files are rotated too quickly, and useful information gets overwritten\n"
+     " - Overall performance impact on the system\n\n"
+    "Log burst limit feature can temporarily disable logging to avoid these issues.";
+desc("authorization") ->
+    "Settings that control client authorization.";
+desc(_) ->
+    undefined.
+
 translations() -> ["ekka", "kernel", "emqx", "gen_rpc"].
 
 translation("ekka") ->

apps/emqx_prometheus/src/emqx_prometheus_schema.erl

@@ -21,7 +21,9 @@
 
 -export([ namespace/0
         , roots/0
-        , fields/1]).
+        , fields/1
+        , desc/1
+        ]).
 
 namespace() -> "prometheus".
 
@@ -45,4 +47,9 @@ fields("prometheus") ->
                    })}
     ].
 
+desc("prometheus") ->
+    "Settings for reporting metrics to Prometheus pushgateway.";
+desc(_) ->
+    undefined.
+
 sc(Type, Meta) -> hoconsc:mk(Type, Meta).

build

@@ -70,7 +70,7 @@ make_doc() {
     local libs_dir1 libs_dir2
     libs_dir1="$("$FIND" "_build/default/lib/" -maxdepth 2 -name ebin -type d)"
     libs_dir2="$("$FIND" "_build/$PROFILE/lib/" -maxdepth 2 -name ebin -type d)"
-    libs_dir3="$("$FIND" "_build/$PROFILE/checkouts/" -maxdepth 2 -name ebin -type d)"
+    libs_dir3="$("$FIND" "_build/$PROFILE/checkouts/" -maxdepth 2 -name ebin -type d || true)"
     case $PROFILE in
         emqx-enterprise)
             SCHEMA_MODULE='emqx_enterprise_conf_schema'