yuanbiao
/
emqx
1
0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

docs(schema): Add descriptions of the records

This commit is contained in:
ieQu1 2022-03-28 21:51:06 +02:00
parent aecfa77985
commit fff6bffa0c
5 changed files with 234 additions and 98 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

6
apps/emqx/etc/emqx.conf
View File

@ -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:

219
apps/emqx/src/emqx_schema.erl
View File

@ -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"
"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.<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) ->

94
apps/emqx_conf/src/emqx_conf_schema.erl
View File

@ -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.<br>"
"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 <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."
, 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,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
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.<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") ->

9
apps/emqx_prometheus/src/emqx_prometheus_schema.erl
View File

@ -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).

2
build
View File

@ -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'