From fff6bffa0cbb65ab496c9f61a51c76bf99d326a1 Mon Sep 17 00:00:00 2001 From: ieQu1 <99872536+ieQu1@users.noreply.github.com> Date: Mon, 28 Mar 2022 21:51:06 +0200 Subject: [PATCH] docs(schema): Add descriptions of the records --- apps/emqx/etc/emqx.conf | 6 +- apps/emqx/src/emqx_schema.erl | 219 ++++++++++++------ apps/emqx_conf/src/emqx_conf_schema.erl | 96 +++++--- .../src/emqx_prometheus_schema.erl | 9 +- build | 2 +- 5 files changed, 234 insertions(+), 98 deletions(-) diff --git a/apps/emqx/etc/emqx.conf b/apps/emqx/etc/emqx.conf index df6eea362..63ec0f664 100644 --- a/apps/emqx/etc/emqx.conf +++ b/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: diff --git a/apps/emqx/src/emqx_schema.erl b/apps/emqx/src/emqx_schema.erl index dec890f45..862bc3e76 100644 --- a/apps/emqx/src/emqx_schema.erl +++ b/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.
\n" - "The configs here work as default values which can be overridden\n" - "in zone 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.
\n" - "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`." + "Enable flapping connection detection feature." } )}, {"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.
\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:
\n" - " $SYS/broker//clients//
\n" - "- For the Gateway client, it is\n" - " $SYS/broker//gateway//clients//" - } + #{} )} ]; 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.
\n" + "The configs here work as default values which can be overridden\n" + "in zone 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" + " listener...zone.\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//`,\n" + "where the `` is the client ID of the congested MQTT connection,\n" + "and `` 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//clients//`\n" + "- For the Gateway clients, it is\n" + "`$SYS/broker//gateway//clients//`\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) -> diff --git a/apps/emqx_conf/src/emqx_conf_schema.erl b/apps/emqx_conf/src/emqx_conf_schema.erl index 6830eda00..4b307526c 100644 --- a/apps/emqx_conf/src/emqx_conf_schema.erl +++ b/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 " - "and the Erlang virtual machine (BEAM) boot parameters." - , translate_to => ["emqx"] + #{ translate_to => ["emqx"] })} , {"cluster", sc(ref("cluster"), - #{ desc => "EMQX nodes can form a cluster to scale up the total capacity.
" - "Here holds the configs to instruct how individual nodes " - "can discover each other." - , translate_to => ["ekka"] + #{ translate_to => ["ekka"] })} , {"log", sc(ref("log"), - #{ desc => "Configure logging backends (to console or to file), " - "and logging level for each logger backend." - , translate_to => ["kernel"] + #{ translate_to => ["kernel"] })} , {"rpc", sc(ref("rpc"), - #{ desc => "EMQX uses a library called gen_rpc for " - "inter-broker communication.
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"] + #{ 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,10 +408,8 @@ a crash dump" )} , {"cluster_call", sc(ref("cluster_call"), - #{ desc => "Options for the 'cluster call' feature that allows to execute a callback - on all nodes in the cluster." - , 'readOnly' => true - } + #{ '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.
" + "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 gen_rpc for " + "inter-broker communication.
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).
" + "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.
" + "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") -> diff --git a/apps/emqx_prometheus/src/emqx_prometheus_schema.erl b/apps/emqx_prometheus/src/emqx_prometheus_schema.erl index 5434ef1f1..6e6ebd4b9 100644 --- a/apps/emqx_prometheus/src/emqx_prometheus_schema.erl +++ b/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). diff --git a/build b/build index f231b3fee..e84609b23 100755 --- a/build +++ b/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'