Merge pull request #65 from emqx/dev/autorate-docs

doc: Include list of autorates and metrics in the documentation

Makefile

@@ -47,6 +47,7 @@ $(WWW): $(DOCBOOK) $(XSLTNG)
 	cd $$(dirname $@) ;\
 	java -jar $(CURDIR)/$(XSLTNG) resource-base-uri='./' chunk-output-base-uri='./' \
                                 verbatim-syntax-highlight-languages='bash erlang' \
+                                mathml-js='https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-mml-chtml.js' \
                                 chunk=index.html persistent-toc=true chunk-nav=true $(CURDIR)/$<
 	cp -R _build/lee_doc/docbook-xslTNG-2.1.2/resources/* $$(dirname $@)
 

doc/src/schema.adoc

@@ -48,6 +48,7 @@ For example the following command can automatically adjust the rate of connectio
 
 Autorate configuration can be referred by id.
 This value must be equal to one of the elements returned by `emqttb @ls autorate` command.
+Full list is also available in <<autorate>>
 
 
 [id=autorate._.speed]
@@ -61,6 +62,7 @@ Note: by default this parameter is set to 0 for each autorate, effectively locki
 
 This parameter specifies ID of the metric that senses pressure on the SUT and serves as the process variable (PV).
 Its value must be equal to one of the metric IDs returned by `emqttb @ls metric` command.
+Full list can be also found in <<metrics>>.
 
 [id=autorate._.setpoint]
 == Setpoint
@@ -313,27 +315,30 @@ The following substitutions are supported:
 
 How often the clients will send `PING` MQTT message to the broker on idle connections.
 
+[id=autorate._.scram.enabled]
+== SCRAM
+Normally, autorate adjusts the control variable gradually.
+However, sometimes the system under test becomes overloaded suddenly, and in this case slowly decreasing the pressure may not be efficient enough.
+To combat this situation, `emqttb` has "SCRAM" mechanism, that immediately resets the control variable to a <<value.autorate.$$_$$.scram.override,configured safe value>>.
+This happens when the value of process variable exceeds the <<value.autorate.$$_$$.scram.threshold,threshold>>.
 
-[id=groups._.scram.threshold]
-== Maximum unacked CONNECT packets
-`emqttb` can automatically slow down creating new workers in a group when the broker is unable to accept connections in real time.
-
-`emqttb` keeps track of the number of un-acked `CONNECT` packets, and once becomes larger than the threshold,
-the group temporarily enters "SCRAM" mode where
-it overrides the rate to the <<value.groups.$$_$$.scram.override,specified value>>.
 SCRAM mode remains in effect until the number of pending connections becomes less than
-_threshold_ * <<value.groups.$$_$$.scram.hysteresis,hystersis>> / 100.
+_threshold_ * <<value.autorate.$$_$$.scram.hysteresis,hystersis>> / 100.
+
+
+[id=autorate._.scram.threshold]
+== SCRAM threshold
 
-[id=groups._.scram.override]
+
+[id=autorate._.scram.override]
 == SCRAM rate override
-Replace whatever configured (or calculated via autorate) connection rate value with this value when broker is not keeping up with the new connections.
+Replace configured (or calculated via autorate) value of the control variable with this value when the system under test is not keeping up with the load.
 
 
-[id=groups._.scram.hysteresis]
+[id=autorate._.scram.hysteresis]
 == SCRAM hysteresis
 It's not desirable to switch between normal and SCRAM connection rate too often.
 
-
 [id=autorate._.update_interval]
 == How often autorate is updated
 

src/framework/emqttb_autorate.erl

@@ -1,5 +1,5 @@
 %%--------------------------------------------------------------------
-%% Copyright (c) 2022-2023 EMQ Technologies Co., Ltd. All Rights Reserved.
+%% Copyright (c) 2022-2024 EMQ Technologies Co., Ltd. All Rights Reserved.
 %%
 %% Licensed under the Apache License, Version 2.0 (the "License");
 %% you may not use this file except in compliance with the License.
@@ -29,7 +29,7 @@
 %% gen_server callbacks:
 -export([init/1, handle_call/3, handle_cast/2, handle_info/2]).
 %% lee_metatype callbacks:
--export([names/1, metaparams/1, meta_validate/2, validate_node/5]).
+-export([names/1, metaparams/1, meta_validate/2, validate_node/5, description/3]).
 
 %% internal exports:
 -export([start_link/1, model/0, from_model/1]).
@@ -284,6 +284,18 @@ from_model(Key) ->
   #mnode{metaparams = #{autorate_id := Id}} = lee_model:get(Key, ?MYMODEL),
   Id.
 
+description(autorate = MT, Model, _Options) ->
+  Chapter = autorate,
+  Content = [begin
+               #mnode{metaparams = Attrs} = lee_model:get(Key, Model),
+               Title = atom_to_list(?m_attr(autorate, autorate_id, Attrs)),
+               lee_doc:refer_value(Model, Chapter, Key, Title)
+             end || Key <- lee_model:get_metatype_index(MT, Model)
+            ],
+  lee_doc:chapter(MT, "Automatically adjusted values", Content);
+description(_, _, _) ->
+  [].
+
 %%================================================================================
 %% gen_server callbacks
 %%================================================================================

src/metrics/emqttb_metrics.erl

@@ -1,5 +1,5 @@
 %%--------------------------------------------------------------------
-%% Copyright (c) 2022-2023 EMQ Technologies Co., Ltd. All Rights Reserved.
+%% Copyright (c) 2022-2024 EMQ Technologies Co., Ltd. All Rights Reserved.
 %%
 %% Licensed under the Apache License, Version 2.0 (the "License");
 %% you may not use this file except in compliance with the License.
@@ -30,7 +30,7 @@
 -export([init/1, handle_call/3, handle_cast/2, handle_info/2, terminate/2]).
 
 %% lee_metatype callbacks:
--export([names/1, metaparams/1, meta_validate/2, validate_node/5]).
+-export([names/1, metaparams/1, meta_validate/2, validate_node/5, description/3]).
 
 %% internal exports:
 -export([start_link/0]).
@@ -218,6 +218,20 @@ validate_node(metric_id, Model, Data, Key, _) ->
 validate_node(metric, _, _, _, _) ->
   {[], []}.
 
+description(metric = MT, Model, _Options) ->
+  Chapter = metrics,
+  Content = [begin
+               #mnode{metaparams = MPs} = lee_model:get(Key, Model),
+               Oneliner = ?m_attr(metric, oneliner, MPs, ""),
+               {refsection, [{'xml:id', lee_doc:format_key(Chapter, Key)}],
+                [ {title, [lee_lib:term_to_string(Key)]}
+                , {para, [Oneliner]}
+                ]}
+             end || Key <- lee_model:get_metatype_index(MT, Model)],
+  lee_doc:chapter(Chapter, "Metrics", Content);
+description(_, _, _) ->
+  [].
+
 ls(Model) ->
   lee_model:get_metatype_index(metric, Model).