/docs/engineer/bench

Create and run your first MQTT benchmark in 5 minutes

Use an authorized, reachable Broker to create a safe 25-client Fan-out baseline, pass Preflight, and verify live MQTT traffic in five minutes.

Author:: Mqttable
Updated:: Aug 26, 2026

On this page9 sections

Create a small, repeatable MQTT benchmark with one Publisher and 24 Subscribers. Connect your authorized Broker, load the Fan-out scenario, pass Preflight, and confirm the expected live traffic.

BEFORE YOU START

Installed app · authorized Broker · exact endpoint

SAFE BASELINE

1 Publisher · 24 Subscribers · 45s

TRAFFIC

fo/data → fo/# · QoS 1 · every 1s

DONE

25 online · 1 send/s · 24 recv/s · 0 errors

1. Create and test your target

Open Bench from the Mqttable sidebar. If the Runtime has no saved Benchmark target, select Benchmark Now.

In New Broker, enter:

Name: a clear name for this target, such as First Fan-out;
Protocol, Host, and Port: the exact endpoint of your authorized test Broker;
Run Duration: 45 seconds;
Warm-up Duration: 0 seconds;
Source IP: Auto;
the TLS and Credential refs required by your target, if any.

Benchmark Now does not start or provision a Broker. The screenshot uses the disposable documentation target Bench Docs Demo at mqtt://127.0.0.1:18883; do not copy that endpoint unless you already started your own listener there.

Select Test Connection. Continue only when MQTT 3.1.1 and MQTT 5.0 both report Connection OK, then select Create.

New Benchmark Broker form showing the example endpoint, 45-second Measurement, no Warm-up, and successful MQTT 3.1.1 and MQTT 5.0 connection tests — Use your own authorized endpoint; both protocol tests must pass before you create the target.
Replace the example protocol, host, port, and credentials with your authorized target.
Continue only after both MQTT protocol rows show Connection OK.

2. Load a safe Fan-out baseline

Open the beaker menu and choose Fan-out (1 pub → 1K subs). The template creates:

fanout-pub: one Publisher that sends a QoS 1 message to fo/data every second;
fanout-sub: 1,000 Subscribers on fo/#.

Do not run the 1K template as loaded. It is an editable scenario, not a safe first-run size.

Bench Fan-out example menu open above the publisher and subscriber Groups at the original one-thousand-subscriber scale — Load the complete Fan-out plan, then reduce its Subscriber scale before Preflight or Start.
Choose Fan-out to create the Publisher, Subscriber, message, and subscription together.
The template starts with 1,000 Subscribers; do not run it yet.

Open fanout-sub and change exactly these two values:

Total Clients: 1000 → 24;
Connection target: 100 → 24 clients/sec.

Save the Group. Leave fo-sub-{index}, MQTT 5.0, Clean Start, and the 300-second Keep Alive unchanged. The template already supplies the matching fo/data Scheduled Message and fo/# Subscription; you do not need to open or recreate them for this first run.

Edit Benchmark Group dialog with fanout-sub reduced to 24 total clients and 24 clients per second — The first-run safety boundary is 24 Subscribers at a target of 24 new connections per second.
Set Total Clients to 24 before this workload can run.
Set the connection target to 24 clients/sec and save the Group.

3. Preflight and start

Select Run preflight. Before creating load, confirm the summary shows:

25 Clients: 1 Publisher + 24 Subscribers;
2 Groups: fanout-pub and fanout-sub;
34 connects/s: the two Groups' connection targets combined;
your exact Broker endpoint and the intended Runtime.

Use the result as a gate:

Ready: select Start;
Ready with warnings: open Details and continue only when every warning is acceptable for this run;
Blocker: stop and correct the reported problem;
Stale: the configuration changed, so run Preflight again.

System Preflight for the 25-client Fan-out plan showing the plan summary, Ready with warnings, and the Start action — Preflight must describe the workload you intend to run and contain no unresolved Blocker.
Confirm 25 Clients, 2 Groups, 34 connects/s, and your exact target.
Review every warning and start only when no Blocker remains.

With Warm-up set to 0, Start moves from Setup directly into the 45-second Measurement and then Disconnecting.

4. Confirm your Benchmark is running

During Measurement, compare the live cards with the plan:

Online = 25: one Publisher plus 24 Subscribers;
Send Rate ≈ 1.0 msgs/s: the Scheduled Message is active;
Recv Rate ≈ 24.0 msgs/s: every publish reaches all 24 Subscribers;
Connection Health = Healthy: Connect, Disconnect, and Subscribe errors remain zero.

Running Fan-out Measurement with 25 online clients, one sent and 24 received messages per second, and zero connection errors — The relationship between Online, Send Rate, and Recv Rate proves that the baseline is running as configured.
Online 25 matches one Publisher plus 24 Subscribers.
Send 1.0, Recv 24.0, and zero errors are the first-run success signal.

Success: your first Benchmark is now running against your authorized Broker. You can stop here—the five-minute path is complete. Continue only if you want to interpret, export, customize, troubleshoot, or remove it.

Understand and export the result

After 45 seconds, require Showing last run snapshot · Completed and a Phase Timer of 00:00:45. The live Online, Send Rate, and Recv Rate correctly return to zero after Disconnecting; use the retained charts to judge the finished Measurement.

On Latency:

RTT P50 / P90 / P99 measure QoS 1 PUBLISH to PUBACK;
E2E P50 / P90 / P99 measure the Publisher–Broker–Subscriber path.

Completed 45-second Benchmark snapshot with disconnected clients and retained RTT and end-to-end latency charts — Completed and the retained charts prove the Measurement finished; zero live rates show teardown completed.
Completed and 00:00:45 are the terminal evidence for this run.
RTT covers the acknowledgement path; E2E covers delivery to Subscribers.

These values describe only this run. A loopback result is not a remote Broker capacity claim. Keep the Broker, network path, Payload, QoS, scale, duration, and load-generator host comparable before comparing two runs.

To keep portable evidence, open Chart actions → Export All Data. Mqttable downloads benchmark_all_charts_data.csv; the formal export contains Measurement rows and excludes Warm-up rows.

Completed Benchmark result with Chart actions open and Export All Data available — Export All Data preserves the completed Measurement outside the live chart.
Choose the time window, then use Export All Data for the Measurement CSV.

Customize, troubleshoot, and clean up

Turn the baseline into your Benchmark

Change one dimension at a time so the next result remains explainable:

edit the Broker when the endpoint, transport, or Credential refs change;
edit Group totals and connection targets to change connection scale;
edit the Scheduled Message to change Topic, interval, Payload, or QoS;
edit the Subscription to keep its Topic filter and QoS aligned with the Publisher;
load another built-in example only after reviewing and reducing its default scale.

Every configuration change makes the previous Preflight stale. Run it again before Start.

Fix the first common failures

Connection test fails: verify protocol, host, port, Broker listener, TLS refs, and authentication before creating load.
Online remains below 25: inspect Connect and Subscribe errors, then verify the Group Client ID generators and credentials.
Send is near 1 but Recv is 0: verify that the publish Topic matches the Subscription filter; the baseline requires fo/data against fo/#.
Preflight reports a warning or Blocker: review the exact host and target evidence. Never bypass a Blocker, and stop when errors or resource use reach an unacceptable limit.

Keep or remove the baseline

Keep the target if you want to edit and rerun it. To remove it, stop any active run, select the exact Broker identity you created in step 1, then choose Delete in Edit Broker. The screenshot shows the documentation identity Bench Docs Demo; select your own exact name instead.

Edit Broker dialog for the example Bench Docs Demo target with the destructive Delete action — Delete only the exact tutorial target; this also removes its Groups, Clients, and related Benchmark data.
Confirm the selected identity is the target you created before deleting it.
Delete is irreversible and removes the target with its related Benchmark state.

Capability and safety boundaries:

Run load only against a Broker you own or are explicitly authorized to test. Never use a public or production Broker for this tutorial.
Free supports 1–600 seconds of Measurement per run. Pro removes that duration limit; Run Duration = 0 means unlimited Measurement and therefore requires Pro.
This path uses Local Runtime. Authenticated Remote Runtime requires a current online Pro entitlement and the required permissions.
Preflight and Monitor describe the load-generator Runtime host, not a remote Broker's internal CPU, memory, or storage.
Stopping during Setup or Warm-up leaves no formal result; stopping during Measurement leaves incomplete evidence. A full Measurement and teardown becomes Completed.

After this baseline, use Monitor to correlate Runtime resources with Benchmark phases, or Proxy to introduce controlled network faults.