From ef9903733574e144480e24f776e79a347ef9f339 Mon Sep 17 00:00:00 2001 From: "Zaiming (Stone) Shi" Date: Tue, 27 Feb 2024 09:08:34 +0100 Subject: [PATCH] docs: add log docs --- apps/emqx/etc/emqx.conf | 20 ++++++++++++++++++++ apps/emqx_conf/src/emqx_conf_schema.erl | 10 ++++++---- bin/emqx | 2 +- mix.exs | 20 ++++++++++++++------ rebar.config.erl | 11 +++++++---- rel/i18n/emqx_conf_schema.hocon | 13 +++++++++++++ scripts/spellcheck/dicts/emqx.txt | 1 + 7 files changed, 62 insertions(+), 15 deletions(-) diff --git a/apps/emqx/etc/emqx.conf b/apps/emqx/etc/emqx.conf index e69de29bb..ce9612e87 100644 --- a/apps/emqx/etc/emqx.conf +++ b/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 + # } +} + diff --git a/apps/emqx_conf/src/emqx_conf_schema.erl b/apps/emqx_conf/src/emqx_conf_schema.erl index d99538f2b..1e3e14744 100644 --- a/apps/emqx_conf/src/emqx_conf_schema.erl +++ b/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"]; diff --git a/bin/emqx b/bin/emqx index 3ee57288f..c7ec11c3b 100755 --- a/bin/emqx +++ b/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" diff --git a/mix.exs b/mix.exs index 598b770b8..55c479e47 100644 --- a/mix.exs +++ b/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 diff --git a/rebar.config.erl b/rebar.config.erl index 4600a4a83..b340e7eea 100644 --- a/rebar.config.erl +++ b/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) diff --git a/rel/i18n/emqx_conf_schema.hocon b/rel/i18n/emqx_conf_schema.hocon index 4477b6a54..7469ddd22 100644 --- a/rel/i18n/emqx_conf_schema.hocon +++ b/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.""" diff --git a/scripts/spellcheck/dicts/emqx.txt b/scripts/spellcheck/dicts/emqx.txt index c2f5f54ef..bfa63e349 100644 --- a/scripts/spellcheck/dicts/emqx.txt +++ b/scripts/spellcheck/dicts/emqx.txt @@ -239,6 +239,7 @@ superset sys sysmem sysmon +systemd tcp ticktime timeseries