From f47f5db52109f65987b2a053e333ebe62b11cc98 Mon Sep 17 00:00:00 2001 From: DDDHuang <44492639+DDDHuang@users.noreply.github.com> Date: Tue, 19 Apr 2022 10:53:35 +0800 Subject: [PATCH 1/2] fix: prometheus & statsd & topic rewrite docs --- .../i18n/emqx_auto_subscribe_api_i18n.conf | 23 ++++++ .../src/emqx_auto_subscribe_api.erl | 14 ++-- .../src/emqx_auto_subscribe_schema.erl | 2 +- .../i18n/emqx_modules_schema_i18n.conf | 74 +++++++++++++++++++ .../i18n/emqx_rewrite_api_i18n.conf | 25 +++++++ apps/emqx_modules/src/emqx_modules_schema.erl | 11 +-- apps/emqx_modules/src/emqx_rewrite_api.erl | 12 +-- .../i18n/emqx_prometheus_schema_i18n.conf | 33 +++++++++ .../src/emqx_prometheus_schema.erl | 21 +++--- .../i18n/emqx_statsd_schema_i18n.conf | 41 ++++++++++ apps/emqx_statsd/src/emqx_statsd_schema.erl | 12 +-- 11 files changed, 235 insertions(+), 33 deletions(-) create mode 100644 apps/emqx_auto_subscribe/i18n/emqx_auto_subscribe_api_i18n.conf create mode 100644 apps/emqx_modules/i18n/emqx_modules_schema_i18n.conf create mode 100644 apps/emqx_modules/i18n/emqx_rewrite_api_i18n.conf create mode 100644 apps/emqx_prometheus/i18n/emqx_prometheus_schema_i18n.conf create mode 100644 apps/emqx_statsd/i18n/emqx_statsd_schema_i18n.conf diff --git a/apps/emqx_auto_subscribe/i18n/emqx_auto_subscribe_api_i18n.conf b/apps/emqx_auto_subscribe/i18n/emqx_auto_subscribe_api_i18n.conf new file mode 100644 index 000000000..1a06afd4d --- /dev/null +++ b/apps/emqx_auto_subscribe/i18n/emqx_auto_subscribe_api_i18n.conf @@ -0,0 +1,23 @@ +emqx_auto_subscribe_api { + list_auto_subscribe_api { + desc { + en: """Get auto subscribe topic list""" + zh: """获取自动订阅主题列表""" + } + } + + update_auto_subscribe_api { + desc { + en: """Update auto subscribe topic list""" + zh: """更新自动订阅主题列表""" + } + } + + update_auto_subscribe_api_response_409 { + desc { + en: """Auto Subscribe topics max limit""" + zh: """超出自定订阅主题列表长度限制""" + } + } + +} diff --git a/apps/emqx_auto_subscribe/src/emqx_auto_subscribe_api.erl b/apps/emqx_auto_subscribe/src/emqx_auto_subscribe_api.erl index 7883193cf..51a8ca541 100644 --- a/apps/emqx_auto_subscribe/src/emqx_auto_subscribe_api.erl +++ b/apps/emqx_auto_subscribe/src/emqx_auto_subscribe_api.erl @@ -29,6 +29,7 @@ -define(EXCEED_LIMIT, 'EXCEED_LIMIT'). -define(BAD_REQUEST, 'BAD_REQUEST'). +-include_lib("hocon/include/hoconsc.hrl"). -include_lib("emqx/include/emqx_placeholder.hrl"). api_spec() -> @@ -41,20 +42,21 @@ schema("/mqtt/auto_subscribe") -> #{ 'operationId' => auto_subscribe, get => #{ - description => <<"Auto subscribe list">>, + description => ?DESC(list_auto_subscribe_api), responses => #{ 200 => hoconsc:ref(emqx_auto_subscribe_schema, "auto_subscribe") } }, put => #{ - description => <<"Update auto subscribe topic list">>, + description => ?DESC(update_auto_subscribe_api), 'requestBody' => hoconsc:ref(emqx_auto_subscribe_schema, "auto_subscribe"), responses => #{ 200 => hoconsc:ref(emqx_auto_subscribe_schema, "auto_subscribe"), - 400 => emqx_mgmt_util:error_schema( - <<"Request body required">>, [?BAD_REQUEST]), - 409 => emqx_mgmt_util:error_schema( - <<"Auto Subscribe topics max limit">>, [?EXCEED_LIMIT])}} + 409 => emqx_dashboard_swagger:error_codes( + [?EXCEED_LIMIT], + ?DESC(update_auto_subscribe_api_response_409)) + } + } }. %%%============================================================================================== diff --git a/apps/emqx_auto_subscribe/src/emqx_auto_subscribe_schema.erl b/apps/emqx_auto_subscribe/src/emqx_auto_subscribe_schema.erl index 0084e5f80..12bcc5a86 100644 --- a/apps/emqx_auto_subscribe/src/emqx_auto_subscribe_schema.erl +++ b/apps/emqx_auto_subscribe/src/emqx_auto_subscribe_schema.erl @@ -33,7 +33,7 @@ roots() -> fields("auto_subscribe") -> [ {topics, hoconsc:mk(hoconsc:array(hoconsc:ref(?MODULE, "topic")), - #{desc => "List of auto-subscribe topics."})} + #{desc => ?DESC(auto_subscribe)})} ]; fields("topic") -> diff --git a/apps/emqx_modules/i18n/emqx_modules_schema_i18n.conf b/apps/emqx_modules/i18n/emqx_modules_schema_i18n.conf new file mode 100644 index 000000000..128bb92b9 --- /dev/null +++ b/apps/emqx_modules/i18n/emqx_modules_schema_i18n.conf @@ -0,0 +1,74 @@ +emqx_modules_schema { + + rewrite { + desc { + en: """The topic rewriting function of EMQX supports rewriting topic A to topic B when the client subscribes to topics, publishes messages, and cancels subscriptions according to user-configured rules. +Each rewrite rule consists of three parts: subject filter, regular expression, and target expression. +Under the premise that the subject rewriting function is enabled, when EMQX receives a subject-based MQTT message such as a PUBLISH message, +it will use the subject of the message to sequentially match the subject filter part of the rule in the configuration file. If the match is successful, +the regular expression is used to extract the information in the subject, and then replaced with the target expression to form a new subject. +Variables in the format of $N can be used in the target expression to match the elements extracted from the regular expression. +The value of $N is the Nth element extracted from the regular expression. For example, $1 is the regular expression. The first element extracted by the expression. +It should be noted that EMQX uses reverse order to read the rewrite rules in the configuration file. +When a topic can match the topic filter of multiple topic rewrite rules at the same time, EMQX will only use the first rule it matches. Rewrite. +If the regular expression in this rule does not match the subject of the MQTT message, the rewriting will fail, and no other rules will be attempted for rewriting. +Therefore, users need to carefully design MQTT message topics and topic rewriting rules when using them.""" + zh: """EMQX 的主题重写功能支持根据用户配置的规则在客户端订阅主题、发布消息、取消订阅的时候将 A 主题重写为 B 主题。 +重写规则分为 Pub 规则和 Sub 规则，Pub 规则匹配 PUSHLISH 报文携带的主题，Sub 规则匹配 SUBSCRIBE、UNSUBSCRIBE 报文携带的主题。 +每条重写规则都由主题过滤器、正则表达式、目标表达式三部分组成。 +在主题重写功能开启的前提下，EMQX 在收到诸如 PUBLISH 报文等带有主题的 MQTT 报文时，将使用报文中的主题去依次匹配配置文件中规则的主题过滤器部分，一旦成功匹配，则使用正则表达式提取主题中的信息，然后替换至目标表达式以构成新的主题。 +目标表达式中可以使用 $N 这种格式的变量匹配正则表达中提取出来的元素，$N 的值为正则表达式中提取出来的第 N 个元素，比如 $1 即为正则表达式提取的第一个元素。 +需要注意的是，EMQX 使用倒序读取配置文件中的重写规则，当一条主题可以同时匹配多条主题重写规则的主题过滤器时，EMQX 仅会使用它匹配到的第一条规则进行重写，如果该条规则中的正则表达式与 MQTT 报文主题不匹配，则重写失败，不会再尝试使用其他的规则进行重写。 +因此用户在使用时需要谨慎的设计 MQTT 报文主题以及主题重写规则。""" + } + label { + en: """Topic Rewrite""" + zh: """主题重写""" + } + } + + tr_source_topic { + desc { + en: """Source topic, specified by the client.""" + zh: """源主题，客户端业务指定的主题""" + } + label { + en: """Source Topic""" + zh: """源主题""" + } + } + + tr_action { + desc { + en: """subscribe: Rewrite topic when client do subscribe. +publish: Rewrite topic when client do publish. +all: Both""" + zh: """subscribe：订阅时重写主题； +publish：发布时重写主题； +all：全部重写主题""" + } + label { + en: """Action""" + zh: """Action""" + } + } + + tr_re { + desc { + en: """Regular expressions""" + zh: """正则表达式""" + } + } + + tr_dest_topic { + desc { + en: """Destination topic.""" + zh: """目标主题。""" + } + label { + en: """Destination Topic""" + zh: """目标主题""" + } + } + +} diff --git a/apps/emqx_modules/i18n/emqx_rewrite_api_i18n.conf b/apps/emqx_modules/i18n/emqx_rewrite_api_i18n.conf new file mode 100644 index 000000000..2b36f78a5 --- /dev/null +++ b/apps/emqx_modules/i18n/emqx_rewrite_api_i18n.conf @@ -0,0 +1,25 @@ +emqx_rewrite_api { + + list_topic_rewrite_api { + desc { + en: """List all rewrite rules""" + zh: """列出全部主题重写规则""" + } + } + + update_topic_rewrite_api { + desc { + en: """Update all rewrite rules""" + zh: """更新全部主题重写规则""" + } + } + + + update_topic_rewrite_api_response_413 { + desc { + en: """Rules count exceed max limit""" + zh: """超出主题重写规则数量上限""" + } + } + +} diff --git a/apps/emqx_modules/src/emqx_modules_schema.erl b/apps/emqx_modules/src/emqx_modules_schema.erl index a74406488..fd166c89e 100644 --- a/apps/emqx_modules/src/emqx_modules_schema.erl +++ b/apps/emqx_modules/src/emqx_modules_schema.erl @@ -16,6 +16,7 @@ -module(emqx_modules_schema). +-include_lib("hocon/include/hoconsc.hrl"). -include_lib("typerefl/include/types.hrl"). -behaviour(hocon_schema). @@ -50,17 +51,17 @@ fields("rewrite") -> {action, sc( hoconsc:enum([subscribe, publish, all]), - #{desc => <<"Action">>, example => publish} + #{desc => ?DESC(tr_action), example => publish} )}, {source_topic, sc( binary(), - #{desc => <<"Origin Topic">>, example => "x/#"} + #{desc => ?DESC(tr_source_topic), example => "x/#"} )}, {dest_topic, sc( binary(), - #{desc => <<"Destination Topic">>, example => "z/y/$1"} + #{desc => ?DESC(tr_dest_topic), example => "z/y/$1"} )}, {re, fun regular_expression/1} ]; @@ -72,14 +73,14 @@ desc("telemetry") -> desc("delayed") -> "Settings for the delayed module."; desc("rewrite") -> - "Rewrite rule."; + ?DESC(rewrite); desc("topic_metrics") -> ""; desc(_) -> undefined. regular_expression(type) -> binary(); -regular_expression(desc) -> "Regular expressions"; +regular_expression(desc) -> ?DESC(tr_re); regular_expression(example) -> "^x/y/(.+)$"; regular_expression(validator) -> fun is_re/1; regular_expression(_) -> undefined. diff --git a/apps/emqx_modules/src/emqx_rewrite_api.erl b/apps/emqx_modules/src/emqx_rewrite_api.erl index 264a36a06..ffb5aace0 100644 --- a/apps/emqx_modules/src/emqx_rewrite_api.erl +++ b/apps/emqx_modules/src/emqx_rewrite_api.erl @@ -16,6 +16,8 @@ -module(emqx_rewrite_api). -behaviour(minirest_api). + +-include_lib("hocon/include/hoconsc.hrl"). -include_lib("typerefl/include/types.hrl"). -include("emqx_modules.hrl"). @@ -38,16 +40,16 @@ schema("/mqtt/topic_rewrite") -> 'operationId' => topic_rewrite, get => #{ tags => ?API_TAG_MQTT, - description => <<"List rewrite topic.">>, + description => ?DESC(list_topic_rewrite_api), responses => #{ 200 => hoconsc:mk( hoconsc:array(hoconsc:ref(emqx_modules_schema, "rewrite")), - #{desc => <<"List all rewrite rules">>} + #{desc => ?DESC(list_topic_rewrite_api)} ) } }, put => #{ - description => <<"Update rewrite topic">>, + description => ?DESC(update_topic_rewrite_api), tags => ?API_TAG_MQTT, 'requestBody' => hoconsc:mk( hoconsc:array( @@ -58,11 +60,11 @@ schema("/mqtt/topic_rewrite") -> responses => #{ 200 => hoconsc:mk( hoconsc:array(hoconsc:ref(emqx_modules_schema, "rewrite")), - #{desc => <<"Update rewrite topic success.">>} + #{desc => ?DESC(update_topic_rewrite_api)} ), 413 => emqx_dashboard_swagger:error_codes( [?EXCEED_LIMIT], - <<"Rules count exceed max limit">> + ?DESC(update_topic_rewrite_api_response_413) ) } } diff --git a/apps/emqx_prometheus/i18n/emqx_prometheus_schema_i18n.conf b/apps/emqx_prometheus/i18n/emqx_prometheus_schema_i18n.conf new file mode 100644 index 000000000..f49d8d00c --- /dev/null +++ b/apps/emqx_prometheus/i18n/emqx_prometheus_schema_i18n.conf @@ -0,0 +1,33 @@ +emqx_prometheus_schema { + + prometheus { + desc { + en: """Settings for reporting metrics to Prometheus""" + zh: """Prometheus 监控数据推送""" + } + label { + en: """Prometheus""" + zh: """Prometheus""" + } + } + + push_gateway_server { + desc { + en: """URL of Prometheus server""" + zh: """Prometheus 服务器地址""" + } + } + + interval { + desc { + en: """Data reporting interval, in milliseconds.""" + zh: """数据推送间隔，单位 毫秒""" + } + } + enable { + desc { + en: """Turn Prometheus data pushing on or off""" + zh: """开启或关闭 Prometheus 数据推送""" + } + } +} diff --git a/apps/emqx_prometheus/src/emqx_prometheus_schema.erl b/apps/emqx_prometheus/src/emqx_prometheus_schema.erl index 6e6ebd4b9..98f9a519b 100644 --- a/apps/emqx_prometheus/src/emqx_prometheus_schema.erl +++ b/apps/emqx_prometheus/src/emqx_prometheus_schema.erl @@ -15,6 +15,7 @@ %%-------------------------------------------------------------------- -module(emqx_prometheus_schema). +-include_lib("hocon/include/hoconsc.hrl"). -include_lib("typerefl/include/types.hrl"). -behaviour(hocon_schema). @@ -30,25 +31,25 @@ namespace() -> "prometheus". roots() -> ["prometheus"]. fields("prometheus") -> - [ {push_gateway_server, sc(string(), + [ + {push_gateway_server, sc(string(), #{ default => "http://127.0.0.1:9091" , required => true - , desc => "URL of Prometheus pushgateway." - })} - , {interval, sc(emqx_schema:duration_ms(), + , desc => ?DESC(push_gateway_server) + })}, + {interval, sc(emqx_schema:duration_ms(), #{ default => "15s" , required => true - , desc => "Data reporting interval in milliseconds." - })} - , {enable, sc(boolean(), + , desc => ?DESC(interval) + })}, + {enable, sc(boolean(), #{ default => false , required => true - , desc => "Enable reporting of metrics via Prometheus Pushgateway." + , desc => ?DESC(enable) })} ]. -desc("prometheus") -> - "Settings for reporting metrics to Prometheus pushgateway."; +desc("prometheus") -> ?DESC(prometheus); desc(_) -> undefined. diff --git a/apps/emqx_statsd/i18n/emqx_statsd_schema_i18n.conf b/apps/emqx_statsd/i18n/emqx_statsd_schema_i18n.conf new file mode 100644 index 000000000..bc0e1d3b0 --- /dev/null +++ b/apps/emqx_statsd/i18n/emqx_statsd_schema_i18n.conf @@ -0,0 +1,41 @@ +emqx_statsd_schema { + + statsd { + desc { + en: """Settings for reporting metrics to Statsd""" + zh: """Statsd 监控数据推送""" + } + label { + en: """Statsd""" + zh: """Statsd""" + } + } + + server { + desc { + en: """URL of Statsd server""" + zh: """Statsd 服务器地址""" + } + } + + sample_interval { + desc { + en: """Data collection interval in second.""" + zh: """数据收集间隔，单位 毫秒""" + } + } + + flush_interval { + desc { + en: """Data reporting interval, in second.""" + zh: """数据推送间隔，单位 毫秒""" + } + } + + enable { + desc { + en: """Turn Statsd data pushing on or off""" + zh: """开启或关闭 Statsd 数据推送""" + } + } +} diff --git a/apps/emqx_statsd/src/emqx_statsd_schema.erl b/apps/emqx_statsd/src/emqx_statsd_schema.erl index 7566e6255..df98e4df1 100644 --- a/apps/emqx_statsd/src/emqx_statsd_schema.erl +++ b/apps/emqx_statsd/src/emqx_statsd_schema.erl @@ -16,6 +16,7 @@ -module(emqx_statsd_schema). +-include_lib("hocon/include/hoconsc.hrl"). -include_lib("typerefl/include/types.hrl"). -behaviour(hocon_schema). @@ -37,34 +38,33 @@ fields("statsd") -> [ {enable, hoconsc:mk(boolean(), #{ default => false , required => true - , desc => "Enable statsd" + , desc => ?DESC(enable) })} , {server, fun server/1} , {sample_time_interval, fun sample_interval/1} , {flush_time_interval, fun flush_interval/1} ]. -desc("statsd") -> - "Configuration related to reporting metrics to statsd."; +desc("statsd") -> ?DESC(statsd); desc(_) -> undefined. server(type) -> emqx_schema:ip_port(); server(required) -> true; server(default) -> "127.0.0.1:8125"; -server(desc) -> "URL of the statsd gateway."; +server(desc) -> ?DESC(?FUNCTION_NAME); server(_) -> undefined. sample_interval(type) -> emqx_schema:duration_ms(); sample_interval(required) -> true; sample_interval(default) -> "10s"; -sample_interval(desc) -> "Data collection interval in milliseconds."; +sample_interval(desc) -> ?DESC(?FUNCTION_NAME); sample_interval(_) -> undefined. flush_interval(type) -> emqx_schema:duration_ms(); flush_interval(required) -> true; flush_interval(default) -> "10s"; -flush_interval(desc) -> "Flush interval in milliseconds."; +flush_interval(desc) -> ?DESC(?FUNCTION_NAME); flush_interval(_) -> undefined. to_ip_port(Str) -> From 330e302a7cac36a5926fab714902a4dfa155c7e0 Mon Sep 17 00:00:00 2001 From: DDDHuang <44492639+DDDHuang@users.noreply.github.com> Date: Tue, 19 Apr 2022 11:28:50 +0800 Subject: [PATCH 2/2] fix: better atom name --- apps/emqx_auto_subscribe/i18n/emqx_auto_subscribe_api_i18n.conf | 2 +- apps/emqx_auto_subscribe/src/emqx_auto_subscribe_api.erl | 2 +- apps/emqx_modules/i18n/emqx_rewrite_api_i18n.conf | 2 +- apps/emqx_modules/src/emqx_rewrite_api.erl | 2 +- 4 files changed, 4 insertions(+), 4 deletions(-) diff --git a/apps/emqx_auto_subscribe/i18n/emqx_auto_subscribe_api_i18n.conf b/apps/emqx_auto_subscribe/i18n/emqx_auto_subscribe_api_i18n.conf index 1a06afd4d..b8d043e9a 100644 --- a/apps/emqx_auto_subscribe/i18n/emqx_auto_subscribe_api_i18n.conf +++ b/apps/emqx_auto_subscribe/i18n/emqx_auto_subscribe_api_i18n.conf @@ -13,7 +13,7 @@ emqx_auto_subscribe_api { } } - update_auto_subscribe_api_response_409 { + update_auto_subscribe_api_response409 { desc { en: """Auto Subscribe topics max limit""" zh: """超出自定订阅主题列表长度限制""" diff --git a/apps/emqx_auto_subscribe/src/emqx_auto_subscribe_api.erl b/apps/emqx_auto_subscribe/src/emqx_auto_subscribe_api.erl index 51a8ca541..48ec92fb4 100644 --- a/apps/emqx_auto_subscribe/src/emqx_auto_subscribe_api.erl +++ b/apps/emqx_auto_subscribe/src/emqx_auto_subscribe_api.erl @@ -54,7 +54,7 @@ schema("/mqtt/auto_subscribe") -> 200 => hoconsc:ref(emqx_auto_subscribe_schema, "auto_subscribe"), 409 => emqx_dashboard_swagger:error_codes( [?EXCEED_LIMIT], - ?DESC(update_auto_subscribe_api_response_409)) + ?DESC(update_auto_subscribe_api_response409)) } } }. diff --git a/apps/emqx_modules/i18n/emqx_rewrite_api_i18n.conf b/apps/emqx_modules/i18n/emqx_rewrite_api_i18n.conf index 2b36f78a5..91f15cb8c 100644 --- a/apps/emqx_modules/i18n/emqx_rewrite_api_i18n.conf +++ b/apps/emqx_modules/i18n/emqx_rewrite_api_i18n.conf @@ -15,7 +15,7 @@ emqx_rewrite_api { } - update_topic_rewrite_api_response_413 { + update_topic_rewrite_api_response413 { desc { en: """Rules count exceed max limit""" zh: """超出主题重写规则数量上限""" diff --git a/apps/emqx_modules/src/emqx_rewrite_api.erl b/apps/emqx_modules/src/emqx_rewrite_api.erl index ffb5aace0..a62b2a9b2 100644 --- a/apps/emqx_modules/src/emqx_rewrite_api.erl +++ b/apps/emqx_modules/src/emqx_rewrite_api.erl @@ -64,7 +64,7 @@ schema("/mqtt/topic_rewrite") -> ), 413 => emqx_dashboard_swagger:error_codes( [?EXCEED_LIMIT], - ?DESC(update_topic_rewrite_api_response_413) + ?DESC(update_topic_rewrite_api_response413) ) } }