From aecfa7798516b8241bdf9a6ad14c9cfc3cdf8bde Mon Sep 17 00:00:00 2001 From: ieQu1 <99872536+ieQu1@users.noreply.github.com> Date: Mon, 28 Mar 2022 21:50:49 +0200 Subject: [PATCH 1/5] chore(hocon): Bump version --- apps/emqx/rebar.config | 2 +- apps/emqx_prometheus/rebar.config | 2 +- build | 3 ++- mix.exs | 2 +- rebar.config | 2 +- 5 files changed, 6 insertions(+), 5 deletions(-) diff --git a/apps/emqx/rebar.config b/apps/emqx/rebar.config index aea67376c..ef91981c5 100644 --- a/apps/emqx/rebar.config +++ b/apps/emqx/rebar.config @@ -30,7 +30,7 @@ {esockd, {git, "https://github.com/emqx/esockd", {tag, "5.9.1"}}}, {ekka, {git, "https://github.com/emqx/ekka", {tag, "0.12.3"}}}, {gen_rpc, {git, "https://github.com/emqx/gen_rpc", {tag, "2.8.1"}}}, - {hocon, {git, "https://github.com/emqx/hocon.git", {tag, "0.26.4"}}}, + {hocon, {git, "https://github.com/emqx/hocon.git", {tag, "0.26.6"}}}, {pbkdf2, {git, "https://github.com/emqx/erlang-pbkdf2.git", {tag, "2.0.4"}}}, {recon, {git, "https://github.com/ferd/recon", {tag, "2.5.1"}}}, {snabbkaffe, {git, "https://github.com/kafka4beam/snabbkaffe.git", {tag, "0.18.0"}}} diff --git a/apps/emqx_prometheus/rebar.config b/apps/emqx_prometheus/rebar.config index 42212df9f..b05091515 100644 --- a/apps/emqx_prometheus/rebar.config +++ b/apps/emqx_prometheus/rebar.config @@ -4,7 +4,7 @@ [ {emqx, {path, "../emqx"}}, %% FIXME: tag this as v3.1.3 {prometheus, {git, "https://github.com/deadtrickster/prometheus.erl", {tag, "v4.8.1"}}}, - {hocon, {git, "https://github.com/emqx/hocon.git", {tag, "0.26.4"}}} + {hocon, {git, "https://github.com/emqx/hocon.git", {tag, "0.26.6"}}} ]}. {edoc_opts, [{preprocess, true}]}. diff --git a/build b/build index 8fe1e1fd7..f231b3fee 100755 --- a/build +++ b/build @@ -70,6 +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)" case $PROFILE in emqx-enterprise) SCHEMA_MODULE='emqx_enterprise_conf_schema' @@ -79,7 +80,7 @@ make_doc() { ;; esac # shellcheck disable=SC2086 - erl -noshell -pa $libs_dir1 $libs_dir2 -eval \ + erl -noshell -pa $libs_dir1 $libs_dir2 $libs_dir3 -eval \ "Dir = filename:join(['_build', '${PROFILE}', lib, emqx_dashboard, priv, www, static]), \ ok = emqx_conf:dump_schema(Dir, $SCHEMA_MODULE), \ halt(0)." diff --git a/mix.exs b/mix.exs index d7d05e979..d87a4366b 100644 --- a/mix.exs +++ b/mix.exs @@ -68,7 +68,7 @@ defmodule EMQXUmbrella.MixProject do # in conflict by emqtt and hocon {:getopt, "1.0.2", override: true}, {:snabbkaffe, github: "kafka4beam/snabbkaffe", tag: "0.18.0", override: true}, - {:hocon, github: "emqx/hocon", tag: "0.26.4", override: true}, + {:hocon, github: "emqx/hocon", tag: "0.26.6", override: true}, {:emqx_http_lib, github: "emqx/emqx_http_lib", tag: "0.4.1", override: true}, {:esasl, github: "emqx/esasl", tag: "0.2.0"}, {:jose, github: "potatosalad/erlang-jose", tag: "1.11.2"}, diff --git a/rebar.config b/rebar.config index 2e3544309..e62810ece 100644 --- a/rebar.config +++ b/rebar.config @@ -66,7 +66,7 @@ , {system_monitor, {git, "https://github.com/ieQu1/system_monitor", {tag, "3.0.2"}}} , {getopt, "1.0.2"} , {snabbkaffe, {git, "https://github.com/kafka4beam/snabbkaffe.git", {tag, "0.18.0"}}} - , {hocon, {git, "https://github.com/emqx/hocon.git", {tag, "0.26.4"}}} + , {hocon, {git, "https://github.com/emqx/hocon.git", {tag, "0.26.6"}}} , {emqx_http_lib, {git, "https://github.com/emqx/emqx_http_lib.git", {tag, "0.4.1"}}} , {esasl, {git, "https://github.com/emqx/esasl", {tag, "0.2.0"}}} , {jose, {git, "https://github.com/potatosalad/erlang-jose", {tag, "1.11.2"}}} 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 2/5] 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' From 410b69d61672590e569b920a8eee9b01eb7670ee Mon Sep 17 00:00:00 2001 From: ieQu1 <99872536+ieQu1@users.noreply.github.com> Date: Tue, 29 Mar 2022 14:04:00 +0200 Subject: [PATCH 3/5] docs(schema): Document records for gateway --- apps/emqx_gateway/src/emqx_gateway_schema.erl | 58 ++++++++++++++++++- 1 file changed, 56 insertions(+), 2 deletions(-) diff --git a/apps/emqx_gateway/src/emqx_gateway_schema.erl b/apps/emqx_gateway/src/emqx_gateway_schema.erl index 9b7f80d19..f4cd97637 100644 --- a/apps/emqx_gateway/src/emqx_gateway_schema.erl +++ b/apps/emqx_gateway/src/emqx_gateway_schema.erl @@ -48,7 +48,7 @@ ]). -elvis([{elvis_style, dont_repeat_yourself, disable}]). --export([namespace/0, roots/0 , fields/1]). +-export([namespace/0, roots/0 , fields/1, desc/1]). -export([proxy_protocol_opts/0]). @@ -432,6 +432,60 @@ fields(dtls_opts) -> , ciphers => dtls_all_available }, false). +desc(gateway) -> + "EMQX Gateway configuration root."; +desc(stomp) -> + "The STOMP protocol gateway provides EMQX with the ability to access STOMP\n" + "(Simple (or Streaming) Text Orientated Messaging Protocol) protocol."; +desc(stomp_frame) -> + "Size limits for the STOMP frames."; +desc(mqttsn) -> + "The MQTT-SN (MQTT for Sensor Networks) protocol gateway."; +desc(mqttsn_predefined) -> + "The pre-defined topic name corresponding to the pre-defined topic\n" + "ID of N.\n\n" + "Note: the pre-defined topic ID of 0 is reserved."; +desc(coap) -> + "The CoAP protocol gateway provides EMQX with the access capability of the CoAP protocol.\n" + "It allows publishing, subscribing, and receiving messages to EMQX in accordance\n" + "with a certain defined CoAP message format."; +desc(lwm2m) -> + "The LwM2M protocol gateway."; +desc(exproto) -> + "Settings for EMQX extension protocol (exproto)."; +desc(exproto_grpc_server) -> + "Settings for the exproto gRPC server."; +desc(exproto_grpc_handler) -> + "Settings for the exproto gRPC connection handler."; +desc(ssl_server_opts) -> + "SSL configuration for the server."; +desc(clientinfo_override) -> + "ClientInfo override."; +desc(lwm2m_translators) -> + "MQTT topics that correspond to LwM2M events."; +desc(translator) -> + "MQTT topic that corresponds to a particular type of event."; +desc(udp_listeners) -> + "Settings for the UDP listeners."; +desc(tcp_listeners) -> + "Settings for the TCP listeners."; +desc(udp_tcp_listeners) -> + "Settings for the listeners."; +desc(tcp_listener) -> + "Settings for the TCP listener."; +desc(ssl_listener) -> + "Settings for the SSL listener."; +desc(udp_listener) -> + "Settings for the UDP listener."; +desc(dtls_listener) -> + "Settings for the DTLS listener."; +desc(udp_opts) -> + "Settings for the UDP sockets."; +desc(dtls_opts) -> + "Settings for the DTLS protocol."; +desc(_) -> + undefined. + authentication_schema() -> sc(emqx_authn_schema:authenticator_type(), #{ required => {false, recursively} @@ -471,7 +525,7 @@ It has two purposes: })} , {clientinfo_override, sc(ref(clientinfo_override), - #{ desc => "" + #{ desc => "ClientInfo override" })} , {?EMQX_AUTHENTICATION_CONFIG_ROOT_NAME_ATOM, authentication_schema()} ]. From 465e0e418c7dce625aaa0a21e877d7b167ed11b0 Mon Sep 17 00:00:00 2001 From: ieQu1 <99872536+ieQu1@users.noreply.github.com> Date: Tue, 29 Mar 2022 14:04:22 +0200 Subject: [PATCH 4/5] docs(schema): Document rate_limit fields --- apps/emqx/etc/emqx.conf | 2 +- apps/emqx/src/emqx_schema.erl | 17 ++++++++++++++--- 2 files changed, 15 insertions(+), 4 deletions(-) diff --git a/apps/emqx/etc/emqx.conf b/apps/emqx/etc/emqx.conf index 63ec0f664..a272a110f 100644 --- a/apps/emqx/etc/emqx.conf +++ b/apps/emqx/etc/emqx.conf @@ -936,7 +936,7 @@ rate_limit { ## max_conn_rate: 1000 max_conn_rate = 1000 - ## Message limit for the a external MQTT connection. + ## Message limit for the external MQTT connections. ## ## @doc rate_limit.conn_messages_in ## ValueType: String | infinity diff --git a/apps/emqx/src/emqx_schema.erl b/apps/emqx/src/emqx_schema.erl index 862bc3e76..2879d251d 100644 --- a/apps/emqx/src/emqx_schema.erl +++ b/apps/emqx/src/emqx_schema.erl @@ -623,17 +623,28 @@ fields("rate_limit") -> {"max_conn_rate", sc( hoconsc:union([infinity, integer()]), - #{default => 1000} + #{ + default => 1000, + desc => "Maximum connections per second." + } )}, {"conn_messages_in", sc( hoconsc:union([infinity, comma_separated_list()]), - #{default => infinity} + #{ + default => infinity, + desc => "Message limit for the external MQTT connections." + } )}, {"conn_bytes_in", sc( hoconsc:union([infinity, comma_separated_list()]), - #{default => infinity} + #{ + default => infinity, + desc => + "Limit the rate of receiving packets for a MQTT connection.\n" + "The rate is counted by bytes of packets per second." + } )} ]; fields("flapping_detect") -> From fcc99b484f9e425ab29e0db39cfeafc2a385cfd9 Mon Sep 17 00:00:00 2001 From: Dmitrii <99872536+ieQu1@users.noreply.github.com> Date: Wed, 30 Mar 2022 10:12:04 +0200 Subject: [PATCH 5/5] docs(schema): Apply suggestions from code review Co-authored-by: Thales Macedo Garitezi --- apps/emqx/etc/emqx.conf | 2 +- apps/emqx/src/emqx_schema.erl | 4 ++-- apps/emqx_conf/src/emqx_conf_schema.erl | 4 ++-- 3 files changed, 5 insertions(+), 5 deletions(-) diff --git a/apps/emqx/etc/emqx.conf b/apps/emqx/etc/emqx.conf index a272a110f..a84d35e59 100644 --- a/apps/emqx/etc/emqx.conf +++ b/apps/emqx/etc/emqx.conf @@ -894,7 +894,7 @@ 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 be sent. ## The socket tries to buffer the packets until the buffer is ## full. If more packets come after that, the packets will be ## "pending" in a queue and we consider the connection is diff --git a/apps/emqx/src/emqx_schema.erl b/apps/emqx/src/emqx_schema.erl index 2879d251d..b2c51b853 100644 --- a/apps/emqx/src/emqx_schema.erl +++ b/apps/emqx/src/emqx_schema.erl @@ -1740,7 +1740,7 @@ desc("zone") -> "}\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: " + "If there is a listener using 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" @@ -1771,7 +1771,7 @@ desc("overload_protection") -> 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" + "get \"congested\", because there are too many packets to be 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" diff --git a/apps/emqx_conf/src/emqx_conf_schema.erl b/apps/emqx_conf/src/emqx_conf_schema.erl index 4b307526c..3849e296b 100644 --- a/apps/emqx_conf/src/emqx_conf_schema.erl +++ b/apps/emqx_conf/src/emqx_conf_schema.erl @@ -756,7 +756,7 @@ 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."; + "fine-tuning 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."; @@ -769,7 +769,7 @@ desc("log_rotation") -> " 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" + "Log overload kill features 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.";