Merge pull request #12599 from zmstone/0227-refactor-log-config-template

docs: add log docs

apps/emqx/etc/emqx.conf

@@ -0,0 +1,20 @@
+## EMQX provides support for two primary log handlers: `file` and `console`, with an additional `audit` handler specifically designed to always direct logs to files.
+## The system's default log handling behavior can be configured via the environment variable `EMQX_DEFAULT_LOG_HANDLER`, which accepts the following settings:
+##
+##   - `file`: Directs log output exclusively to files.
+##   - `console`: Channels log output solely to the console.
+##
+## It's noteworthy that `EMQX_DEFAULT_LOG_HANDLER` is set to `file` when EMQX is initiated via systemd `emqx.service` file.
+## In scenarios outside systemd initiation, `console` serves as the default log handler.
+
+## Read more about configs here: {{ emqx_configuration_doc_log }}
+
+log {
+    # file {
+    #     level = warning
+    # }
+    # console {
+    #     level = warning
+    # }
+}
+

apps/emqx_conf/src/emqx_conf_schema.erl

@@ -116,7 +116,8 @@ roots() ->
                     ?R_REF("log"),
                     #{
                         translate_to => ["kernel"],
-                        importance => ?IMPORTANCE_HIGH
+                        importance => ?IMPORTANCE_HIGH,
+                        desc => ?DESC(log_root)
                     }
                 )},
             {rpc,
@@ -1234,9 +1235,10 @@ tr_cluster_discovery(Conf) ->
     {Strategy, filter(cluster_options(Strategy, Conf))}.
 
 log_handler_common_confs(Handler, Default) ->
-    %% we rarely support dynamic defaults like this
-    %% for this one, we have build-time default the same as runtime default
-    %% so it's less tricky
+    %% We rarely support dynamic defaults like this.
+    %% For this one, we have build-time default the same as runtime default so it's less tricky
+    %% Buildtime default: "" (which is the same as "file")
+    %% Runtime default: "file" (because .service file sets EMQX_DEFAULT_LOG_HANDLER to "file")
     EnableValues =
         case Handler of
             console -> ["console", "both"];

bin/emqx

@@ -604,7 +604,7 @@ check_license() {
         return 0
     fi
 
-    key_license="${EMQX_LICENSE__KEY:-$(get_boot_config 'license.key')}"
+    key_license="${EMQX_LICENSE__KEY:-$(get_boot_config 'license.key' || echo '')}"
 
     if [[ -n "$key_license" && ("$key_license" != "undefined") ]]; then
       call_nodetool check_license_key "$key_license"

mix.exs

@@ -722,7 +722,8 @@ defmodule EMQXUmbrella.MixProject do
   defp template_vars(release, release_type, :bin = _package_type, edition_type) do
     [
       emqx_default_erlang_cookie: default_cookie(),
-      emqx_configuration_doc: emqx_configuration_doc(edition_type),
+      emqx_configuration_doc: emqx_configuration_doc(edition_type, :root),
+      emqx_configuration_doc_log: emqx_configuration_doc(edition_type, :log),
       platform_data_dir: "data",
       platform_etc_dir: "etc",
       platform_plugins_dir: "plugins",
@@ -745,7 +746,8 @@ defmodule EMQXUmbrella.MixProject do
   defp template_vars(release, release_type, :pkg = _package_type, edition_type) do
     [
       emqx_default_erlang_cookie: default_cookie(),
-      emqx_configuration_doc: emqx_configuration_doc(edition_type),
+      emqx_configuration_doc: emqx_configuration_doc(edition_type, :root),
+      emqx_configuration_doc_log: emqx_configuration_doc(edition_type, :log),
       platform_data_dir: "/var/lib/emqx",
       platform_etc_dir: "/etc/emqx",
       platform_plugins_dir: "/var/lib/emqx/plugins",
@@ -779,11 +781,17 @@ defmodule EMQXUmbrella.MixProject do
     end
   end
 
-  defp emqx_configuration_doc(:enterprise),
-    do: "https://docs.emqx.com/en/enterprise/v5.0/configuration/configuration.html"
+  defp emqx_configuration_doc(:enterprise, :root),
+    do: "https://docs.emqx.com/en/enterprise/latest/configuration/configuration.html"
 
-  defp emqx_configuration_doc(:community),
-    do: "https://www.emqx.io/docs/en/v5.0/configuration/configuration.html"
+  defp emqx_configuration_doc(:enterprise, :log),
+    do: "https://docs.emqx.com/en/enterprise/latest/configuration/logs.html"
+
+  defp emqx_configuration_doc(:community, :root),
+    do: "https://www.emqx.io/docs/en/latest/configuration/configuration.html"
+
+  defp emqx_configuration_doc(:community, :log),
+    do: "https://www.emqx.io/docs/en/latest/configuration/logs.html"
 
   defp emqx_schema_mod(:enterprise), do: :emqx_enterprise_schema
   defp emqx_schema_mod(:community), do: :emqx_conf_schema

rebar.config.erl

@@ -352,16 +352,19 @@ overlay_vars(cloud, PkgType, Edition) ->
 overlay_vars_edition(ce) ->
     [
         {emqx_schema_mod, emqx_conf_schema},
+        {is_enterprise, "no"},
         {emqx_configuration_doc,
-            "https://www.emqx.io/docs/en/v5.0/configuration/configuration.html"},
-        {is_enterprise, "no"}
+            "https://www.emqx.io/docs/en/latest/configuration/configuration.html"},
+        {emqx_configuration_doc_log, "https://www.emqx.io/docs/en/latest/configuration/logs.html"}
     ];
 overlay_vars_edition(ee) ->
     [
         {emqx_schema_mod, emqx_enterprise_schema},
+        {is_enterprise, "yes"},
         {emqx_configuration_doc,
-            "https://docs.emqx.com/en/enterprise/v5.0/configuration/configuration.html"},
-        {is_enterprise, "yes"}
+            "https://docs.emqx.com/en/enterprise/latest/configuration/configuration.html"},
+        {emqx_configuration_doc_log,
+            "https://docs.emqx.com/en/enterprise/latest/configuration/logs.html"}
     ].
 
 %% vars per packaging type, bin(zip/tar.gz/docker) or pkg(rpm/deb)

rel/i18n/emqx_conf_schema.hocon

@@ -1,5 +1,18 @@
 emqx_conf_schema {
 
+log_root.desc =
+    """~
+    EMQX provides support for two primary log handlers: `file` and `console`, with an additional `audit` handler specifically designed to always direct logs to files.
+    The system's default log handling behavior can be configured via the environment variable `EMQX_DEFAULT_LOG_HANDLER`, which accepts the following settings:
+
+    - `file`: Directs log output exclusively to files.
+    - `console`: Channels log output solely to the console.
+
+    It's noteworthy that `EMQX_DEFAULT_LOG_HANDLER` is set to `file` when EMQX is initiated via systemd's `emqx.service` file.
+    In scenarios outside systemd initiation, `console` serves as the default log handler."""
+
+log_root.label = log
+
 common_handler_drop_mode_qlen.desc:
 """When the number of buffered log events is larger than this value, the new log events are dropped.
 When drop mode is activated or deactivated, a message is printed in the logs."""

scripts/spellcheck/dicts/emqx.txt

@@ -239,6 +239,7 @@ superset
 sys
 sysmem
 sysmon
+systemd
 tcp
 ticktime
 timeseries