### Quick start: subscribe scenario with full arguments Source: https://github.com/emqx/emqttb/blob/master/README.adoc Starts 10 clients subscribing to wildcard topic 't/#', with 10ms connection interval, running for 30s. Uses @sub and @g. ```bash emqttb --loiter 30s \ @sub --topic 't/#' --conninterval 10ms --num-clients 10 \ @g --host 127.0.0.1 ``` -------------------------------- ### start_link/0 - Start pushgateway gen_server Source: https://github.com/emqx/emqttb/blob/master/_autodocs/api-reference/emqttb_grafana.md Starts the emqttb_pushgw gen_server locally. init/1 starts the collection timer using [metrics, pushgateway, interval]. ```erlang start_link() -> gen_server:start_link({local, ?MODULE}, ?MODULE, [], []). ``` -------------------------------- ### start_link/0 Source: https://github.com/emqx/emqttb/blob/master/_autodocs/api-reference/emqttb_metrics.md Starts the metrics server. init/1 walks the model's [metric] metatype index, creates every declared metric, and starts a 100 ms tick. ```erlang start_link() -> gen_server:start_link({local, ?SERVER}, ?MODULE, [], []). ``` -------------------------------- ### Quick start: publish scenario with full arguments Source: https://github.com/emqx/emqttb/blob/master/README.adoc Starts 100 clients connecting to localhost with 10ms pause, publishing 1kb messages every 10ms to topic 't/%clientid%', running for 30s. Uses the @pub action and @g group configuration. ```bash emqttb --loiter 30s \ @pub --topic 't/%n' --conninterval 10ms --pubinterval 10ms --num-clients 100 --size 1kb \ @g --host 127.0.0.1 ``` -------------------------------- ### emqttb_app:start/2 boot sequence Source: https://github.com/emqx/emqttb/blob/master/_autodocs/api-reference/emqttb.md OTP application start callback that boots the emqttb tool. It loads the configuration model and configuration, starts the top-level supervisor, runs autorates and scenarios, annotates Grafana, and calls post_init. The function returns the supervisor pid. ```erlang start(_StartType, _StartArgs) -> emqttb_conf:load_model(), Sup = emqttb_sup:start_link(), emqttb_conf:load_conf(), maybe_perform_special_action(), emqttb_autorate:create_autorates(), emqttb_scenario:run_scenarios(), CLIArgs = application:get_env(?APP, cli_args, []), emqttb_grafana:annotate(["Start emqttb " | lists:join($ , CLIArgs)]), post_init(), Sup. ``` -------------------------------- ### start_link/0 Source: https://github.com/emqx/emqttb/blob/master/_autodocs/api-reference/emqttb_metrics.md Starts the metrics server. It initializes all metrics declared in the model and starts a 100 ms tick. ```APIDOC ## start_link/0 ### Description Starts the metrics server. It initializes all metrics declared in the model and starts a 100 ms tick. ### Function Signature ```erlang start_link() -> gen_server:start_link({local, ?SERVER}, ?MODULE, [], []). ``` ### Returns - `{ok, pid()}` - The pid of the started server. ``` -------------------------------- ### run/1 - Start a scenario Source: https://github.com/emqx/emqttb/blob/master/_autodocs/api-reference/emqttb_scenario.md Starts a scenario via the supervisor. Returns ok and is idempotent. ```erlang -spec run(emqttb:scenario()) -> ok. run(Name) -> emqttb_scenarios_sup:run(Name). ``` -------------------------------- ### start_link/0 (emqttb_pushgw) Source: https://github.com/emqx/emqttb/blob/master/_autodocs/api-reference/emqttb_grafana.md Starts the pushgateway gen_server. Called by emqttb_app:post_init/0 when pushgateway is enabled. ```APIDOC ## start_link/0 (emqttb_pushgw) ### Description Starts the pushgateway gen_server. Called by emqttb_app:post_init/0 when pushgateway is enabled. ### Method Erlang function ### Endpoint start_link() ### Returns `{ok, pid()}` ``` -------------------------------- ### Quick start: combined pub and sub scenarios Source: https://github.com/emqx/emqttb/blob/master/README.adoc Combines the publish and subscribe scenarios in a single command, running both concurrently for 30s. ```bash emqttb -L 30s @pub -t 't/%n' -I 10ms -i 10ms -N 100 -s 1kb \ @sub -t 't/#' -I 10ms -N 10 @g -h 127.0.0.1 ``` -------------------------------- ### start/3 - Start a worker Source: https://github.com/emqx/emqttb/blob/master/_autodocs/api-reference/emqttb_worker.md Starts a new worker process with the given behavior module, group leader, and worker id. If the group's lowmem option is true, spawns with min_heap_size and fullsweep_after options; otherwise no special options. Returns the worker pid. ```erlang -spec start(module(), pid(), non_neg_integer()) -> pid(). start(Behavior, GroupLeader, Number) -> ``` -------------------------------- ### run/1 Source: https://github.com/emqx/emqttb/blob/master/_autodocs/api-reference/emqttb_scenario.md Starts a scenario by name via the supervisor. Returns ok and is idempotent. ```APIDOC ## run/1 ### Description Starts the scenario (via the supervisor). Returns `ok` (idempotent). ### Function Signature ```erlang -spec run(emqttb:scenario()) -> ok. ``` ### Parameters - **Name** (`emqttb:scenario()` atom) - Required - Scenario name, e.g. `pub` ### Returns - `ok` ``` -------------------------------- ### Quick start: List available metrics and autorates Source: https://github.com/emqx/emqttb/blob/master/_autodocs/index.md Commands to list available metrics and autorates using the @ls command. ```bash emqttb @ls metric ``` ```bash emqttb @ls autorate ``` -------------------------------- ### ensure/1 - Start or reuse a group manager Source: https://github.com/emqx/emqttb/blob/master/_autodocs/api-reference/emqttb_group.md Starts the group manager for the given configuration, setting the parent to the caller. Idempotent; returns ok. ```erlang -spec ensure(group_config()) -> ok. ensure(Conf) -> emqttb_group_sup:ensure(Conf#{parent => self()}). ``` -------------------------------- ### connect/2 and connect/5 Source: https://github.com/emqx/emqttb/blob/master/_autodocs/api-reference/emqttb_worker.md Builds the full emqtt option list from the group configuration and starts the client via emqtt:start_link/1. The connection is performed inside emqttb_metrics:call_with_counter/4 so connect latency/pending are recorded. ```APIDOC ## connect/2 and connect/5 ### Description Builds the full `emqtt` option list from the group configuration (`username`, `password`, `ssl_opts`, `clientid` from `my_clientid/0`, `max_inflight`, `hosts` from `broker_hosts/2`, `port` from `get_port/0`, `proto_ver`, `low_mem`, `owner => self()`, `ssl`, `tcp_opts`, v5 `properties` with `'Receive-Maximum'`, `keepalive`) and starts the client via `emqtt:start_link/1`. The connection is performed inside `emqttb_metrics:call_with_counter/4` so connect latency/pending are recorded. Host selection and shifting come from the `host_shift` / `host_selection` properties (defaults `0` and `random`). ### Function Signatures ```erlang -spec connect(emqttb_metrics:metric_ref(), map()) -> gen_statem:start_ret(). connect(ConnOpstat, Properties) -> connect(ConnOpstat, Properties, [], [], []). -spec connect(emqttb_metrics:metric_ref(), map(), [emqtt:option()], [gen_tcp:option()], [ssl:tls_option()]) -> gen_statem:start_ret(). connect(ConnOpstat, Properties0, CustomOptions, CustomTcpOptions, CustomSslOptions) -> ``` ### Parameters | Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | `ConnOpstat` | `emqttb_metrics:metric_ref()` | yes | — | `{avg_time, pending}` metric pair for the connect operation | | `Properties` / `Properties0` | `map()` | yes | — | MQTT v5 properties (e.g. `'Session-Expiry-Interval'`), plus optional `host_shift` / `host_selection` keys that are stripped before passing on | | `CustomOptions` | `[emqtt:option()]` | no | `[]` | Extra options passed straight to `emqtt:start_link/1` | | `CustomTcpOptions` | `[gen_tcp:option()]` | no | `[]` | Extra TCP options appended before `tcp_opts()` | | `CustomSslOptions` | `[ssl:tls_option()]` | no | `[]` | Extra TLS options appended before `ssl_opts()` | ### Returns `{ok, ClientPid}` (a `gen_statem:start_ret()`, i.e. `{ok, pid()} | {error, term()}`), the return of `emqtt:start_link/1` and `emqtt:connect/2` combined by `emqttb_metrics:call_with_counter/4`. ``` -------------------------------- ### Build emqttb on macOS with Homebrew Source: https://github.com/emqx/emqttb/blob/master/README.adoc Installs dependencies via Homebrew, clones the repo, sets MANPAGE_STYLESHEET, and builds. Requires Homebrew and docbook-xsl. ```bash brew install erlang rebar3 cmake texi2html texinfo git clone git@github.com:emqx/emqttb.git cd emqttb export MANPAGE_STYLESHEET=$(brew --prefix docbook-xsl)/docbook-xsl/manpages/docbook.xsl make release ``` -------------------------------- ### Quick start: publish scenario with shortened arguments Source: https://github.com/emqx/emqttb/blob/master/README.adoc Same as the full-argument publish scenario but using shortened flags: -L, -t, -I, -i, -N, -s, -h. ```bash emqttb -L 30s @pub -t 't/%n' -I 10ms -i 10ms -N 100 -s 1kb @g -h 127.0.0.1 ``` -------------------------------- ### CLI structure example with scopes Source: https://github.com/emqx/emqttb/blob/master/README.adoc Illustrates the global scope, action scopes, and positional arguments in the EMQTTB CLI. The ASCII diagram shows how arguments are grouped. ```bash emqttb --foo --bar 1 positional1 positional2 @action1 --foo 1 positional1 @action2 ... |___________| |_____________________| |_________________| |regular args positional args | action1 scope |___________________________________| global scope ``` -------------------------------- ### Quick start: subscribe scenario with shortened arguments Source: https://github.com/emqx/emqttb/blob/master/README.adoc Same as the full-argument subscribe scenario but using shortened flags: -L, -t, -I, -N, -h. ```bash emqttb -L 30s @sub -t 't/#' -I 10ms -N 10 @g -h 127.0.0.1 ``` -------------------------------- ### GET /doc/[...] Source: https://github.com/emqx/emqttb/blob/master/_autodocs/endpoints.md Serves static HTML documentation from the release's doc/html directory. The landing page is /doc/index.html. ```APIDOC ## GET /doc/[...] ### Description Serves static HTML documentation from the release's doc/html directory. The landing page is /doc/index.html. ### Method GET ### Endpoint /doc/[...] ### Response #### Success Response (200) - Static file content #### Error Response (404) - File not found ``` -------------------------------- ### ensure/1 Source: https://github.com/emqx/emqttb/blob/master/_autodocs/api-reference/emqttb_group.md Starts the group manager for the given configuration, or reuses an existing group with the same id. Idempotent and returns ok. ```APIDOC ## ensure/1 ### Description Starts the group manager (or reuses an already-running group with the same id). Idempotent — calling twice with the same id is safe. ### Function Signature ```erlang -spec ensure(group_config()) -> ok. ensure(Conf) -> emqttb_group_sup:ensure(Conf#{parent => self()}). ``` ### Parameters - **Conf** (group_config()) - Required - Group configuration; `parent` is set to the caller ### Returns - `ok` ``` -------------------------------- ### main/1 escript entrypoint Source: https://github.com/emqx/emqttb/blob/master/_autodocs/api-reference/emqttb.md Entry point for the EMQTTB escript. Receives raw command-line arguments, stores them in the application environment via application:set_env(emqttb, cli_args, Args), and records the run start time. Returns no_return() because it terminates the VM after scenarios complete. ```erlang %% Escript entrypoint -spec main([string()]) -> no_return(). main(Args) -> ``` -------------------------------- ### GET /scenario/:scenario/stage Source: https://github.com/emqx/emqttb/blob/master/_autodocs/api-reference/emqttb_http.md Returns the current stage of a scenario. Returns 404 if the scenario is not enabled. ```APIDOC ## GET /scenario/:scenario/stage ### Description Returns the current stage of a scenario. Returns 404 if the scenario is not enabled. ### Method GET ### Endpoint /scenario/:scenario/stage ### Parameters #### Path Parameters - **scenario** (string) - Required - The name of the scenario. ### Request Example N/A ### Response #### Success Response (200) - **Body** (text/plain) - The current stage as a binary string. #### Error Response (404) - Scenario not enabled. ``` -------------------------------- ### GET /metrics Source: https://github.com/emqx/emqttb/blob/master/_autodocs/endpoints.md Returns all metrics declared in the configuration model plus runtime Prometheus gauges, in Prometheus text exposition format. ```APIDOC ## GET /metrics ### Description Returns all metrics declared in the configuration model plus runtime Prometheus gauges, in Prometheus text exposition format. ### Method GET ### Endpoint /metrics ### Response #### Success Response (200) - **Body** (text/plain) - Prometheus text format output #### Response Example (metrics in Prometheus text format) ``` -------------------------------- ### start_link/0 Source: https://github.com/emqx/emqttb/blob/master/_autodocs/api-reference/emqttb_http.md Starts the Cowboy HTTP or HTTPS listener for the EMQTTB REST API. Reads configuration for listen port and TLS settings, and returns {ok, Pid} on success or {error, Reason}. ```APIDOC ## start_link/0 ### Description Starts the Cowboy HTTP or HTTPS listener for the EMQTTB REST API. Reads configuration for listen port and TLS settings, and returns {ok, Pid} on success or {error, Reason}. ### Method N/A (Erlang function) ### Endpoint N/A ### Parameters No arguments. ### Request Example N/A ### Response #### Success Response - **{ok, Pid}** - Listener started successfully. #### Error Response - **{error, Reason}** - Failed to start listener. ### Notes - Reads `[restapi, listen_port]` (default `{0,0,0,0,8017}`) and `[restapi, tls]` (default `false`). - Uses `cowboy:start_clear/3` for HTTP or `cowboy:start_tls/3` for HTTPS. ``` -------------------------------- ### start/3 Source: https://github.com/emqx/emqttb/blob/master/_autodocs/api-reference/emqttb_worker.md Starts a new worker process with the given behavior module, group leader, and worker number. The process is spawned with special options if the group's lowmem option is enabled. ```APIDOC ## start/3 ### Description Starts a new worker process with the given behavior module, group leader, and worker number. The process is spawned with special options if the group's lowmem option is enabled. ### Function Signature ```erlang -spec start(module(), pid(), non_neg_integer()) -> pid(). start(Behavior, GroupLeader, Number) -> ``` ### Parameters - **Behavior** (module()) - Required - Behavior module to run - **GroupLeader** (pid()) - Required - Group-manager process (new worker's group leader) - **Number** (non_neg_integer()) - Required - Worker id within the group ### Behavior If the group's `lowmem` option is true, spawns with `[{min_heap_size, 10}, {fullsweep_after, 0}]`; otherwise with no special options. ### Returns - **pid()** - The worker pid. ``` -------------------------------- ### connect/2 and connect/5 function specifications Source: https://github.com/emqx/emqttb/blob/master/_autodocs/api-reference/emqttb_worker.md Defines the public connect/2 and connect/5 functions. connect/2 delegates to connect/5 with empty option lists. connect/5 builds the full emqtt option list from group configuration and starts the client via emqtt:start_link/1, recording metrics. ```erlang -spec connect(emqttb_metrics:metric_ref(), map()) -> gen_statem:start_ret(). connect(ConnOpstat, Properties) -> connect(ConnOpstat, Properties, [], [], []). -spec connect(emqttb_metrics:metric_ref(), map(), [emqtt:option()], [gen_tcp:option()], [ssl:tls_option()]) -> gen_statem:start_ret(). connect(ConnOpstat, Properties0, CustomOptions, CustomTcpOptions, CustomSslOptions) -> ``` -------------------------------- ### GET /metrics Source: https://github.com/emqx/emqttb/blob/master/_autodocs/api-reference/emqttb_http.md Returns metrics in Prometheus text format. ```APIDOC ## GET /metrics ### Description Returns metrics in Prometheus text format. ### Method GET ### Endpoint /metrics ### Parameters None. ### Request Example N/A ### Response #### Success Response (200) - **Body** (text/plain) - Prometheus metrics in text format. #### Response Example (metrics in Prometheus text format) ``` -------------------------------- ### Set Grafana API key and URL via EMQTTB_ environment variables Source: https://github.com/emqx/emqttb/blob/master/_autodocs/configuration.md Sets the Grafana API key and URL via environment variables using the EMQTTB_ prefix and double underscores to separate path levels. These are the two examples explicitly documented in the project README. ```bash export EMQTTB_METRICS__GRAFANA__API_KEY="Bearer " # [metrics, grafana, api_key] export EMQTTB_METRICS__GRAFANA__URL="http://localhost:3000" # [metrics, grafana, url] ``` -------------------------------- ### my_hostname/0 - Get hostname Source: https://github.com/emqx/emqttb/blob/master/_autodocs/api-reference/emqttb_worker.md Returns the machine hostname as a binary using inet:gethostname/0. ```erlang -spec my_hostname() -> binary(). my_hostname() -> {ok, Host} = inet:gethostname(), list_to_binary(Host). ``` -------------------------------- ### info/0 - Get group information Source: https://github.com/emqx/emqttb/blob/master/_autodocs/api-reference/emqttb_group.md Returns a list of maps, one per live group, with keys '$id', conf_root, behavior, shared_state, and n_workers. ```erlang info() -> ``` -------------------------------- ### start_link/0 function Source: https://github.com/emqx/emqttb/blob/master/_autodocs/api-reference/emqttb_http.md Starts the Cowboy listener named rest_api with either HTTP or HTTPS based on the [restapi, tls] configuration. Reads [restapi, listen_port] for IP and port. Returns {ok, Pid} on success or {error, Reason}. ```erlang -spec start_link() -> {ok, pid()} | {error, _}. start_link() -> {IP, Port} = ?CFG([restapi, listen_port]), logger:info("Starting REST API at ~p:~p", [IP, Port]), TransportOpts = #{ port => Port , ip => IP }, Env = #{dispatch => dispatch()}, ProtocolOpts = #{env => Env}, StartFun = case ?CFG([restapi, tls]) of true -> ?LOG_INFO("Starting HTTPS listener with parameters ~p", [ProtocolOpts]), fun cowboy:start_tls/3; false -> ?LOG_INFO("Starting HTTP listener with parameters ~p", [ProtocolOpts]), fun cowboy:start_clear/3 end, StartFun(rest_api, maps:to_list(TransportOpts), ProtocolOpts). ``` -------------------------------- ### emqttb_behavior_sub config and prototype types Source: https://github.com/emqx/emqttb/blob/master/_autodocs/api-reference/behaviors.md Defines the configuration map and prototype type for the subscriber behavior. The config includes required fields for topic, QoS, and metrics, with optional fields for clean start, expiry, host shift, host selection, metadata parsing, and sequence verification. ```erlang -type config() :: #{ topic := binary() , qos := 0..2 , metrics := lee:model_key() , clean_start => boolean() , expiry => non_neg_integer() | undefined , host_shift => integer() , host_selection => _ , parse_metadata => boolean() , verify_sequence => boolean() }. -type prototype() :: {?MODULE, config()}. ``` -------------------------------- ### Define publisher behavior config and prototype types Source: https://github.com/emqx/emqttb/blob/master/_autodocs/api-reference/behaviors.md Defines the configuration map and prototype type for the publisher behavior. The config includes required fields for topic pattern, publish interval autorate, message size, metrics path, and QoS, with optional fields for retain, metadata, host shift, randomization, host selection, clean start, and session expiry. ```erlang -type config() :: #{ topic := binary() , pubinterval := lee:model_key() , msg_size := non_neg_integer() , metrics := lee:model_key() , qos := emqttb:qos() , retain => boolean() , metadata => boolean() , host_shift => integer() , random => boolean() , host_selection => random | round_robin , clean_start => boolean() , expiry => non_neg_integer() | undefined }. -type prototype() :: {?MODULE, config()}. ``` -------------------------------- ### emqttb_scenario_conn model/0 callback Source: https://github.com/emqx/emqttb/blob/master/_autodocs/api-reference/scenarios.md Defines the option schema for the @conn scenario, including connection interval, number of clients, group, expiry, clean start, and metrics. The metrics option uses emqttb_behavior_conn:model/1. ```erlang model() -> #{ conninterval => ... %% emqttb:duration_us(), default_ref [interval], CLI --conninterval / -I, autorate 'conn/conninterval' , n_clients => ... %% emqttb:n_clients(), default_ref [n_clients], CLI --num-clients / -N , group => ... %% atom(), default default, CLI --group / -g , expiry => ... %% union(non_neg_integer(), undefined), default undefined, CLI --expiry / -x , clean_start => ... %% boolean(), default true, CLI --clean-start / -C , metrics => emqttb_behavior_conn:model('conn/conn') }. ``` -------------------------------- ### ensure/1 starts or reuses autorate Source: https://github.com/emqx/emqttb/blob/master/_autodocs/api-reference/emqttb_autorate.md Starts (or reuses) the autorate via emqttb_autorate_sup:ensure/1 and returns a counters reference to its current value. The caller typically stores this in worker shared state and calls emqttb:get_duration_and_repeats/1 on it. ```erlang -spec ensure(config()) -> {auto, counters:counters_ref()}. ensure(Conf) -> {ok, Pid} = emqttb_autorate_sup:ensure(Conf#{parent => self()}), {auto, get_counter(Pid)}. ``` -------------------------------- ### Show help for pub scenario Source: https://github.com/emqx/emqttb/blob/master/README.adoc Displays the manual page for the @pub scenario using emqttb --help pub. ```bash emqttb --help pub ``` -------------------------------- ### GET /healthcheck Source: https://github.com/emqx/emqttb/blob/master/_autodocs/api-reference/emqttb_http.md Health check endpoint that always returns HTTP 200 with an empty text body. ```APIDOC ## GET /healthcheck ### Description Health check endpoint that always returns HTTP 200 with an empty text body. ### Method GET ### Endpoint /healthcheck ### Parameters None. ### Request Example N/A ### Response #### Success Response (200) - **Body** (text/plain) - Empty body. #### Response Example (empty) ``` -------------------------------- ### Build emqttb from source Source: https://github.com/emqx/emqttb/blob/master/README.adoc Clones the repository and builds a release with make. Requires Erlang/OTP 24+, rebar3, make, and cmake (for quicer). ```bash git clone git@github.com:emqx/emqttb.git cd emqttb make release ``` -------------------------------- ### my_scenario/0 - Get current scenario name Source: https://github.com/emqx/emqttb/blob/master/_autodocs/api-reference/emqttb_scenario.md Returns the name (atom) of the scenario that spawned the calling process. ```erlang -spec my_scenario() -> module(). my_scenario() -> persistent_term:get(?SCENARIO_GROUP_LEADER(group_leader())). ``` -------------------------------- ### my_id/0 - Get worker id Source: https://github.com/emqx/emqttb/blob/master/_autodocs/api-reference/emqttb_worker.md Returns the worker's numeric id within its group from the process dictionary. ```erlang -spec my_id() -> integer(). my_id() -> get(?MY_ID). ``` -------------------------------- ### stage/1 - Get current stage Source: https://github.com/emqx/emqttb/blob/master/_autodocs/api-reference/emqttb_scenario.md Returns the current stage atom for the given scenario, or undefined if no stage was set. ```erlang -spec stage(emqttb:scenario()) -> emqttb:stage(). stage(Scenario) -> persistent_term:get({emqttb_stage, Scenario}, undefined). ``` -------------------------------- ### load_conf/0 Source: https://github.com/emqx/emqttb/blob/master/_autodocs/api-reference/emqttb_conf.md Initializes the configuration store from all configured metatypes. After successful init, it may load repeat configuration, load a config file, or dump configuration depending on convenience settings. ```APIDOC ## load_conf/0 ### Description Initializes the configuration store from all configured metatypes. After a successful init, it may load repeat configuration, load a config file, or dump configuration depending on convenience settings. On failure, logs errors, marks the run as failed, and terminates the VM. ### Method Function call ### Endpoint `load_conf/0` ### Parameters None. ### Returns - `ok` - On successful initialization. - Halts the VM on invalid configuration. ``` -------------------------------- ### load_conf/0 - Initialize configuration store Source: https://github.com/emqx/emqttb/blob/master/_autodocs/api-reference/emqttb_conf.md Initializes the configuration store from all configured metatypes. After successful init, it may load a repeat file, load a config file, or dump the configuration. On failure, logs errors at critical level, marks the run as failed with reason "invalid configuration", and terminates the VM. ```erlang load_conf() -> Storage = lee_storage:new(lee_persistent_term_storage, ?CONF_STORE), case lee:init_config(?MYMODEL, Storage) of {ok, _Data, _Warnings} -> maybe_load_repeat(), maybe_load_conf_file(), maybe_dump_conf(), ok; {error, Errors, Warnings} -> [logger:critical(E) || E <- Errors], [logger:warning(E) || E <- Warnings], emqttb:setfail("invalid configuration"), emqttb:terminate() end. ``` -------------------------------- ### my_group/0 - Get group id Source: https://github.com/emqx/emqttb/blob/master/_autodocs/api-reference/emqttb_worker.md Returns the group id of the calling worker by looking up the group leader in a persistent term. ```erlang -spec my_group() -> emqttb:group(). my_group() -> persistent_term:get(?GROUP_LEADER_TO_GROUP_ID(group_leader())). ``` -------------------------------- ### GET /metrics Source: https://github.com/emqx/emqttb/blob/master/_autodocs/index.md Prometheus text endpoint that exposes metrics in Prometheus format. It is part of the REST API enabled with --restapi. ```APIDOC ## GET /metrics ### Description Prometheus text endpoint that exposes metrics in Prometheus format. ### Method GET ### Endpoint /metrics ### Response #### Success Response (200) - **body** (text/plain) - Prometheus metrics in text format. #### Response Example ``` # HELP emqttb_... ... # TYPE emqttb_... ... ``` ``` -------------------------------- ### my_conf_key/1 Source: https://github.com/emqx/emqttb/blob/master/_autodocs/api-reference/emqttb_scenario.md Returns the full configuration path for a scenario-specific key. ```APIDOC ## my_conf_key/1 ### Description Returns the full config path `[scenarios, , {}, ...Key]`. ### Function Signature ```erlang -spec my_conf_key(lee:key()) -> lee:key(). ``` ### Parameters - **Key** (`lee:key()`) - Required - Key relative to the scenario config, e.g. `[n_clients]` ### Returns - `lee:key()` - The full configuration path. ``` -------------------------------- ### my_conf_key/1 and my_conf/1 - Configuration helpers Source: https://github.com/emqx/emqttb/blob/master/_autodocs/api-reference/emqttb_scenario.md my_conf_key/1 returns the full config path for a scenario option. my_conf/1 returns the value of the scenario option at the given key. ```erlang -spec my_conf_key(lee:key()) -> lee:key(). my_conf_key(Key) -> [?SK(my_scenario()) | Key]. -spec my_conf(lee:key()) -> term(). my_conf(Key) -> ?CFG(my_conf_key(Key)). ``` -------------------------------- ### Set Grafana API key and URL for emqttb Source: https://github.com/emqx/emqttb/blob/master/README.adoc Exports environment variables for Grafana API key and URL, then runs emqttb with the --grafana flag. Requires a Grafana API key with Editor role. ```bash export EMQTTB_METRICS__GRAFANA__API_KEY="Bearer eyJrIjoiNmhSdTFnWGJlaE9tZXQ2YXI4WlEyUGNSMXFMb1oyUXkiLCJuIjoiZW1xdHRiIiwiaWQiOjF9" export EMQTTB_METRICS__GRAFANA__URL="http://localhost:3000" emqttb --grafana ... ``` -------------------------------- ### get/1 Source: https://github.com/emqx/emqttb/blob/master/_autodocs/api-reference/emqttb_conf.md Retrieves the value of a configuration key from the emqttb configuration store. ```APIDOC ## get/1 ### Description Retrieves the value of a configuration key from the emqttb configuration store. ### Method Function call ### Endpoint `get(Key)` ### Parameters - `Key` (`lee:key()`) - Required - Configuration key (e.g. `[restapi, listen_port]`) ### Returns The value of the given key (see configuration.md). ``` -------------------------------- ### ensure/1 Source: https://github.com/emqx/emqttb/blob/master/_autodocs/api-reference/emqttb_autorate.md Starts (or reuses) the autorate and returns a counters reference to its current value. The caller typically stores this in worker shared state and calls emqttb:get_duration_and_repeats/1 on it. ```APIDOC ## ensure/1 ### Description Starts (or reuses) the autorate and returns a counters reference to its current value. The caller typically stores this in worker shared state and calls `emqttb:get_duration_and_repeats/1` on it. ### Function Signature ```erlang -spec ensure(config()) -> {auto, counters:counters_ref()}. ensure(Conf) -> {ok, Pid} = emqttb_autorate_sup:ensure(Conf#{parent => self()}), {auto, get_counter(Pid)}. ``` ### Parameters - **Conf** (`config()`) - Required - Autorate configuration ### Returns `{auto, counters:counters_ref()}` — a counters reference to the current value. ``` -------------------------------- ### init_per_group/3 - Initialize group Source: https://github.com/emqx/emqttb/blob/master/_autodocs/api-reference/emqttb_worker.md Calls the behavior module's init_per_group/2 with the group ID and options. Returns the shared state from that call. ```erlang -spec init_per_group(module(), emqttb:group(), term()) -> term(). init_per_group(Module, GroupID, Opts) -> Module:init_per_group(GroupID, Opts). ``` -------------------------------- ### Client group configuration: multiple groups with different transports Source: https://github.com/emqx/emqttb/blob/master/README.adoc Uses two group configurations: one for websocket (wss) and one for MQTT (mqtt), allowing publishers and subscribers to use different transports. ```bash emqttb @pub -t 'foo/%n' -g wss \ @sub -t 'foo/#' -g mqtt \ @g -g wss -h localhost --transport ws --ssl \ @g -g mqtt -h localhost --transport sock ``` -------------------------------- ### my_clientid/0 - Get client id Source: https://github.com/emqx/emqttb/blob/master/_autodocs/api-reference/emqttb_worker.md Expands the [client, clientid] pattern by substituting %n (worker id), %g (group id), %h (hostname). Returns the client id binary. ```erlang -spec my_clientid() -> binary(). my_clientid() -> ``` -------------------------------- ### annotate_range/4 - Post annotation for a time range Source: https://github.com/emqx/emqttb/blob/master/_autodocs/api-reference/emqttb_grafana.md Posts an annotation for a time range using start and end times in epoch ms. Used by emqttb:terminate/0 to annotate the whole run span. ```erlang -spec annotate_range(iolist(), [string()], integer(), integer()) -> ok. annotate_range(Text, Tags, Time, TimeEnd) -> Range = #{time => Time, 'timeEnd' => TimeEnd}, annotate(Text, Tags, Range). ``` -------------------------------- ### init_per_group/3 Source: https://github.com/emqx/emqttb/blob/master/_autodocs/api-reference/emqttb_worker.md Calls the behavior module's init_per_group/2 function with the given group ID and options, returning the shared state. ```APIDOC ## init_per_group/3 ### Description Calls the behavior module's init_per_group/2 function with the given group ID and options, returning the shared state. ### Function Signature ```erlang -spec init_per_group(module(), emqttb:group(), term()) -> term(). init_per_group(Module, GroupID, Opts) -> Module:init_per_group(GroupID, Opts). ``` ### Parameters - **Module** (module()) - Required - Behavior module - **GroupID** (emqttb:group()) - Required - Group identifier - **Opts** (term()) - Required - Options passed to the behavior module ### Returns - **term()** - The shared state returned by `Module:init_per_group/2`. ``` -------------------------------- ### my_hostname/0 Source: https://github.com/emqx/emqttb/blob/master/_autodocs/api-reference/emqttb_worker.md Returns the machine hostname as a binary. ```APIDOC ## my_hostname/0 ### Description Returns the machine hostname as a binary. ### Function Signature ```erlang -spec my_hostname() -> binary(). my_hostname() -> {ok, Host} = inet:gethostname(), list_to_binary(Host). ``` ### Returns - **binary()** - The machine hostname as a binary. ``` -------------------------------- ### string2patch/1 Source: https://github.com/emqx/emqttb/blob/master/_autodocs/errors.md Parses a CLI-like string into a configuration patch. Raises a badmatch error if the string fails lee_cli:read/2. ```APIDOC ## string2patch/1 ### Description Parses a CLI-like string into a configuration patch. Raises a `{badmatch, {error, ...}}` or `{badmatch, ...}` error if the string fails `lee_cli:read/2` (bad argument). ### Method Function call ### Endpoint N/A (Erlang function) ### Parameters - **String** (string) - Required - The CLI-like string to parse. ### Response - **Patch** (term) - The parsed configuration patch. ### Error Handling - Wrap in `try` to catch `{badmatch, ...}` errors. Used only in scenario `initial_config/0`. ``` -------------------------------- ### my_cfg/1 and my_cfg/2 - Get group config Source: https://github.com/emqx/emqttb/blob/master/_autodocs/api-reference/emqttb_worker.md Reads a group-specific configuration value. my_cfg/1 uses the current group leader; my_cfg/2 accepts a specific group leader. Returns the value from the @g configuration. ```erlang -spec my_cfg(lee:key()) -> term(). my_cfg(Key) -> my_cfg(group_leader(), Key). -spec my_cfg(pid(), lee:key()) -> term(). my_cfg(GroupLeader, Key) -> ``` -------------------------------- ### my_conf/1 Source: https://github.com/emqx/emqttb/blob/master/_autodocs/api-reference/emqttb_scenario.md Returns the value of the scenario option at the given key. ```APIDOC ## my_conf/1 ### Description Returns the value of the scenario option at `Key`. ### Function Signature ```erlang -spec my_conf(lee:key()) -> term(). ``` ### Parameters - **Key** (`lee:key()`) - Required - Key relative to the scenario config, e.g. `[n_clients]` ### Returns - `term()` - The value of the scenario option. ``` -------------------------------- ### load_model/0 Source: https://github.com/emqx/emqttb/blob/master/_autodocs/api-reference/emqttb_conf.md Compiles the configuration model and stores it in the persistent term. On failure, logs errors, marks the run as failed, and terminates the VM. ```APIDOC ## load_model/0 ### Description Compiles the configuration model and stores it in the persistent term `?MODEL_STORE`. On failure it logs each error at `critical` level, marks the run as failed with reason `"invalid configuration model"`, and terminates the VM (exit code 1). ### Method Function call ### Endpoint `load_model/0` ### Parameters None. ### Returns - `ok` - On successful compilation and storage. - Halts the VM on invalid model. ``` -------------------------------- ### activate/1 and deactivate/1 freeze and thaw Source: https://github.com/emqx/emqttb/blob/master/_autodocs/api-reference/emqttb_autorate.md deactivate/1 freezes the current value (updates stop); activate/1 resumes periodic updates. Both return ok. The group manager calls emqttb_autorate:activate/1 whenever a new scaling operation starts. ```erlang %% Freeze the value of autorate deactivate(Autorate) -> gen_server:call(server(Autorate), deactivate). %% Thaw the value of autorate activate(Autorate) -> gen_server:call(server(Autorate), activate). ``` -------------------------------- ### Client group configuration: implicit default group Source: https://github.com/emqx/emqttb/blob/master/README.adoc Shows the default group configuration usage. The @pub scenario uses the implicit 'default' group. ```bash emqttb @pub -t foo @g -h localhost ``` -------------------------------- ### POST /conf/reload Source: https://github.com/emqx/emqttb/blob/master/_autodocs/endpoints.md Reloads the configuration in the runtime by re-running emqttb_conf:reload/0. Returns true on success, false otherwise. ```APIDOC ## POST /conf/reload ### Description Reloads the configuration in the runtime by re-running emqttb_conf:reload/0. Returns true on success, false otherwise. ### Method POST ### Endpoint /conf/reload ### Response #### Success Response (200) - **Body** (text/plain) - `true` on successful reload, `false` otherwise #### Response Example (plain text boolean) ``` -------------------------------- ### complete/1 Source: https://github.com/emqx/emqttb/blob/master/_autodocs/api-reference/emqttb_scenario.md Completes the scenario, setting the stage to complete and marking the run as failed on error. ```APIDOC ## complete/1 ### Description Sets the stage to `complete` and, when the result is `{error, _}`, marks the whole run as failed via `emqttb:setfail(Scenario)`. Returns `no_return()` — the gen_server stops normally right after the callback returns. ### Function Signature ```erlang -spec complete(result()) -> no_return(). ``` ### Parameters - **PrevStageResult** (`result()`) - Required - Final stage result ### Returns - `no_return()` ``` -------------------------------- ### info/0 Source: https://github.com/emqx/emqttb/blob/master/_autodocs/api-reference/emqttb_autorate.md Returns one info() map per running autorate, containing fields such as '$id', value, error, p, i, and sum. ```APIDOC ## info/0 ### Description Returns one `info()` map per running autorate: `'$id'`, `value` (from the counter), `error`, `p`, `i`, `sum` (from the `emqttb_autorate_control` Prometheus gauge). ### Function Signature ```erlang -spec info() -> [info()]. info() -> ``` ### Returns List of `info()` maps, one per running autorate. ``` -------------------------------- ### patch/1 - Apply configuration patch Source: https://github.com/emqx/emqttb/blob/master/_autodocs/api-reference/emqttb_conf.md Applies a patch to the live configuration. Returns true on success, false otherwise. ```erlang patch(Patch) -> logger:debug("Patching configuration: ~p", [Patch]), case lee:patch(?MYMODEL, ?MYCONF, Patch) of {ok, _, _} -> true; _ -> false end. ``` -------------------------------- ### string2patch/1 Source: https://github.com/emqx/emqttb/blob/master/_autodocs/api-reference/emqttb_conf.md Parses a string resembling CLI arguments into a configuration patch, used by scenario initial_config/0 callbacks. ```APIDOC ## string2patch/1 ### Description Parses a string resembling CLI arguments into a configuration patch, used by scenario initial_config/0 callbacks. ### Method Function call ### Endpoint `string2patch(Str)` ### Parameters - `Str` (`string()`) - Required - A string resembling CLI arguments, e.g. `"@a -a pub/pubinterval --pvar '[scenarios,pub,{},metrics,pub_latency,pending]'"` ### Returns A `lee:patch()` (never a tagged `{ok, ...}` — the wrapper strips it). ``` -------------------------------- ### compile_model/1 - Compile model against metamodel Source: https://github.com/emqx/emqttb/blob/master/_autodocs/api-reference/emqttb_conf.md Compiles the given model fragment against the metamodel, which includes base metamodel and metatypes like lee_os_env, lee_app_env, lee_logger, lee_cli, lee_config_file, emqttb_scenario, emqttb_metrics, and emqttb_autorate. Returns {ok, Model} or {error, Errors}. ```erlang compile_model(Model) -> MTs = metamodel(), lee_model:compile(MTs, [Model]). ``` -------------------------------- ### POST /conf/reload Source: https://github.com/emqx/emqttb/blob/master/_autodocs/errors.md Reloads the configuration. Returns false if the underlying lee:init_config/2 did not return {ok, _, _}. The REST handler returns this boolean as the response body. ```APIDOC ## POST /conf/reload ### Description Reloads the configuration. Returns `false` if the underlying `lee:init_config/2` did not return `{ok, _, _}`. The REST handler returns this boolean as the response body. ### Method POST ### Endpoint /conf/reload ### Response #### Success Response (200) - **body** (boolean) - `true` if reload succeeded, `false` otherwise. #### Response Example true ### Error Handling - If `lee:init_config/2` does not return `{ok, _, _}`, the endpoint returns `false` as the body. ``` -------------------------------- ### patch/1 Source: https://github.com/emqx/emqttb/blob/master/_autodocs/errors.md Applies a configuration patch. Returns false if the underlying lee:patch/3 did not return {ok, _, _}, e.g., due to unknown key or type mismatch. ```APIDOC ## patch/1 ### Description Applies a configuration patch. Returns `false` if the underlying `lee:patch/3` did not return `{ok, _, _}`, e.g., due to unknown key or type mismatch. ### Method Function call ### Endpoint N/A (Erlang function) ### Parameters - **Patch** (term) - Required - The configuration patch to apply. ### Response - **boolean** - `true` if patch succeeded, `false` otherwise. ### Error Handling - Pattern-match the boolean return value to detect failure. ``` -------------------------------- ### do_collect/0 - Push metrics to pushgateway Source: https://github.com/emqx/emqttb/blob/master/_autodocs/api-reference/emqttb_grafana.md Builds the push URL as /metrics/job//instance/~ and posts Prometheus text-format metrics via hackney. The job label is the first part of the node name, the instance label combines node name and host part. ```erlang do_collect() -> Uri = ?CFG([metrics, pushgateway, url]), [Name, Ip] = string:tokens(atom_to_list(node()), "@"), Url = lists:concat([Uri, "/metrics/job/", Name, "/instance/", Name, "~", Ip]), Data = prometheus_text_format:format(), Headers = [], Options = [], {ok, _Code, _RespHeaders, ClientRef} = hackney:post(Url, Headers, Data, Options), hackney:skip_body(ClientRef). ``` -------------------------------- ### set_stage/1 and set_stage/2 - Set stage Source: https://github.com/emqx/emqttb/blob/master/_autodocs/api-reference/emqttb_scenario.md set_stage/1 logs a banner, annotates Grafana, and stores the stage. set_stage/2 additionally logs completion/failure banners before switching the stage. ```erlang -spec set_stage(emqttb:stage()) -> ok. set_stage(Stage) -> Scenario = my_scenario(), Txt = lists:flatten(io_lib:format("~p entered stage ~p", [Scenario, Stage])), logger:notice(asciiart:visible($#, Txt, [])), emqttb_grafana:annotate(Txt, [Scenario]), persistent_term:put({emqttb_stage, Scenario}, Stage). -spec set_stage(emqttb:stage(), result()) -> ok. set_stage(Stage, ok) -> set_stage(Stage); set_stage(Stage, {ok, Result}) -> ... set_stage(Stage); set_stage(Stage, {error, Err}) -> ... set_stage(Stage). ``` -------------------------------- ### model/0 - Build configuration model Source: https://github.com/emqx/emqttb/blob/master/_autodocs/api-reference/emqttb_scenario.md Returns a lee model fragment mapping each scenario name to its model, merging each scenario's own model/0 with the standard loiter option. ```erlang -spec model() -> lee:lee_module(). model() -> application:load(?APP), Scenarios = all_scenario_modules(), Model = [{name(M), make_model(M)} || M <- Scenarios], maps:from_list(Model). ``` -------------------------------- ### load_model/0 - Compile and store configuration model Source: https://github.com/emqx/emqttb/blob/master/_autodocs/api-reference/emqttb_conf.md Compiles the configuration model and stores it in the persistent term ?MODEL_STORE. On failure, logs each error at critical level, marks the run as failed with reason "invalid configuration model", and terminates the VM (exit code 1). ```erlang load_model() -> case compile_model(emqttb_conf_model:model()) of {ok, Model} -> persistent_term:put(?MODEL_STORE, Model), ok; {error, Errors} -> logger:critical("Configuration model is invalid!"), [logger:critical(E) || E <- Errors], emqttb:setfail("invalid configuration model"), emqttb:terminate() end. ``` -------------------------------- ### patch/1 Source: https://github.com/emqx/emqttb/blob/master/_autodocs/api-reference/emqttb_conf.md Applies a configuration patch to the live configuration. ```APIDOC ## patch/1 ### Description Applies a patch to the live configuration. ### Method Function call ### Endpoint `patch/1` ### Parameters #### Path Parameters - `Patch` (lee:patch()) - Required - Configuration patch (list of `{Path, Value}` terms). ### Returns - `true` - On success. - `false` - On failure. ``` -------------------------------- ### annotate/1 - Post annotation with default tags Source: https://github.com/emqx/emqttb/blob/master/_autodocs/api-reference/emqttb_grafana.md Posts an annotation with no custom tags. Returns ok. ```erlang -spec annotate(iolist()) -> ok. annotate(Text) -> annotate(Text, []). ```