fix: schema and desc for time_offset of the log handlers

2022-06-09 17:04:40 +08:00 · 2022-06-09 17:04:40 +08:00 · b0cd83254d
parent 0aab063dd5
commit b0cd83254d
2 changed files with 78 additions and 66 deletions
--- a/apps/emqx_conf/i18n/emqx_conf_schema.conf
+++ b/apps/emqx_conf/i18n/emqx_conf_schema.conf
@ -940,8 +940,8 @@ until the RPC connection is considered lost."""

  log_file_handlers {
    desc {
-      en: """Key-value list of file-based log handlers."""
-      zh: """需要持久化到文件的日志处理进程列表。默认只有 default 一个处理进程。"""
+      en: """file-based log handlers."""
+      zh: """输出到文件的日志处理进程列表"""
    }
    label {
      en: "File Handler"
@ -962,21 +962,39 @@ until the RPC connection is considered lost."""

  common_handler_level {
    desc {
-      en: """Global log level. This includes the primary log level and all log handlers."""
-      zh: """设置日志级别。 默认为warning。"""
+      en: """
+The log level for the current log handler.
+Defaults to warning.
+"""
+      zh: """
+当前日志处理进程的日志级别。
+默认为 warning 级别。
+"""
    }
    label {
-      en: "Global Log Level"
+      en: "Log Level"
      zh: "日志级别"
    }
  }

  common_handler_time_offset {
    desc {
-      en: """The time offset to be used when formatting the timestamp."""
-      zh: """日志格式中的时间戳，使用的时间偏移量。默认使用系统时区system，当为utc为无时间偏移量
-为具体的N(1-24)数字时，则代表时间偏移量+N。
-      """
+      en: """
+The time offset to be used when formatting the timestamp.
+Can be one of:
+  - <code>system</code>: the time offset used by the local system
+  - <code>utc</code>: the UTC time offset
+  - <code>+-[hh]:[mm]</code>: user specified time offset, such as "-02:00" or "+00:00"
+Defaults to: <code>system</code>.
+"""
+      zh: """
+日志中的时间戳使用的时间偏移量。
+可选值为：
+  - <code>system</code>: 本地系统使用的时区偏移量
+  - <code>utc</code>: 0 时区的偏移量
+  - <code>+-[hh]:[mm]</code>: 自定义偏移量，比如 "-02:00" 或者 "+00:00"
+默认值为本地系统的时区偏移量：<code>system</code>。
+"""
    }
    label {
      en: "Time Offset"
@ -997,12 +1015,12 @@ until the RPC connection is considered lost."""

  common_handler_formatter {
    desc {
-      en: """Choose log format. <code>text</code> for free text, and <code>json</code> for structured logging."""
-      zh: """选择日志格式。 <code>text</code> 用于纯文本，<code>json</code> 用于结构化日志记录。"""
+      en: """Choose log formatter. <code>text</code> for free text, and <code>json</code> for structured logging."""
+      zh: """选择日志格式类型。 <code>text</code> 用于纯文本，<code>json</code> 用于结构化日志记录。"""
    }
    label {
-      en: "Log Format"
-      zh: "日志格式"
+      en: "Log Formatter"
+      zh: "日志格式类型"
    }
  }

@ -1037,8 +1055,8 @@ asynchronous operation is resumed.
 默认为100条信息，当等待的日志事件大于100条时，就开始同步处理日志。"""
    }
    label {
-      en: "Sync Mode Max Log Events"
-      zh: "异步模式最大事件数"
+      en: "Queue Length before Entering Sync Mode"
+      zh: "进入异步模式的队列长度"
    }
  }

@ -1047,7 +1065,7 @@ asynchronous operation is resumed.
      en: """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."""
      zh: """当缓冲的日志事件数大于此值时，新的日志事件将被丢弃。起到过载保护的功能。
-为了使过载保护算法正常工作必须要：<code> sync_mode_qlen =< drop_mode_qlen =< flush_qlen <\code> 且 drop_mode_qlen > 1
+为了使过载保护算法正常工作必须要：<code> sync_mode_qlen =< drop_mode_qlen =< flush_qlen </code> 且 drop_mode_qlen > 1
 要禁用某些模式，请执行以下操作。
 - 如果sync_mode_qlen被设置为0，所有的日志事件都被同步处理。也就是说，异步日志被禁用。
 - 如果sync_mode_qlen被设置为与drop_mode_qlen相同的值，同步模式被禁用。也就是说，处理程序总是以异步模式运行，除非调用drop或flushing。
@ -1055,31 +1073,36 @@ When drop mode is activated or deactivated, a message is printed in the logs."""
 """
    }
    label {
-      en: "Drop Mode Max Log Events"
-      zh: "缓存最大日志事件数"
+      en: "Queue Length before Entering Drop Mode"
+      zh: "进入丢弃模式的队列长度"
    }
  }

  common_handler_flush_qlen {
    desc {
-      en: """If the number of buffered log events grows larger than this threshold, a flush (delete) operation takes place. To flush events, the handler discards the buffered log messages without logging."""
-      zh: """如果缓冲日志事件的数量增长大于此阈值，则会发生刷新（删除）操作。 日志处理进程会丢弃缓冲的日志消息。
+      en: """If the number of buffered log events grows larger than this threshold, a flush (delete) operation takes place.
+To flush events, the handler discards the buffered log messages without logging."""
+      zh: """如果缓冲日志事件的数量增长大于此阈值，则会发生冲刷（删除）操作。 日志处理进程会丢弃缓冲的日志消息。
 来缓解自身不会由于内存瀑涨而影响其它业务进程。日志内容会提醒有多少事件被删除。"""
    }
    label {
      en: "Flush Threshold"
-      zh: "刷新阈值"
+      zh: "冲刷阈值"
    }
  }

  common_handler_supervisor_reports {
    desc {
-      en: """Type of supervisor reports that are logged.
- - `error`: only log errors in the Erlang processes.
- - `progress`: log process startup."""
-      zh: """ supervisor 报告的类型。默认为 error 类型。
-  - `error`：仅记录 Erlang 进程中的错误。
-  - `progress`：除了 error 信息外，还需要记录进程启动的详细信息。"""
+      en: """
+Type of supervisor reports that are logged. Defaults to <code>error</code>
+  - <code>error</code>: only log errors in the Erlang processes.
+  - <code>progress</code>: log process startup.
+"""
+      zh: """
+Supervisor 报告的类型。默认为 error 类型。
+  - <code>error</code>：仅记录 Erlang 进程中的错误。
+  - <code>progress</code>：除了 error 信息外，还需要记录进程启动的详细信息。
+"""
    }
    label {
      en: "Report Type"
@ -1122,17 +1145,6 @@ When drop mode is activated or deactivated, a message is printed in the logs."""
    }
  }

-  log_error_logger {
-    desc {
-      en: """Keep error_logger silent."""
-      zh: """让 error_logger 日志处理进程关闭，防止一条异常信息被记录多次。"""
-    }
-    label {
-      en: "error_logger"
-      zh: "error_logger"
-    }
-  }
-
  log_rotation_enable {
    desc {
      en: """Enable log rotation feature."""
@ -1170,12 +1182,12 @@ When drop mode is activated or deactivated, a message is printed in the logs."""

  log_overload_kill_mem_size {
    desc {
-      en: """Maximum memory size that the handler process is allowed to use."""
-      zh: """处理进程允许使用的最大内存。"""
+      en: """Maximum memory size that the log handler process is allowed to use."""
+      zh: """日志处理进程允许使用的最大内存。"""
    }
    label {
-      en: "Handler Allowed Max Memory Size"
-      zh: "处理进程允许使用的最大内存"
+      en: "Log Handler Max Memory Size"
+      zh: "日志处理进程允许使用的最大内存"
    }
  }

@ -1225,8 +1237,8 @@ When drop mode is activated or deactivated, a message is printed in the logs."""

  log_burst_limit_window_time {
    desc {
-      en: """See `max_count`."""
-      zh: """参考 `max_count`。"""
+      en: """See <code>max_count</code>."""
+      zh: """参考 <code>max_count</code>。"""
    }
    label {
      en: "Window Time"
--- a/apps/emqx_conf/src/emqx_conf_schema.erl
+++ b/apps/emqx_conf/src/emqx_conf_schema.erl
@ -790,16 +790,6 @@ fields("log") ->
            sc(
                map(name, ?R_REF("log_file_handler")),
                #{desc => ?DESC("log_file_handlers")}
-            )},
-        {"error_logger",
-            sc(
-                atom(),
-                #{
-                    mapping => "kernel.error_logger",
-                    default => silent,
-                    'readOnly' => true,
-                    desc => ?DESC("log_error_logger")
-                }
            )}
    ];
 fields("console_handler") ->
@ -811,7 +801,7 @@ fields("log_file_handler") ->
                file(),
                #{
                    desc => ?DESC("log_file_handler_file"),
-                    validator => fun file_location/1
+                    validator => fun validate_file_location/1
                }
            )},
        {"rotation",
@ -955,7 +945,8 @@ translation("ekka") ->
 translation("kernel") ->
    [
        {"logger_level", fun tr_logger_level/1},
-        {"logger", fun tr_logger/1}
+        {"logger", fun tr_logger/1},
+        {"error_logger", fun(_) -> silent end}
    ];
 translation("emqx") ->
    [
@ -1088,7 +1079,8 @@ log_handler_common_confs(Enable) ->
                string(),
                #{
                    default => "system",
-                    desc => ?DESC("common_handler_time_offset")
+                    desc => ?DESC("common_handler_time_offset"),
+                    validator => fun validate_time_offset/1
                }
            )},
        {"chars_limit",
@ -1326,14 +1318,22 @@ emqx_schema_high_prio_roots() ->
            )},
    lists:keyreplace("authorization", 1, Roots, Authz).

-define(VALID_FILE, "^[/\_a-zA-Z0-9\.\-]*$").
-file_location(File) ->
-    Error = {error, "Invalid file name: " ++ ?VALID_FILE},
-    try
-        case re:run(File, ?VALID_FILE) of
-            nomatch -> Error;
-            _ -> ok
-        end
+validate_file_location(File) ->
+    ValidFile = "^[/\\_a-zA-Z0-9\\.\\-]*$",
+    Error = "Invalid file name: " ++ ValidFile,
+    validator_string_re(File, ValidFile, Error).
+
+validate_time_offset(Offset) ->
+    ValidTimeOffset = "^([\\-\\+][0-1][0-9]:[0-6][0-9]|system|utc)$",
+    Error =
+        "Invalid time offset, should be of format: +[hh]:[mm], "
+        "i.e. +08:00 or -02:00",
+    validator_string_re(Offset, ValidTimeOffset, Error).
+
+validator_string_re(Val, RE, Error) ->
+    try re:run(Val, RE) of
+        nomatch -> {error, Error};
+        _ -> ok
    catch
-        _:_ -> Error
+        _:_ -> {error, Error}
    end.