From e0d05a02ff970a92c7a0bd6b8dc412b5854ccf5d Mon Sep 17 00:00:00 2001
From: "Zaiming (Stone) Shi" <zmstone@gmail.com>
Date: Thu, 22 Jun 2023 17:08:54 +0200
Subject: [PATCH] refactor: refine examples

Also turns off vm_dist_collector metrics collector by default
---
 .../src/emqx_prometheus_schema.erl            | 14 ++---
 rel/config/examples/README.md                 | 18 +++++--
 rel/config/examples/alarm.conf.example        |  6 ---
 .../examples/cluster-with-dns.conf.example    | 11 +---
 .../cluster-with-etcd-ssl.conf.example        | 54 ++-----------------
 .../examples/cluster-with-etcd.conf.example   | 12 +----
 .../examples/cluster-with-k8s.conf.example    | 11 +---
 .../examples/cluster-with-manual.conf.example | 11 +---
 .../examples/cluster-with-static.conf.example | 11 +---
 .../examples/conn_congestion.conf.example     |  4 --
 .../examples/dashboard-with-http.conf.example |  8 +--
 .../dashboard-with-https.conf.example         |  8 +--
 rel/config/examples/exhook.conf.example       |  4 +-
 ..._transfer-with-local-exporter.conf.example | 10 +---
 ...ile_transfer-with-s3-exporter.conf.example |  9 +---
 .../examples/flapping_detect.conf.example     | 10 ++--
 rel/config/examples/force_gc.conf.example     | 10 +---
 .../examples/force_shutdown.conf.example      |  8 +--
 .../examples/gateway.exproto.conf.example     |  6 ---
 .../examples/gateway.lwm2m.conf.example       |  6 ---
 .../examples/gateway.mqttsn.conf.example      |  6 ---
 .../examples/gateway.stomp.conf.example       |  6 ---
 rel/config/examples/license.conf.example      | 10 +---
 .../examples/listeners.quic.conf.example      | 15 ++----
 .../examples/listeners.ssl.conf.example       | 22 +++-----
 .../examples/listeners.tcp.conf.example       | 11 +---
 rel/config/examples/listeners.ws.conf.example | 14 +----
 .../examples/listeners.wss.conf.example       | 18 ++-----
 rel/config/examples/log.console.conf.example  |  8 +--
 rel/config/examples/log.file.conf.example     | 13 ++---
 rel/config/examples/mqtt.conf.example         | 11 ++--
 rel/config/examples/node.conf.example         | 34 ++++++------
 rel/config/examples/plugin.conf.example       |  9 +---
 .../prometheus-pushgateway.conf.example       | 28 ++++++++++
 rel/config/examples/prometheus.conf.example   | 32 +++--------
 .../examples/psk_authentication.conf.example  |  8 +--
 rel/config/examples/retainer.conf.example     | 16 ++----
 rel/config/examples/sys_topics.conf.example   |  5 --
 rel/config/examples/sysmon.os.conf.example    | 14 ++---
 rel/config/examples/sysmon.vm.conf.example    |  8 +--
 rel/i18n/emqx_conf_schema.hocon               |  6 +--
 rel/i18n/emqx_prometheus_schema.hocon         |  6 ++-
 rel/i18n/emqx_retainer_schema.hocon           |  6 +--
 43 files changed, 144 insertions(+), 393 deletions(-)
 create mode 100644 rel/config/examples/prometheus-pushgateway.conf.example

diff --git a/apps/emqx_prometheus/src/emqx_prometheus_schema.erl b/apps/emqx_prometheus/src/emqx_prometheus_schema.erl
index d657e0772..82d951ab3 100644
--- a/apps/emqx_prometheus/src/emqx_prometheus_schema.erl
+++ b/apps/emqx_prometheus/src/emqx_prometheus_schema.erl
@@ -88,9 +88,9 @@ fields("prometheus") ->
             ?HOCON(
                 hoconsc:enum([enabled, disabled]),
                 #{
-                    default => enabled,
+                    default => disabled,
                     required => true,
-                    importance => ?IMPORTANCE_HIDDEN,
+                    importance => ?IMPORTANCE_LOW,
                     desc => ?DESC(vm_dist_collector)
                 }
             )},
@@ -100,7 +100,7 @@ fields("prometheus") ->
                 #{
                     default => enabled,
                     required => true,
-                    importance => ?IMPORTANCE_HIDDEN,
+                    importance => ?IMPORTANCE_LOW,
                     desc => ?DESC(mnesia_collector)
                 }
             )},
@@ -110,7 +110,7 @@ fields("prometheus") ->
                 #{
                     default => enabled,
                     required => true,
-                    importance => ?IMPORTANCE_HIDDEN,
+                    importance => ?IMPORTANCE_LOW,
                     desc => ?DESC(vm_statistics_collector)
                 }
             )},
@@ -120,7 +120,7 @@ fields("prometheus") ->
                 #{
                     default => enabled,
                     required => true,
-                    importance => ?IMPORTANCE_HIDDEN,
+                    importance => ?IMPORTANCE_LOW,
                     desc => ?DESC(vm_system_info_collector)
                 }
             )},
@@ -130,7 +130,7 @@ fields("prometheus") ->
                 #{
                     default => enabled,
                     required => true,
-                    importance => ?IMPORTANCE_HIDDEN,
+                    importance => ?IMPORTANCE_LOW,
                     desc => ?DESC(vm_memory_collector)
                 }
             )},
@@ -140,7 +140,7 @@ fields("prometheus") ->
                 #{
                     default => enabled,
                     required => true,
-                    importance => ?IMPORTANCE_HIDDEN,
+                    importance => ?IMPORTANCE_LOW,
                     desc => ?DESC(vm_msacc_collector)
                 }
             )}
diff --git a/rel/config/examples/README.md b/rel/config/examples/README.md
index 013939394..326b5c730 100644
--- a/rel/config/examples/README.md
+++ b/rel/config/examples/README.md
@@ -1,16 +1,24 @@
 # Examples
 
-Here are examples of how to configure features In EMQX,  most of them can be used directly by copy-paste content into the `emqx.conf` file, others may need to be slightly modified to use, for example, you should change the listener port or HTTP URL to what you actually used.
+Here are examples of how to configure EMQX.
+The main purpose of the examples are to serve as a reference for configuration layout and syntax, but not a guide to how to configure EMQX.
+For more information about EMQX configuration, please refer to EMQX documentation (links below).
 
-Although we have tried to show every configurable field in the example,
-you do not need to care about each one, since most of them already have default values and can be omitted in the configuration file.
+There are two ways to extend the configuration of EMQX:
 
-If you are confused about some fields, please refer to our documents, here are just some simple configuration examples with necessary descriptions.
+* By adding the configs to `emqx.conf` file.
+* By adding the configs to a new file and include it in `emqx.conf` file. For example, add `include "mylisteners.conf"` to `emqx.conf` file and add the listeners to `mylisteners.conf`.
 
+EMQX configuration consists of two parts: static configs and dynamic configs.
+
+* Configs loaded from `emqx.conf` (and included files) are static configs.
+* Configs added or updated from the dashboard or CLI are dynamic configs which are synced to all nodes in the cluster and stored in the data directory on each node.
+
+It is important to note that static configs are loaded when EMQX starts and overlays on top of the dynamic configs,
+to avoid confusion, it is highly recommended NOT to use the same config name for both static and dynamic configs.
 
 ## Documentation
 
 The EMQX documentation is available at [www.emqx.io/docs/en/latest/](https://www.emqx.io/docs/en/latest/).
 
 The EMQX Enterprise documentation is available at [docs.emqx.com/en/](https://docs.emqx.com/en/).
-
diff --git a/rel/config/examples/alarm.conf.example b/rel/config/examples/alarm.conf.example
index 537341ea2..e7f505b59 100644
--- a/rel/config/examples/alarm.conf.example
+++ b/rel/config/examples/alarm.conf.example
@@ -1,10 +1,4 @@
-##--------------------------------------------------------------------
 ## Alarm
-##
-## Configuring how to handle the alarms generated from sysmon.*.conf.example
-##--------------------------------------------------------------------
-## Note: This is an example of how to configure this feature
-##       you should copy and paste the below data into the emqx.conf for working
 
 alarm {
     ## The actions triggered when the alarm is activated
diff --git a/rel/config/examples/cluster-with-dns.conf.example b/rel/config/examples/cluster-with-dns.conf.example
index ae617a808..4cade3b54 100644
--- a/rel/config/examples/cluster-with-dns.conf.example
+++ b/rel/config/examples/cluster-with-dns.conf.example
@@ -1,10 +1,4 @@
-##--------------------------------------------------------------------
-## Cluster in service discovery via DNS SRV records mode
-##
-## Configs to instruct how individual nodes can discover each other
-##--------------------------------------------------------------------
-## Note: This is an example of how to configure this feature
-##       you should copy and paste the below data into the emqx.conf for working
+## Cluster discovery via DNS resolution
 
 cluster {
     ## Human-friendly name of the EMQX cluster.
@@ -13,9 +7,6 @@ cluster {
     ## Service discovery method for the cluster nodes
     discovery_strategy = dns
 
-    ## List of core nodes that the replicant will connect to
-    core_nodes = ["emqx1@192.168.0.1", "emqx2@192.168.0.2"]
-
     ## If true, the node will try to heal network partitions automatically
     autoheal = true
 
diff --git a/rel/config/examples/cluster-with-etcd-ssl.conf.example b/rel/config/examples/cluster-with-etcd-ssl.conf.example
index d3a31c7d0..9f9486bae 100644
--- a/rel/config/examples/cluster-with-etcd-ssl.conf.example
+++ b/rel/config/examples/cluster-with-etcd-ssl.conf.example
@@ -1,21 +1,12 @@
-##--------------------------------------------------------------------
-## Cluster in service discovery using 'etcd' service mode
-##
-## Configs to instruct how individual nodes can discover each other
-##--------------------------------------------------------------------
-## Note: This is an example of how to configure this feature
-##       you should copy and paste the below data into the emqx.conf for working
+## Cluster discovery using 'etcd'
+## connect to etcd over TLS
 
 cluster {
-    ## Human-friendly name of the EMQX cluster.
     name = emqxcl
 
     ## Service discovery method for the cluster nodes
     discovery_strategy = etcd
 
-    ## List of core nodes that the replicant will connect to
-    core_nodes = ["emqx1@192.168.0.1", "emqx2@192.168.0.2"]
-
     ## If true, the node will try to heal network partitions automatically
     autoheal = true
 
@@ -31,51 +22,16 @@ cluster {
 
       ssl_options {
           ## Trusted PEM format CA certificates bundle file
-          cacertfile = "data/certs/cacert.pem"
+          cacertfile = "${EMQX_ETC_DIR}/certs/etcd-cacert.pem"
 
           ## PEM format certificates chain file
-          certfile = "data/certs/cert.pem"
+          certfile = "${EMQX_ETC_DIR}/certs/etcd-client-cert.pem"
 
           ## PEM format private key file
-          keyfile = "data/certs/key.pem"
+          keyfile = "${EMQX_ETC_DIR}/certs/etcd-client-key.pem"
 
           ## Enable or disable peer verification
           verify = verify_none ## use verify_peer to enable
-
-          ## if `verify' is ebabled, whit true, the connection fails if the client does not have a certificate to send
-          fail_if_no_peer_cert = false
-
-          ## Enable TLS session reuse
-          reuse_sessions = true
-
-          ## Maximum number of non-self-issued intermediate certificates that can follow the peer certificate in a valid certification path
-          depth = 10
-
-          ## Which versions are to be supported
-          versions = [tlsv1.3, tlsv1.2]
-
-          ## TLS cipher suite names
-          ## Note: By default, all available suites are supported, you do not need to set this
-          ciphers = ["TLS_AES_256_GCM_SHA384","TLS_AES_128_GCM_SHA256"]
-
-          ## Allows a client and a server to renegotiate the parameters of the SSL connection on the fly
-          secure_renegotiate = true
-
-          ## Log level for SSL communication
-          ## Type: emergency | alert | critical | error | warning | notice | info | debug | none | all
-          log_level = notice
-
-          ## Hibernate the SSL process after idling for amount of time reducing its memory footprint
-          hibernate_after = 5s
-
-          ## Forces the cipher to be set based on the server-specified order instead of the client-specified order
-           honor_cipher_order = true
-
-          ##  Setting this to false to disable client-initiated renegotiation
-           client_renegotiation = true
-
-          ## Maximum time duration allowed for the handshake to complete
-           handshake_timeout = 15s
       }
     }
 }
diff --git a/rel/config/examples/cluster-with-etcd.conf.example b/rel/config/examples/cluster-with-etcd.conf.example
index 3eae3b980..2ec888b42 100644
--- a/rel/config/examples/cluster-with-etcd.conf.example
+++ b/rel/config/examples/cluster-with-etcd.conf.example
@@ -1,10 +1,5 @@
-##--------------------------------------------------------------------
-## Cluster in service discovery using 'etcd' service mode
-##
-## Configs to instruct how individual nodes can discover each other
-##--------------------------------------------------------------------
-## Note: This is an example of how to configure this feature
-##       you should copy and paste the below data into the emqx.conf for working
+## Cluster discovery using 'etcd' service
+## Connect to etcd over plain TCP (not TLS)
 
 cluster {
     ## Human-friendly name of the EMQX cluster.
@@ -13,9 +8,6 @@ cluster {
     ## Service discovery method for the cluster nodes
     discovery_strategy = etcd
 
-    ## List of core nodes that the replicant will connect to
-    core_nodes = ["emqx1@192.168.0.1", "emqx2@192.168.0.2"]
-
     ## If true, the node will try to heal network partitions automatically
     autoheal = true
 
diff --git a/rel/config/examples/cluster-with-k8s.conf.example b/rel/config/examples/cluster-with-k8s.conf.example
index 7a0ad3b29..a24409a3c 100644
--- a/rel/config/examples/cluster-with-k8s.conf.example
+++ b/rel/config/examples/cluster-with-k8s.conf.example
@@ -1,10 +1,4 @@
-##--------------------------------------------------------------------
-## Cluster in service discovery via Kubernetes API server mode
-##
-## Configs to instruct how individual nodes can discover each other
-##--------------------------------------------------------------------
-## Note: This is an example of how to configure this feature
-##       you should copy and paste the below data into the emqx.conf for working
+## Cluster discovery via Kubernetes API server mode
 
 cluster {
     ## Human-friendly name of the EMQX cluster.
@@ -13,9 +7,6 @@ cluster {
     ## Service discovery method for the cluster nodes
     discovery_strategy = k8s
 
-    ## List of core nodes that the replicant will connect to
-    core_nodes = ["emqx1@192.168.0.1", "emqx2@192.168.0.2"]
-
     ## If true, the node will try to heal network partitions automatically
     autoheal = true
 
diff --git a/rel/config/examples/cluster-with-manual.conf.example b/rel/config/examples/cluster-with-manual.conf.example
index 7c031b44a..7df0f305f 100644
--- a/rel/config/examples/cluster-with-manual.conf.example
+++ b/rel/config/examples/cluster-with-manual.conf.example
@@ -1,10 +1,4 @@
-##--------------------------------------------------------------------
-## Cluster in service discovery via manual join mode
-##
-## Configs to instruct how individual nodes can discover each other
-##--------------------------------------------------------------------
-## Note: This is an example of how to configure this feature
-##       you should copy and paste the below data into the emqx.conf for working
+## Cluster discovery via `emqx ctl cluster` command
 
 cluster {
     ## Human-friendly name of the EMQX cluster.
@@ -13,9 +7,6 @@ cluster {
     ## Service discovery method for the cluster nodes
     discovery_strategy = manual
 
-    ## List of core nodes that the replicant will connect to
-    core_nodes = ["emqx1@192.168.0.1", "emqx2@192.168.0.2"]
-
     ## If true, the node will try to heal network partitions automatically
     autoheal = true
  }
diff --git a/rel/config/examples/cluster-with-static.conf.example b/rel/config/examples/cluster-with-static.conf.example
index e2263da15..7013ee7ad 100644
--- a/rel/config/examples/cluster-with-static.conf.example
+++ b/rel/config/examples/cluster-with-static.conf.example
@@ -1,10 +1,4 @@
-##--------------------------------------------------------------------
-## Cluster in service discovery via static nodes mode
-##
-## Configs to instruct how individual nodes can discover each other
-##--------------------------------------------------------------------
-## Note: This is an example of how to configure this feature
-##       you should copy and paste the below data into the emqx.conf for working
+## Cluster discovery via static seed nodes
 
 cluster {
     ## Human-friendly name of the EMQX cluster.
@@ -13,9 +7,6 @@ cluster {
     ## Service discovery method for the cluster nodes
     discovery_strategy = static
 
-    ## List of core nodes that the replicant will connect to
-    core_nodes = ["emqx1@192.168.0.1", "emqx2@192.168.0.2"]
-
     ## If true, the node will try to heal network partitions automatically
     autoheal = true
 
diff --git a/rel/config/examples/conn_congestion.conf.example b/rel/config/examples/conn_congestion.conf.example
index e6f3597d1..66a47a65f 100644
--- a/rel/config/examples/conn_congestion.conf.example
+++ b/rel/config/examples/conn_congestion.conf.example
@@ -1,10 +1,6 @@
-##--------------------------------------------------------------------
 ## Connection Congestion
 ##
 ## Generating alarm when MQTT connection congested
-##--------------------------------------------------------------------
-## Note: This is an example of how to configure this feature
-##       you should copy and paste the below data into the emqx.conf for working
 
 conn_congestion {
     ## Enable or disable connection congestion alarm
diff --git a/rel/config/examples/dashboard-with-http.conf.example b/rel/config/examples/dashboard-with-http.conf.example
index 8cf68ab33..e6107e116 100644
--- a/rel/config/examples/dashboard-with-http.conf.example
+++ b/rel/config/examples/dashboard-with-http.conf.example
@@ -1,10 +1,6 @@
-##--------------------------------------------------------------------
-## Dashboard with HTTP Listener
+## Dashboard on HTTP
 ##
-## Configuration for EMQX dashboard
-##--------------------------------------------------------------------
-## Note: This is an example of how to configure this feature
-##       you should copy and paste the below data into the emqx.conf for working
+## Configure HTTP for EMQX dashboard
 
 dashboard {
     ## JWT token expiration time
diff --git a/rel/config/examples/dashboard-with-https.conf.example b/rel/config/examples/dashboard-with-https.conf.example
index 5cc277e47..8e15077e0 100644
--- a/rel/config/examples/dashboard-with-https.conf.example
+++ b/rel/config/examples/dashboard-with-https.conf.example
@@ -1,10 +1,6 @@
-##--------------------------------------------------------------------
-## Dashboard with HTTPS Listener
+## Dashboard on HTTPS
 ##
-## Configuration for EMQX dashboard
-##--------------------------------------------------------------------
-## Note: This is an example of how to configure this feature
-##       you should copy and paste the below data into the emqx.conf for working
+## Configure HTTPS for EMQX dashboard
 
 dashboard {
     ## JWT token expiration time
diff --git a/rel/config/examples/exhook.conf.example b/rel/config/examples/exhook.conf.example
index 8adcfcab9..cf9fffc71 100644
--- a/rel/config/examples/exhook.conf.example
+++ b/rel/config/examples/exhook.conf.example
@@ -1,8 +1,6 @@
-##--------------------------------------------------------------------
 ## gRPC Hook Extension
 ##
-## Allows users to process EMQX Hooks using other programming languages
-##--------------------------------------------------------------------
+## Allows users to provide hook callbacks over gRPC for EMQX message lifecycle events.
 
 exhook.servers = [
     {
diff --git a/rel/config/examples/file_transfer-with-local-exporter.conf.example b/rel/config/examples/file_transfer-with-local-exporter.conf.example
index 8dbd04f66..860826d38 100644
--- a/rel/config/examples/file_transfer-with-local-exporter.conf.example
+++ b/rel/config/examples/file_transfer-with-local-exporter.conf.example
@@ -1,12 +1,6 @@
-##--------------------------------------------------------------------
-## File Transfer
+## File Transfer over MQTT exporting files to local file system
 ##
-## Enables the File Transfer over MQTT feature
-##--------------------------------------------------------------------
-## Note: This is an example of how to configure this feature
-##       you should copy and paste the below data into the emqx.conf for working
-
-## Note: This configuration only works for the EMQX Enterprise version
+## NOTE: This configuration is only applicable in EMQX Enterprise edition 5.1 or later.
 
 file_transfer {
     ## Enable the File Transfer feature
diff --git a/rel/config/examples/file_transfer-with-s3-exporter.conf.example b/rel/config/examples/file_transfer-with-s3-exporter.conf.example
index a59c7918c..cba6fada5 100644
--- a/rel/config/examples/file_transfer-with-s3-exporter.conf.example
+++ b/rel/config/examples/file_transfer-with-s3-exporter.conf.example
@@ -1,12 +1,7 @@
-##--------------------------------------------------------------------
-## File Transfer
+## File Transfer over MQTT
 ##
 ## Enables the File Transfer over MQTT feature
-##--------------------------------------------------------------------
-## Note: This is an example of how to configure this feature
-##       you should copy and paste the below data into the emqx.conf for working
-
-## Note: This configuration only works for the EMQX Enterprise version
+## Note: This configuration is only applicable for EMQX Enterprise edition 5.1 or later.
 
 file_transfer {
     ## Enable the File Transfer feature
diff --git a/rel/config/examples/flapping_detect.conf.example b/rel/config/examples/flapping_detect.conf.example
index b33a805ea..fe4522b1e 100644
--- a/rel/config/examples/flapping_detect.conf.example
+++ b/rel/config/examples/flapping_detect.conf.example
@@ -1,14 +1,10 @@
-##--------------------------------------------------------------------
 ## Flapping Detect
 ##
-## Ban the client when the times of connections exceed the limit in the time window
-##--------------------------------------------------------------------
-## Note: This is an example of how to configure this feature
-##       you should copy and paste the below data into the emqx.conf for working
+## Ban the client when the times of connections exceed the limit in the configured time window
 
 flapping_detect {
-    ## use false to disabled
-    enable = true
+    ## use 'true' to enable this feature
+    enable = false
 
     ## Time window for flapping detection
     window_time = 1m
diff --git a/rel/config/examples/force_gc.conf.example b/rel/config/examples/force_gc.conf.example
index e682d723d..ee07ee4d2 100644
--- a/rel/config/examples/force_gc.conf.example
+++ b/rel/config/examples/force_gc.conf.example
@@ -1,13 +1,7 @@
-##--------------------------------------------------------------------
-## Force garbage collection
-##
-## Force garbage collection in MQTT connection process after they process certain number of messages or bytes of data
-##--------------------------------------------------------------------
-## Note: This is an example of how to configure this feature
-##       you should copy and paste the below data into the emqx.conf for working
+## Force Elrang VM garbage collection
 
 force_gc {
-    ## set to false to disable this
+    ## set 'false' to disable this feature
     enable = true
 
     ## GC the process after this many received messages
diff --git a/rel/config/examples/force_shutdown.conf.example b/rel/config/examples/force_shutdown.conf.example
index b049691c6..d0a466aa0 100644
--- a/rel/config/examples/force_shutdown.conf.example
+++ b/rel/config/examples/force_shutdown.conf.example
@@ -1,13 +1,9 @@
-##--------------------------------------------------------------------
 ## Force Shutdown
 ##
-## Forced closing of the overloaded session
-##--------------------------------------------------------------------
-## Note: This is an example of how to configure this feature
-##       you should copy and paste the below data into the emqx.conf for working
+## Forced shutdown MQTT clients for overload protection
 
 force_shutdown {
-    ## false to disable this
+    ## set 'false' to disable force shutdown feature
     enable = true
 
     ## Maximum mailbox size for each Erlang process
diff --git a/rel/config/examples/gateway.exproto.conf.example b/rel/config/examples/gateway.exproto.conf.example
index 04c95d98c..fcedb944b 100644
--- a/rel/config/examples/gateway.exproto.conf.example
+++ b/rel/config/examples/gateway.exproto.conf.example
@@ -1,10 +1,4 @@
-##--------------------------------------------------------------------
 ## Gateway Exproto
-##
-## Add an Exproto gateway
-##--------------------------------------------------------------------
-## Note: This is an example of how to configure this feature
-##       you should copy and paste the below data into the emqx.conf for working
 
 gateway.exproto {
 
diff --git a/rel/config/examples/gateway.lwm2m.conf.example b/rel/config/examples/gateway.lwm2m.conf.example
index 2c9b55c04..60943f47c 100644
--- a/rel/config/examples/gateway.lwm2m.conf.example
+++ b/rel/config/examples/gateway.lwm2m.conf.example
@@ -1,10 +1,4 @@
-##--------------------------------------------------------------------
 ## Gateway LwM2M
-##
-## Add a LwM2M gateway
-##--------------------------------------------------------------------
-## Note: This is an example of how to configure this feature
-##       you should copy and paste the below data into the emqx.conf for working
 
 gateway.lwm2m {
 
diff --git a/rel/config/examples/gateway.mqttsn.conf.example b/rel/config/examples/gateway.mqttsn.conf.example
index 7785454f3..aac7d6898 100644
--- a/rel/config/examples/gateway.mqttsn.conf.example
+++ b/rel/config/examples/gateway.mqttsn.conf.example
@@ -1,10 +1,4 @@
-##--------------------------------------------------------------------
 ## Gateway MQTT-SN
-##
-## Add a MQTT-SN gateway
-##--------------------------------------------------------------------
-## Note: This is an example of how to configure this feature
-##       you should copy and paste the below data into the emqx.conf for working
 
 gateway.mqttsn {
 
diff --git a/rel/config/examples/gateway.stomp.conf.example b/rel/config/examples/gateway.stomp.conf.example
index ab09a45f7..e90a04620 100644
--- a/rel/config/examples/gateway.stomp.conf.example
+++ b/rel/config/examples/gateway.stomp.conf.example
@@ -1,10 +1,4 @@
-##--------------------------------------------------------------------
 ## Gateway STOMP
-##
-## Add STOMP CoAP gateway
-##--------------------------------------------------------------------
-## Note: This is an example of how to configure this feature
-##       you should copy and paste the below data into the emqx.conf for working
 
 gateway.stomp {
 
diff --git a/rel/config/examples/license.conf.example b/rel/config/examples/license.conf.example
index 7444ae795..2cb0dc3bd 100644
--- a/rel/config/examples/license.conf.example
+++ b/rel/config/examples/license.conf.example
@@ -1,12 +1,6 @@
-##--------------------------------------------------------------------
-## License
-##
-## Defines the EMQX Enterprise license
-##--------------------------------------------------------------------
-## Note: This is an example of how to configure this feature
-##       you should copy and paste the below data into the emqx.conf for working
+## EMQX Enterprise License
 
-## Note: This configuration only works for the EMQX Enterprise version
+## NOTE: This configuration is only applicable for the EMQX Enterprise eidtion
 
 license {
     ## License Key
diff --git a/rel/config/examples/listeners.quic.conf.example b/rel/config/examples/listeners.quic.conf.example
index 49d4f58a1..52161e828 100644
--- a/rel/config/examples/listeners.quic.conf.example
+++ b/rel/config/examples/listeners.quic.conf.example
@@ -1,13 +1,6 @@
-##--------------------------------------------------------------------
-## QUIC Listener
-##
-## Add a QUIC Listener
-##--------------------------------------------------------------------
-## Note: This is an example of how to configure this feature
-##       you should copy and paste the below data into the emqx.conf for working
+## MQTT over QUIC Listener
 
-## Note: Modifying the 'quicname' to what you need
-listeners.quic.quicname {
+listeners.quic.my_quick_listener_name {
     ## Port or Address to listen on, 0 means disable
     bind = 14567 ## or with an IP, e.g. "127.0.0.1:14567"
 
@@ -28,8 +21,8 @@ listeners.quic.quicname {
     ## Type: infinity | Integer
     max_connections = infinity
 
-    ## TLS cipher suite names
-    ciphers = ["TLS_AES_256_GCM_SHA384", "TLS_AES_128_GCM_SHA256", "TLS_CHACHA20_POLY1305_SHA256"]
+    ## TLS v1.3 exclusive cipher suite names
+    ciphers = "TLS_AES_256_GCM_SHA384,TLS_AES_128_GCM_SHA256,TLS_CHACHA20_POLY1305_SHA256"
 
     ssl_options {
         ## Trusted PEM format CA certificates bundle file
diff --git a/rel/config/examples/listeners.ssl.conf.example b/rel/config/examples/listeners.ssl.conf.example
index 11078db6c..a33ce7efe 100644
--- a/rel/config/examples/listeners.ssl.conf.example
+++ b/rel/config/examples/listeners.ssl.conf.example
@@ -1,16 +1,6 @@
-##--------------------------------------------------------------------
-## SSL Listener
-##
-## Add a SSL Listener
-##--------------------------------------------------------------------
-## Note: This is an example of how to configure this feature
-##       you should copy and paste the below data into the emqx.conf for working
+## MQTT over TLS(SSL) Listener
 
-## The SSL listener also supports all the fields listed in listeners.tcp.conf.example
-## only the SSL-specific fields are shown here
-
-## Note: Modifying the 'sslname' to what you need
-listeners.ssl.sslname {
+listeners.ssl.my_ssl_listener_name {
     ## Port or Address to listen on, 0 means disable
     bind = 8883 ## or with an IP e.g. "127.0.0.1:8883"
     enabled = true
@@ -33,13 +23,13 @@ listeners.ssl.sslname {
     }
     ssl_options {
         ## Trusted PEM format CA certificates bundle file
-        cacertfile = "data/certs/cacert.pem"
+        cacertfile = "${EMQX_ETC_DIR}/certs/cacert.pem"
 
         ## PEM format certificates chain file
-        certfile = "data/certs/cert.pem"
+        certfile = "${EMQX_ETC_DIR}/certs/cert.pem"
 
         ## PEM format private key file
-        keyfile = "data/certs/key.pem"
+        keyfile = "${EMQX_ETC_DIR}/certs/key.pem"
 
         ## Enable or disable peer verification
         verify = verify_none  ## use verify_peer to enable
@@ -58,7 +48,7 @@ listeners.ssl.sslname {
 
         ## TLS cipher suite names
         ## Note: By default, all available suites are supported, you do not need to set this
-        ciphers = ["TLS_AES_256_GCM_SHA384","TLS_AES_128_GCM_SHA256"]
+        ciphers = "TLS_AES_256_GCM_SHA384,TLS_AES_128_GCM_SHA256,ECDHE-RSA-AES256-GCM-SHA384"
 
         ## Allows a client and a server to renegotiate the parameters of the SSL connection on the fly
         secure_renegotiate = true
diff --git a/rel/config/examples/listeners.tcp.conf.example b/rel/config/examples/listeners.tcp.conf.example
index 42e98b071..f03d98cc2 100644
--- a/rel/config/examples/listeners.tcp.conf.example
+++ b/rel/config/examples/listeners.tcp.conf.example
@@ -1,13 +1,6 @@
-##--------------------------------------------------------------------
-## TCP Listener
-##
-## Add a TCP Listener
-##--------------------------------------------------------------------
-## Note: This is an example of how to configure this feature
-##       you should copy and paste the below data into the emqx.conf for working
+## MQTT over TCP Listener
 
-## Note: Modifying the 'tcpname' to what you need
-listeners.tcp.tcpname {
+listeners.tcp.my_tcp_listener_name {
     ## Port or Address to listen on, 0 means disable
     bind = 1883 ## or with an IP e.g. "127.0.0.1:1883"
 
diff --git a/rel/config/examples/listeners.ws.conf.example b/rel/config/examples/listeners.ws.conf.example
index 60523ac7a..f6a6adae8 100644
--- a/rel/config/examples/listeners.ws.conf.example
+++ b/rel/config/examples/listeners.ws.conf.example
@@ -1,16 +1,6 @@
-##--------------------------------------------------------------------
-## WebSocket Listener
-##
-## Add a WebSocket Listener
-##--------------------------------------------------------------------
-## Note: This is an example of how to configure this feature
-##       you should copy and paste the below data into the emqx.conf for working
+## MQTT over WebSocket (HTTP) Listener
 
-## The WebSocket listener supports all the fields listed in listeners.tcp.conf.example
-## only the WebSocket-specific fields are shown here
-
-## Note: Modifying the 'wsname' to what you need
-listeners.ws.wsname {
+listeners.ws.my_ws_listener_name {
     ## Port or Address to listen on, 0 means disable
     bind = "0.0.0.0:8083" # or just a port number, e.g. 8083
     enabled = true
diff --git a/rel/config/examples/listeners.wss.conf.example b/rel/config/examples/listeners.wss.conf.example
index 799d082d7..cbc632e30 100644
--- a/rel/config/examples/listeners.wss.conf.example
+++ b/rel/config/examples/listeners.wss.conf.example
@@ -1,16 +1,6 @@
-##--------------------------------------------------------------------
-## WSS Listener
-##
-## Add a WSS Listener
-##--------------------------------------------------------------------
-## Note: This is an example of how to configure this feature
-##       you should copy and paste the below data into the emqx.conf for working
+## MQTT over Secured Websocket (HTTPS) Listener
 
-## The WSS listener supports all the fields listed in listeners.ws.conf.example
-## only the WSS-specific fields are shown here
-
-## Note: Modifying the 'wssname' to what you need
-listeners.wss.wssname {
+listeners.wss.my_wss_listener_name = {
     ## Port or Address to listen on, 0 means disable
     bind = 8084 ## or with an IP, e.g. "127.0.0.1:8084"
     enabled = true
@@ -76,11 +66,11 @@ listeners.wss.wssname {
         depth = 10
 
         ## Which versions are to be supported
-        versions = [tlsv1.3, tlsv1.2]
+        versions = ["tlsv1.3", "tlsv1.2"]
 
         ## TLS cipher suite names
         ## Note: By default, all available suites are supported, you do not need to set this
-        ciphers = ["TLS_AES_256_GCM_SHA384","TLS_AES_128_GCM_SHA256"]
+        ciphers = "TLS_AES_256_GCM_SHA384,TLS_AES_128_GCM_SHA256,ECDHE-RSA-AES256-GCM-SHA384"
 
         ## Allows a client and a server to renegotiate the parameters of the SSL connection on the fly
         secure_renegotiate = true
diff --git a/rel/config/examples/log.console.conf.example b/rel/config/examples/log.console.conf.example
index 1dd30e120..9bb01b0d9 100644
--- a/rel/config/examples/log.console.conf.example
+++ b/rel/config/examples/log.console.conf.example
@@ -1,10 +1,4 @@
-##--------------------------------------------------------------------
-## Log
-##
-## Configure the log output location, log level, log file storage path, and parameters
-##--------------------------------------------------------------------
-## Note: This is an example of how to configure this feature
-##       you should copy and paste the below data into the emqx.conf for working
+## Log to console
 
 log.console {
     ## set true to enable this
diff --git a/rel/config/examples/log.file.conf.example b/rel/config/examples/log.file.conf.example
index deb9b16b9..e6f408f61 100644
--- a/rel/config/examples/log.file.conf.example
+++ b/rel/config/examples/log.file.conf.example
@@ -1,21 +1,14 @@
-##--------------------------------------------------------------------
-## Log
-##
-## Configure the log output location, log level, log file storage path, and parameters
-##--------------------------------------------------------------------
-## Note: This is an example of how to configure this feature
-##       you should copy and paste the below data into the emqx.conf for working
+## Log to file
 
-## The default-enabled log handler can use all the above fields listed fields
 log.file {
-    ## use false to disable this
+    ## Enable file log handler
     enable = true
 
     ## Log level
     ## Type: debug | info | notice | warning | error | critical | alert | emergency
     level = warning
 
-    ## Log formatter, text for free text, and json for structured logging
+    ## Log formatter, text for free text, and json for more structured logging
     ## Type: text | json
     formatter = text
 
diff --git a/rel/config/examples/mqtt.conf.example b/rel/config/examples/mqtt.conf.example
index c5f81f753..64c73524c 100644
--- a/rel/config/examples/mqtt.conf.example
+++ b/rel/config/examples/mqtt.conf.example
@@ -1,10 +1,5 @@
-##--------------------------------------------------------------------
-## MQTT
-##
-##  MQTT configuration
-##--------------------------------------------------------------------
-## Note: This is an example of how to configure this feature
-##       you should copy and paste the below data into the emqx.conf for working
+## MQTT protocol related settings
+## Settings in this section is applied globally to all MQTT connections/sessions in this node
 
 mqtt {
     ## After the TCP connection is established,
@@ -121,4 +116,4 @@ mqtt {
     ##   - hash_clientid :: select the subscribers by hashing the `clientIds`
     ##   - hash_topic :: select the subscribers by hashing the source topic"""
     shared_subscription_strategy = round_robin
- }
+}
diff --git a/rel/config/examples/node.conf.example b/rel/config/examples/node.conf.example
index 65c08b337..b3db9288e 100644
--- a/rel/config/examples/node.conf.example
+++ b/rel/config/examples/node.conf.example
@@ -1,10 +1,4 @@
-##--------------------------------------------------------------------
-## Node
-##
-## configuring for current EMQX node
-##--------------------------------------------------------------------
-## Note: This is an example of how to configure this feature
-##       you should copy and paste the below data into the emqx.conf for working
+## EMQX Node
 
 ## Note: all fields in this section are immutable after EMQX started, and most of the time you only need to modify the value for the name and cookie.
 node {
@@ -14,29 +8,31 @@ node {
     ##   Note: Make sure the IP resolve from the domain is deterministic and unique and never change
     name = "emqx@127.0.0.1"
 
-    ## Secret cookie is a random string that should be the same on all nodes in the given EMQX cluster, but unique per EMQX cluster
-    cookie = "Yzc0NGExM2RjYzYxYzM0YzQ5MWQ0NmI1NWM0MWRhMzY4NzgxYmFkMmI2MWJjZWQ5NTQzYTMxNjE1ODVmYmJmMyAgLQo="
+    ## Secret cookie is a random string that should be the same on all nodes in the cluster, but unique per EMQX cluster
+    cookie = "Yzc0NGExM2Rj"
 
     ## Select a node role
-    ## Type:
-    ##   - core :: nodes provide durability of the data, and take care of writes
-    ##   - replicant :: nodes are ephemeral worker nodes
+    ## Possible values:
+    ##   - core: This is a core node which provides durability of the client states, and takes care of writes
+    ##   - replicant: This is a stateless worker node
     role = core
 
     ## Maximum number of simultaneously existing processes for this Erlang system
-    ## Type: Range from 1024 to 134217727
     process_limit = 2097152
 
-    ## Maximum number of simultaneously existing ports for this Erlang system
-    ## Type: Range from 1024 to 134217727
+    ## Maximum number of simultaneously open files and sockets for this Erlang system
     max_ports = 1048576
 
-    ## Erlang's distribution buffer busy limit in kilobytes
-    ## Type: Range from 1 to 2097152
+    ## Erlang's distribution buffer busy limit in kilobytes.
+    ## Range from 1 to 2097152
     dist_buffer_size = 8192
 
-    ## Path to the persistent data directory
-    data_dir = "var/emqx/data"
+    ## NOTE: keep this the same for all nodes in the cluster.
+    ## Path to the persistent data directory.
+    ## This config is pre-filled when the EMQX distribution package is built.
+    ## You are advised to use the default value.
+    #data_dir = "data" # when running a zip package or in docker container
+    #data_dir = "/var/lib/emqx" # when installed from deb/rpm packages
 
     ## Type: Periodic garbage collection interval
     global_gc_interval = 15m
diff --git a/rel/config/examples/plugin.conf.example b/rel/config/examples/plugin.conf.example
index d704f9981..fe6e25966 100644
--- a/rel/config/examples/plugin.conf.example
+++ b/rel/config/examples/plugin.conf.example
@@ -1,11 +1,4 @@
-##--------------------------------------------------------------------
-## Plugin
-##
-## Manage EMQX plugins
-##--------------------------------------------------------------------
-## Note: This is an example of how to configure this feature
-##       you should copy and paste the below data into the emqx.conf for working
-
+## Plugin management
 plugin {
     ## Plugins declaration
     ## Note: The plugins are started in the defined order
diff --git a/rel/config/examples/prometheus-pushgateway.conf.example b/rel/config/examples/prometheus-pushgateway.conf.example
new file mode 100644
index 000000000..70b74794a
--- /dev/null
+++ b/rel/config/examples/prometheus-pushgateway.conf.example
@@ -0,0 +1,28 @@
+## Prometheus push-gateway integration
+
+## EMQX's Prometheus scraping endpoint is enabled by default without authentication.
+## e.g. curl -f "127.0.0.1:18083/api/v5/prometheus/stats"
+## If you want to use push-gateway
+
+prometheus {
+    ## Set to true to make EMQX send metrics to push-gateway
+    enable = false
+
+    ## URL of push-gateway server
+    push_gateway_server = "http://127.0.0.1:9091"
+
+    ## Data push interval
+    interval = 15s
+
+    ## A HTTP Headers when pushing to Push-gateway
+    headers = {
+        Authorization = "some-authz-tokens",
+        Connection = "keep-alive"
+    }
+
+    ## Job Name that is pushed to the Push-gateway
+    ## Available variable:
+    ## - ${name}: Name of EMQX node
+    ## - ${host}: Host name of EMQX node
+    job_name = "${name}/instance/${name}~${host}"
+}
diff --git a/rel/config/examples/prometheus.conf.example b/rel/config/examples/prometheus.conf.example
index 645e10364..face3fc1f 100644
--- a/rel/config/examples/prometheus.conf.example
+++ b/rel/config/examples/prometheus.conf.example
@@ -1,28 +1,10 @@
-##--------------------------------------------------------------------
-## Prometheus
-##
-## Settings for reporting metrics to Prometheus
-##--------------------------------------------------------------------
+## Prometheus push-gateway integration
+
+## EMQX's Prometheus scraping endpoint is enabled by default without authentication.
+## And there is no way to turn it off.
+## You can inspect it with a curl command: curl -f "127.0.0.1:18083/api/v5/prometheus/stats"
 
 prometheus {
-    ## URL of Prometheus server
-    push_gateway_server = "http://127.0.0.1:9091"
-
-    ## Data reporting interval
-    interval = 15s
-
-    ## A HTTP Headers when pushing to Push Gateway.
-    headers = {
-        Authorization = "some-authz-tokens",
-        Connection = "keep-alive"
-    }
-
-    ## Job Name that is pushed to the Push Gateway.
-    ## Available variable:
-    ## - ${name}: Name of EMQX node
-    ## - ${host}: Host name of EMQX node
-    job_name = "${name}/instance/${name}~${host}"
-
-    ## set to false to enable this
-    enable = true
+    # turn off this expensive collector
+    vm_dist_collector = disabled
 }
diff --git a/rel/config/examples/psk_authentication.conf.example b/rel/config/examples/psk_authentication.conf.example
index 272eb41b5..6c3482638 100644
--- a/rel/config/examples/psk_authentication.conf.example
+++ b/rel/config/examples/psk_authentication.conf.example
@@ -1,13 +1,7 @@
-##--------------------------------------------------------------------
 ## Pre-Shared Keys authentication
-##
-## Config to enable TLS-PSK authentication
-##--------------------------------------------------------------------
-## Note: This is an example of how to configure this feature
-##       you should copy and paste the below data into the emqx.conf for working
 
 psk_authentication {
-    ## set to false to disable
+    ## Set to false to disable
     enable = true
 
     ## If init_file is specified, EMQX will import PSKs from the file into the built-in database at startup for use by the runtime
diff --git a/rel/config/examples/retainer.conf.example b/rel/config/examples/retainer.conf.example
index 1cef31c30..51101c9c7 100644
--- a/rel/config/examples/retainer.conf.example
+++ b/rel/config/examples/retainer.conf.example
@@ -3,20 +3,12 @@
 ##
 ## Configuration related to handling PUBLISH packets with a retain flag set to 1
 ##--------------------------------------------------------------------
-## Note: This is an example of how to configure this feature
-##       you should copy and paste the below data into the emqx.conf for working
 
 retainer {
-    ## set to false to disable this
+    ## set to false to disable retainer
     enable = true
 
-    ## Message retention time. 0 means message will never be expired
-    msg_expiry_interval = 0s
-
-    ## Periodic interval for cleaning up expired messages. Never clear if the value is 0
-    msg_clear_interval = 0s
-
-    ## Maximum retained message size
+    ## Maximum message size allowed
     max_payload_size = 1MB
 
     ## When the retained flag of the PUBLISH message is set and Payload is empty, whether to continue to publish the message
@@ -27,10 +19,10 @@ retainer {
 
     ## Retained messages store backend
     backend {
-      ## Backend type
+      ## Built-in database (Mnesia)
       type = built_in_database
 
-      ## Specifies whether the messages are stored in RAM or persisted on disc
+      ## Specifies whether the messages are stored in RAM or persisted on disk
       ## Type: enum: ram | disc
       storage_type = ram
 
diff --git a/rel/config/examples/sys_topics.conf.example b/rel/config/examples/sys_topics.conf.example
index b249efd35..e4d0611b1 100644
--- a/rel/config/examples/sys_topics.conf.example
+++ b/rel/config/examples/sys_topics.conf.example
@@ -1,10 +1,5 @@
-##--------------------------------------------------------------------
 ## System Topic
-##
 ## Publishing client lifecycle events to "$SYS" topics
-##--------------------------------------------------------------------
-## Note: This is an example of how to configure this feature
-##       you should copy and paste the below data into the emqx.conf for working
 
 sys_topics {
     ## Time interval of publishing `$SYS` messages
diff --git a/rel/config/examples/sysmon.os.conf.example b/rel/config/examples/sysmon.os.conf.example
index 95e7aa1ec..08e025da0 100644
--- a/rel/config/examples/sysmon.os.conf.example
+++ b/rel/config/examples/sysmon.os.conf.example
@@ -1,10 +1,4 @@
-##--------------------------------------------------------------------
-## System Monitoring For System
-##
-## System monitoring and introspection
-##--------------------------------------------------------------------
-## Note: This is an example of how to configure this feature
-##       you should copy and paste the below data into the emqx.conf for working
+## System Monitoring of the host machine
 
 sysmon.os {
     ## Time interval for the periodic CPU check
@@ -17,9 +11,9 @@ sysmon.os {
     cpu_low_watermark = 60%
 
     ## Time interval for the periodic memory check
-    ## Type:
-    ##   - disabled :: Never check
-    ##   - Time Duration :: The time period
+    ## Possible values:
+    ##   disabled: Never check
+    ##   Duration: Check every Duration 
     mem_check_interval = 60s
 
     ## For how much system memory can be allocated before the corresponding alarm is raised
diff --git a/rel/config/examples/sysmon.vm.conf.example b/rel/config/examples/sysmon.vm.conf.example
index d68141cea..6ca6ee411 100644
--- a/rel/config/examples/sysmon.vm.conf.example
+++ b/rel/config/examples/sysmon.vm.conf.example
@@ -1,10 +1,4 @@
-##--------------------------------------------------------------------
 ## System Monitoring For Erlang VM
-##
-## System monitoring and introspection
-##--------------------------------------------------------------------
-## Note: This is an example of how to configure this feature
-##       you should copy and paste the below data into the emqx.conf for working
 
 sysmon.vm {
     ## Time interval for the periodic process limit check
@@ -25,7 +19,7 @@ sysmon.vm {
     ## Generating an alarm is generated when the Erlang VM detect a task scheduled for too long
     ## Type:
     ##   - disabled :: Never alarm
-    ##   - Time During :: The maximum schedule time for generating an alarm
+    ##   - Duration:: The maximum schedule time for generating an alarm
     long_schedule = 240ms
 
     ## Generating an alarm when an Erlang process consumed a large amount of memory for its heap space
diff --git a/rel/i18n/emqx_conf_schema.hocon b/rel/i18n/emqx_conf_schema.hocon
index 416b3ca76..1fb37cd0a 100644
--- a/rel/i18n/emqx_conf_schema.hocon
+++ b/rel/i18n/emqx_conf_schema.hocon
@@ -135,7 +135,7 @@ log_overload_kill_restart_after.label:
 """Handler Restart Timer"""
 
 log_file_handler_max_size.desc:
-"""This parameter controls log file rotation. The value `infinity` means the log file will grow indefinitely, otherwise the log file will be rotated once it reaches `max_size` in bytes."""
+"""This parameter controls log file rotation. The value `infinity` means the log file will grow indefinitely, otherwise the log file will be rotated once it reaches `rotation_size` in bytes."""
 
 log_file_handler_max_size.label:
 """Rotation Size"""
@@ -514,15 +514,13 @@ cluster_autoclean.label:
 
 process_limit.desc:
 """Maximum number of simultaneously existing processes for this Erlang system.
-The actual maximum chosen may be much larger than the Number passed.
 For more information, see: https://www.erlang.org/doc/man/erl.html"""
 
 process_limit.label:
 """Erlang Process Limit"""
 
 max_ports.desc:
-"""Maximum number of simultaneously existing ports for this Erlang system.
-The actual maximum chosen may be much larger than the Number passed.
+"""Maximum number of simultaneously open files and sockets for this Erlang system.
 For more information, see: https://www.erlang.org/doc/man/erl.html"""
 
 max_ports.label:
diff --git a/rel/i18n/emqx_prometheus_schema.hocon b/rel/i18n/emqx_prometheus_schema.hocon
index d68e1d418..4dd9a2e1e 100644
--- a/rel/i18n/emqx_prometheus_schema.hocon
+++ b/rel/i18n/emqx_prometheus_schema.hocon
@@ -21,13 +21,15 @@ mnesia_collector.desc:
 """Enable or disable Mnesia collector, collects Mnesia metrics mainly using mnesia:system_info/1 ."""
 
 prometheus.desc:
-"""Settings for reporting metrics to Prometheus"""
+"""EMQX's Prometheus scraping endpoint is enabled by default without authentication.
+You can inspect it with a `curl` command like this: `curl -f "127.0.0.1:18083/api/v5/prometheus/stats"`<br/>
+The 'enable' flag is used to turn on and off for the push-gateway integration."""
 
 prometheus.label:
 """Prometheus"""
 
 push_gateway_server.desc:
-"""URL of Prometheus server"""
+"""URL of Prometheus server. Pushgateway is optional, should not be configured if prometheus is to scrape EMQX."""
 
 vm_dist_collector.desc:
 """Enable or disable VM distribution collector, collects information about the sockets and processes involved in the Erlang distribution mechanism."""
diff --git a/rel/i18n/emqx_retainer_schema.hocon b/rel/i18n/emqx_retainer_schema.hocon
index 49b55d259..fc8d4a028 100644
--- a/rel/i18n/emqx_retainer_schema.hocon
+++ b/rel/i18n/emqx_retainer_schema.hocon
@@ -34,11 +34,11 @@ mnesia_config_type.desc:
 """Backend type."""
 
 msg_clear_interval.desc:
-"""Periodic interval for cleaning up expired messages.
-Never clear if the value is 0."""
+"""Interval for EMQX to scan expired messages and delete them. Never scan if the value is 0."""
 
 msg_expiry_interval.desc:
-"""Message retention time. 0 means message will never be expired."""
+"""Message retention time. This config is only applicable for messages without the Message Expiry Interval message property.
+0 means message will never expir."""
 
 stop_publish_clear_msg.desc:
 """When the retained flag of the `PUBLISH` message is set and Payload is empty,