emqx/emqttb

This system is an MQTT benchmarking tool designed to simulate various client workloads and measure performance metrics. It provides a CLI-driven framework for defining and executing scenarios such as publishing, subscribing, and connection testing, with support for complex behaviors like session persistence and network flapping. The tool integrates with Prometheus and Grafana for observability and exposes a REST API for configuration and monitoring.

The metrics module now supports exporting operational data to external monitoring systems. Users can configure Grafana annotations to be created for specific events via the new emqttb\_grafana module, and the system can periodically push collected metrics to a Prometheus Pushgateway using the new emqttb\_pushgw module, enabling broader observability dashboards.

src/metrics · high confidence

The framework source code has been reorganized into the src/framework directory, introducing new modules for declarative autoscaling (emqttb\_autorate), worker group management (emqttb\_group), and scenario execution (emqttb\_scenario). The main application entry point (emqttb\_app) now initializes these components, including setting up Grafana annotations and starting the HTTP and Pushgateway workers. The supervisor tree (emqttb\_sup) has been updated to manage these new children, adding auto-shutdown behavior for significant processes. Additionally, new capabilities include sequence verification for message payloads (emqttb\_msg\_payload) and enhanced logging filtering (emqttb\_logger).

src/framework · high confidence

The benchmarking tool now includes dedicated behavior modules for simulating MQTT workloads. The new \emqttb\_behavior\_pub\ module allows users to configure publishers with options for QoS, retain flags, message metadata, and session expiry intervals. The \emqttb\_behavior\_sub\ module enables subscribers to track message sequence integrity, reporting gaps and repeats, while the new \emqttb\_behavior\_sub\_flapping\ module simulates unstable network conditions by periodically unsubscribing and resubscribing. Additionally, \emqttb\_behavior\_pubsub\ combines these capabilities for end-to-end latency measurement, and \emqttb\_behavior\_conn\ (renamed from \emqttb\_autorate\) focuses on connection latency metrics.

src/behaviors · high confidence

The scenarios module now includes dedicated test profiles for connection-only workloads (emqttb\_scenario\_conn), persistent sessions with publish/subscribe cycles (emqttb\_scenario\_persistent\_session), combined pub/sub traffic (emqttb\_scenario\_pubsub), and full message forwarding across nodes (emqttb\_scenario\_pubsub\_fwd). Subscription testing has been expanded with flapping scenarios that simulate rapid subscribe/unsubscribe cycles (emqttb\_scenario\_sub\_flapping, emqttb\_scenario\_sub\_unsub\_flapping). The existing publisher scenario has been refactored to support modern MQTT features, including configurable QoS, message retention, payload randomization, and metadata injection for end-to-end latency measurement.

src/scenarios · high confidence

Added a new Erlang escript (scripts/docgen.escript) to generate documentation in TexInfo format, specifically supporting metrics and autorate configurations. Also added a shell script (scripts/rename-package.sh) to automate the renaming of release tarballs based on the operating system, architecture, and version, including support for QUIC builds.

scripts · high confidence

The emqttb shell script has been updated to automatically invoke the help function when executed with no arguments, ensuring users see usage information immediately. It also supports explicit help flags (--help and --help \<command\>) and sets the INFOPATH environment variable to include the documentation directory, while applying a specific ulimit setting for file descriptors.

bin · high confidence

The application core has been significantly restructured: the main application, configuration, group, scenario, and scenario supervisor modules (emqttb\_app, emqttb\_conf, emqttb\_group, emqttb\_scenario, emqttb\_scenario\_sup) have been removed, likely replaced by a new architecture using gproc for groups and a refactored scenarios\_sup. The emqttb module now exposes new APIs for duration parsing (microseconds, milliseconds, seconds), host/address parsing, and sleep duration calculation, while the main entry point now monitors emqttb\_scenarios\_sup instead of emqttb\_scenario\_sup. Additionally, the application dependencies have been updated to include gproc, hackney, xmerl, gun, and emqtt, and the version is now set to 'git'.

src · high confidence

The configuration system has been replaced with a new declarative model (emqttb\_conf) that supports loading settings from command-line arguments, environment variables, and configuration files with a defined priority order. This change introduces new CLI options for controlling metrics (pushgateway, Grafana annotations), REST API settings, and logging levels, while also changing the internal representation of durations to microseconds.

src/conf · high confidence

The REST API implementation has been moved into the src/restapi directory, with configuration keys updated from 'rest' to 'restapi'. The healthcheck endpoint now returns a plain text response instead of JSON. Additionally, static HTML documentation is now served directly via Cowboy at the /doc path, and a new endpoint allows getting or setting configuration parameters for running scenarios.

src/restapi · high confidence

The configuration header file has been moved to the include directory and updated to integrate with the Lee library (version 0.4.1). Configuration access now utilizes Lee-specific macros for persistent term storage, and the model store definition has been renamed to lee\_model\_store. Additionally, the scenario key macro now accepts an empty tuple argument.

include · high confidence

The configuration for the Erlang VM has been updated to include specific flags (-Q134217727 and -a16) in vm.args.src, while the previous sys.config.src file has been removed. This change modifies the runtime environment settings for the emqttb application.

config · high confidence

Added new Common Test suites to verify core functionality: \emqtt\_gauge\_SUITE.erl\ tests the rolling average metrics behavior; \emqttb\_worker\_SUITE.erl\ validates worker group lifecycle, state continuity, and error handling in init, message handling, and terminate callbacks using trace assertions; and \escript\_SUITE.erl\ ensures the command-line escript runs various scenarios (pub, sub, pubsub, connection, etc.) without errors.

test · high confidence

The project has significantly upgraded its core dependencies, including emqtt (1.4.4 to 1.14.4), lee (0.2.0 to 0.5.1), and prometheus (4.8.1 to 4.8.2), while introducing new dependencies such as gproc (0.9.1) and hackney (1.25.0). The build system has been restructured with a new Makefile for documentation generation (TexInfo), updated rebar.config profiles for escript and release packaging, and the removal of the old README.org in favor of a comprehensive README.adoc that documents the new CLI action-based scenario API, metrics export, and Grafana integration.

(repo-wide) · high confidence

The documentation source files have been migrated from their previous format to Texinfo, introducing a new structured manual (emqttb.info) that covers core concepts, CLI invocation, autorate mechanisms, and scenario definitions. This change reorganizes the documentation structure to use Texinfo nodes and includes, ensuring consistent formatting and improved navigation for users.

doc · high confidence

Written by watchdog.canine.dev from the codebase's own history, inside the signed delivery this page is composed from.

• CAI 59 → 57 (-1.5)
• Rubric changed (rubric-2026.09.12 → rubric-2026.09.18) — scores are not directly comparable.

• Code Health 97 → 97 (+0.0)
• Architecture 100 → 100 (+0.0)
• Maturity 49 → 49 (+0.0)
• Readiness 59 → 53 (-6.2)
• Security 58 → 58 (+0.0)

• Coverage not measured — no coverage collector is wired up
• Documentation: no installation or build instructions (README.adoc)
• Documentation: no usage examples (README.adoc)
• Off-boarding risk: anonymized user #1

• Dependency hygiene PARTLY measured — rebar3 pinning read, dependency currency not (no rebar.lock-pinned Hex declaration to grade)
• No ADRs found
• No dependency lockfile committed (rebar.config)
• Off-boarding risk: anonymized user #1

Written by watchdog.canine.dev from the codebase's own history, inside the signed delivery this page is composed from.

emqx/emqttb was measured the same way every project in this corpus was: the same rubric, at a pinned commit, with the result published in full. Point a surveyor at a repository you know and see whether you agree with it.