HiveMQ Swarm Example Scenarios

You can use these example scenarios to become familiar with HiveMQ Swarm and as a basis for your own scenarios.

If you are currently using a test licence for your HiveMQ broker, you are limited to 25 client connections. Similarly, the test version of HiveMQ Swarm allows 25 clients and 1 agent. To run HiveMQ scenarios that require more connections, contact our sales team to request an extended evaluation licence or upgrade to a HiveMQ professional or enterprise edition.

Reconnect Storm Scenario

Run this type of scenario to test the resiliency of your IoT solution.

This four-stage scenario creates 25 MQTT clients in a clients client group, and assigns clients a series of client IDs from client-00 to client-24.

The stages in a scenario execute sequentially. The lifecycles in each stage begin simultaneously.

In the connect-stage of the scenario, all 25 clients in the clients client group connect to the node-1 broker within 10 seconds.
The linear spread defined in the delay of the connect-lifecycle distributes the client connections evenly within the 10-second delay duration. For example, client-00 connects in 0 seconds, client-12 connects in 5 seconds, and client-24 connects in 10 seconds (1).

After all 25 clients are connected, the clients in the clients client group proceed to the second stage of the scenario and instantly disconnect from the node-1 broker (2).

After the clients simultaneously disconnect, all clients in the clients client group proceed to the third stage of the scenario and instantly connect to the node-2 broker (3).

After the clients instantly connect to the second broker, the clients client group proceeds to the final stage of the scenario and sequentially disconnect from the node-2 broker.
The linear spread defined in the delay of disconnect-lifecycle-2 distributes the disconnection evenly within the 10-second delay duration. For example, client-00 in 0 seconds, client-12 in 5 seconds, and client-24 in 10 seconds (4).

After the last client disconnects, the last stage is done, and the scenario ends.

Reconnect storm scenario code example

<scenario>
    <brokers>
        <broker id="node-1">
            <address>localhost</address>
            <port>1883</port>
        </broker>
        <broker id="node-2">
            <address>localhost</address>
            <port>1884</port>
        </broker>
    </brokers>
    <clientGroups>
        <clientGroup id="clients">
            <clientIdPattern>client-[0-9]{2}</clientIdPattern>
            <count>25</count>
        </clientGroup>
    </clientGroups>
    <stages>
        <stage id="connect-stage">
            <!-- 1 -->
            <lifeCycle id="connect-lifecycle" clientGroup="clients">
                <delay duration="10s" spread="linear"/>
                <connect broker="node-1"/>
            </lifeCycle>
        </stage>
        <stage id="disconnect-stage">
            <!-- 2 -->
            <lifeCycle id="disconnect-lifecycle" clientGroup="clients">
                <disconnect/>
            </lifeCycle>
        </stage>
        <stage id="connect-stage-2">
            <!-- 3 -->
            <lifeCycle id="connect-lifecycle-2" clientGroup="clients">
                <connect broker="node-2"/>
            </lifeCycle>
        </stage>
        <stage id="disconnect-stage-2">
            <!-- 4 -->
            <lifeCycle id="disconnect-lifecycle-2" clientGroup="clients">
                <delay duration="10s" spread="linear"/>
                <disconnect/>
            </lifeCycle>
        </stage>
    </stages>
</scenario>

Fan-out Scenario

This scenario creates a publisher client group with a single MQTT client (1), and a subscribers client group with 10 MQTT clients. The clients in the subscribers client group are assigned a series of client identifiers from subscriber-00 to subscriber-09 (2).
The scenario also creates a topic topic group with a one topic/subtopic topic (3).

In the first stage of the scenario, all clients in the subscribers client group connect to the b1 broker and subscribe to the topic topic group (4).
At the same time, the single client in the publisher client group also connects to the b1 broker (5).

In the second stage of the scenario, each client in the subscribers client group waits for 1,000 incoming MQTT messages on the topic topic group (6).
At the same time, the client in the publisher client group publishes 1,000 MQTT messages on the topic topic group (7).

The result is 11,000 exchanged MQTT PUBLISH messages. The publisher sends 1,000 MQTT messages to HiveMQ and HiveMQ forwards a total of 10,000 MQTT messages to the subscribers (1,000 messages per subscriber).

In the third and final stage of the scenario, all clients in both client groups disconnect, and the scenario ends (8).

Fan-out scenario code example

<scenario>
    <brokers>
        <broker id="b1">
            <address>localhost</address>
            <port>1883</port>
        </broker>
        </brokers>
        <clientGroups>
            <!-- 1 -->
            <clientGroup id="publisher">
                <clientIdPattern>publisher</clientIdPattern>
            </clientGroup>
            <!-- 2 -->
            <clientGroup id="subscribers">
                <clientIdPattern>subscriber-[0-9]</clientIdPattern>
                <count>10</count>
            </clientGroup>
        </clientGroups>
        <topicGroups>
            <!-- 3 -->
            <topicGroup id="topic">
                <topicNamePattern>topic/subtopic</topicNamePattern>
            </topicGroup>
        </topicGroups>
        <stages>
            <stage id="s1">
                <!-- 4 -->
                <lifeCycle id="connect-subscribers" clientGroup="subscribers">
                    <connect broker="b1"/>
                    <subscribe to="topic"/>
                </lifeCycle>
                <!-- 5 -->
                <lifeCycle id="connect-publishers" clientGroup="publisher">
                    <connect broker="b1"/>
                </lifeCycle>
            </stage>
            <stage id="s2">
                <!-- 6 -->
                <lifeCycle id="subscriber-wait" clientGroup="subscribers">
                    <receive count="1000" from="topic"/>
                </lifeCycle>
                <!-- 7 -->
                <lifeCycle id="publish" clientGroup="publisher">
                    <publish topicGroup="topic" count="1000"/>
                </lifeCycle>
            </stage>
            <stage id="s3">
                <!-- 8 -->
                <lifeCycle id="disconnect-subscribers" clientGroup="subscribers">
                    <disconnect/>
                </lifeCycle>
                <!-- 9 -->
                <lifeCycle id="disconnect-publisher" clientGroup="publisher">
                    <disconnect/>
                </lifeCycle>
            </stage>
        </stages>
</scenario>

Fan-in Scenario

This scenario creates a publishers client group with 10 MQTT clients (1) and a subscriber client group with one MQTT client (2). The clients in the publishers client group are assigned client identifiers from publisher-00 to publisher-09.
The scenario also creates a topic topic group with a one topic/subtopic topic (3).

In the first stage of the scenario, the single client in the subscriber client group connects to the b1 broker and subscribes to the topic topic group (4).
At the same time, all clients in the publishers client group also connect to the b1 broker (5).

In the second stage of the scenario, the single client in the subscriber client group waits for 10,000 incoming MQTT messages to arrive on the topic topic group (6).
At the same time, each client in the publishers client group publishes 1,000 MQTT messages to the topic topic group (7).

The result is 20,000 exchanged MQTT PUBLISH messages. The 10 clients that publish send a total of 10,000 MQTT messages to HiveMQ and HiveMQ forwards 10,000 MQTT messages to the subscriber.

In the third and final stage of the scenario, the clients of both client groups disconnect, and the scenario ends (8).

Fan-in scenario code example

<scenario>
    <brokers>
        <broker id="b1">
            <address>localhost</address>
            <port>1883</port>
        </broker>
    </brokers>
    <clientGroups>
        <!-- 1 -->
        <clientGroup id="publishers">
            <clientIdPattern>publisher-[0-9]</clientIdPattern>
            <count>10</count>
        </clientGroup>
        <!-- 2 -->
        <clientGroup id="subscriber">
            <clientIdPattern>subscriber</clientIdPattern>
        </clientGroup>
    </clientGroups>
    <topicGroups>
        <!-- 3 -->
        <topicGroup id="topic">
            <topicNamePattern>topic/subtopic</topicNamePattern>
        </topicGroup>
    </topicGroups>
    <stages>
        <stage id="s1">
            <!-- 4 -->
            <lifeCycle id="connect-subscribers" clientGroup="subscriber">
                <connect broker="b1"/>
                <subscribe to="topic"/>
            </lifeCycle>
            <!-- 5 -->
            <lifeCycle id="connect-publishers" clientGroup="publishers">
                <connect broker="b1"/>
            </lifeCycle>
        </stage>
        <stage id="s2">
            <!-- 6 -->
            <lifeCycle id="subscriber-wait" clientGroup="subscriber">
                <receive count="10000" from="topic"/>
            </lifeCycle>
            <!-- 7 -->
            <lifeCycle id="publish" clientGroup="publishers">
                <publish topicGroup="topic" count="1000"/>
            </lifeCycle>
        </stage>
        <!-- 8 -->
        <stage id="s3">
            <lifeCycle id="disconnect-subscriber" clientGroup="subscriber">
                <disconnect/>
            </lifeCycle>
            <lifeCycle id="disconnect-publishers" clientGroup="publishers">
                <disconnect/>
            </lifeCycle>
        </stage>
    </stages>
</scenario>

Ping-pong Scenario

Run this scenario to see how client groups interact with each other when you use the receive command.

The scenario creates two client groups with 10 MQTT clients each, and a topic group with 10 topics:

A pingers client group with a series of client IDs from pinger-0 to pinger-9(1).
A pongers client group with a series of client IDs from ponger-0 to ponger-9 (2).
A pingPong topic group with a series of topic names from pingpong-1 to pingpong-9 (3)

In the first stage of the scenario, every client in the pingers client group connects to the b1 broker and subscribes to the pingPong topic group (4).
At the same time, every client in the pongers client group connects to the b1 broker and also subscribes to the pingPong topic group (5).

Once all commands in the lifecycles of the first stage are complete, the two client groups proceed to the next stage of the scenario.

In the second stage of the scenario, every client in the pingers client group publishes an MQTT message with the message payload ping for 10 iterations to the pingpong topic group, and then waits for 10 incoming messages on the pingPong topic group (6).
At the same time, every client in the pongers client group waits for 10 incoming messages with the message pattern ping from the pingPong topic group, and then publishes an MQTT message with the message payload pong to the pingpong topic group for 10 iterations (7).

Once all commands in the lifecycles of the second stage are complete, the two client groups proceed to the next stage of the scenario.

In the third stage of the scenario, every client in the pingers client group publishes an MQTT message with the message payload ping 10 times to the pingpong topic group, and then waits for 10 incoming messages on the pingPong topic group (8).
At the same time, every client in the pongers client group waits for 10 incoming messages with the message pattern ping from the pingPong topic group, and then publishes an MQTT message with the message payload pong 10 times to the pingpong topic group (9).

Once all commands in the lifecycles of the second stage are complete, the two client groups proceed to the next stage of the scenario.

In the final stage of the scenario, all clients in both client groups disconnect, and the scenarios ends.

Ping-pong scenario code example

<scenario>
    <brokers>
        <broker id="b1">
            <address>localhost</address>
            <port>1883</port>
        </broker>
    </brokers>

    <clientGroups>
        <!-- 1 -->
        <clientGroup id="pingers">
            <clientIdPattern>waiter-[0-9]</clientIdPattern>
            <count>10</count>
        </clientGroup>
        <!-- 2 -->
        <clientGroup id="pongers">
            <clientIdPattern>blocker-[0-9]</clientIdPattern>
            <count>10</count>
        </clientGroup>
    </clientGroups>

    <topicGroups>
        <!-- 3 -->
        <topicGroup id="pingPong">
            <topicNamePattern>pingpong-[0-9]</topicNamePattern>
            <count>10</count>
        </topicGroup>
    </topicGroups>

    <stages>
        <stage id="s1">
            <!-- 4 -->
            <lifeCycle id="s1.l1" clientGroup="pingers">
                <connect broker="b1"/>
                <subscribe to="pingPong"/>
            </lifeCycle>
            <!-- 5 -->
            <lifeCycle id="s1.l2" clientGroup="pongers">
                <connect broker="b1"/>
                <subscribe to="pingPong"/>
            </lifeCycle>
        </stage>
        <stage id="s2">
            <!-- 6 -->
            <lifeCycle id="s2.l1" clientGroup="pingers">
                <for times="10">
                    <publish topicGroup="pingPong" message="ping"/>
                    <receive from="pingPong" messagePattern="pong"/>
                </for>
            </lifeCycle>
            <!-- 7 -->
            <lifeCycle id="s2.l2" clientGroup="pongers">
                <for times="10">
                    <receive from="pingPong" messagePattern="ping"/>
                    <publish topicGroup="pingPong" message="pong"/>
                </for>
            </lifeCycle>
        </stage>
        <stage id="s3">
            <!-- 8 -->
            <lifeCycle id="s3.l1" clientGroup="pingers">
                <publish topicGroup="pingPong" message="ping" count="10"/>
                <receive from="pingPong" messagePattern="pong" count="10"/>
            </lifeCycle>
            <!-- 9 -->
            <lifeCycle id="s3.l2" clientGroup="pongers">
                <receive from="pingPong" messagePattern="ping" count="10"/>
                <publish topicGroup="pingPong" message="pong" count="10"/>
            </lifeCycle>
        </stage>
        <!-- 10 -->
        <stage id="s4">
            <lifeCycle id="s4.l1" clientGroup="pingers">
                <disconnect/>
            </lifeCycle>
            <lifeCycle id="s4.l2" clientGroup="pongers">
                <disconnect/>
            </lifeCycle>
        </stage>
    </stages>
</scenario>

The following diagram shows how the receive command in the ping-pong scenario is used to ensure that all 10 clients in the ping client group publish before the client in the pong client group are allowed to publish.

Ping-pong Scenario

Custom Timer Scenario

Run this scenario to see how you can use the timer command to capture metrics for specific events.

This scenario creates a clients client group with 10 MQTT clients that are assigned the client identifiers A-01 to A-9 (1), a test topic group with the topic test/ping (2), and an own subscription that references the test topic group (3).

In the first stage of the scenario, all clients in the clients client group connect to the b1 broker and subscribe to the own subscription (4).

In the second stage of the scenario, each client in the clients client group starts a timer and publishes 10 MQTT messages with the message payload test, QoS level 2, and the retained message flag set to true on the test topic group. After publication, each client in the clients client group waits for 10 incoming messages on the own subscription and then stops the timer (5).

In the third stage of the scenario, all clients in the client client group disconnect and the scenario ends.

The custom timer tracks the length of time publishing and receiving a specific message requires. HiveMQ Swarm captures the startTimer and stopTimer values in a custom metric. In this example, the name of the resulting metric is agent_timer_test.

Custom timer scenario code example

<scenario>

    <brokers>
        <broker id="b1">
            <address>localhost</address>
            <port>1883</port>
        </broker>
    </brokers>

    <clientGroups>
        <!-- 1 -->
        <clientGroup id="clients">
            <clientIdPattern>A[0-9]</clientIdPattern>
            <count>10</count>
        </clientGroup>
    </clientGroups>

    <topicGroups>
        <!-- 2 -->
        <topicGroup id="test">
            <topicNamePattern>test/ping</topicNamePattern>
        </topicGroup>
    </topicGroups>

    <subscriptions>
        <!-- 3 -->
        <subscription id="own">
            <topicGroup>test</topicGroup>
        </subscription>
    </subscriptions>

    <stages>
        <stage id="s1">
        <!-- 4 -->
            <lifeCycle id="waiters-1" clientGroup="clients">
                <connect broker="b1"/>
                <subscribe to="own"/>
            </lifeCycle>
        </stage>
        <stage id="s2">
        <!-- 5 -->
            <lifeCycle id="publish" clientGroup="clients">
                <for times="10">
                    <startTimer id="test"/>
                    <publish topicGroup="test" message="test" qos="2" retain="true"/>
                    <receive from="own"/>
                    <stopTimer id="test"/>
                </for>
            </lifeCycle>
        </stage>
        <stage id="s3">
        <!-- 6 -->
            <lifeCycle id="disconnect" clientGroup="clients">
                <disconnect/>
            </lifeCycle>
        </stage>
    </stages>
</scenario>

Publication Spikes Scenario

Run this scenario to see how the for command impacts the iteration of actions in a lifecycle.

This scenario creates a publishers client group of 25 clients with the client identifiers A0000 to A0024 (1) and a topics topic group with a single topic topic (2).

In the first and only stage of the scenario, all 25 clients in the publishers client group connect to the b1 broker.
Next, each client in the publishers client group publishes 100 messages every 10 seconds to the topics topic group for a total of 5 times and then disconnects (4).

Use of the for command creates a message spike of 2,500 messages every 10 seconds for 5 iterations.

Once all clients disconnect, the stage is complete, and the scenario ends.

Publication spikes scenario code example

<scenario>
    <brokers>
        <broker id="b1">
            <address>localhost</address>
            <port>1883</port>
        </broker>
    </brokers>
    <!-- 1 -->
    <clientGroups>
        <clientGroup id="publishers">
            <clientIdPattern>A[0-9]{4}</clientIdPattern>
            <count>25</count>
        </clientGroup>
    </clientGroups>
    <!-- 2 -->
    <topicGroups>
        <topicGroup id="topics">
            <topicNamePattern>topic</topicNamePattern>
        </topicGroup>
    </topicGroups>
    <stages>
        <stage id="s1">
        <!-- 3 -->
            <lifeCycle id="s1.l1" clientGroup="publishers">
                <connect broker="b1"/>
            </lifeCycle>
        </stage>
        <stage id="s2">
            <lifeCycle id="s2.l1" clientGroup="publishers">
                <for times="5" rate="1/10s">
                    <publish topicGroup="topics" count="100"/>
                </for>
            </lifeCycle>
        </stage>
        <stage id="s3">
            <lifeCycle id="s3.l1" clientGroup="publishers">
                <disconnect/>
            </lifeCycle>
        </stage>
    </stages>
</scenario>

Steady Publication Load Scenario

This scenario creates a publishers client group of 25 clients with the client identifiers A0000 to A0024 (1) and a topics topic group with a single topic topic (2).

In the first and only stage of the scenario, all 25 clients in the publishers client group connect to the b1 broker.
Next, each client in the publishers client group publishes 100 messages each to the topics topic group at a rate of 1 event (the publication of 100 messages) per second and then disconnects (3).

This scenario creates an overall publication rate of 25 messages per second.

Steady publication load scenario code example

<scenario>
    <brokers>
        <broker id="b1">
            <address>localhost</address>
            <port>1883</port>
        </broker>
    </brokers>
    <clientGroups>
        <!-- 1 -->
        <clientGroup id="publishers">
            <clientIdPattern>A[0-9]{4}</clientIdPattern>
            <count>25</count>
        </clientGroup>
    </clientGroups>
    <!-- 2 -->
    <topicGroups>
        <topicGroup id="topics">
            <topicNamePattern>topic</topicNamePattern>
        </topicGroup>
    </topicGroups>
    <stages>
        <!-- 3 -->
        <stage id="s1">
            <lifeCycle id="publish" clientGroup="publishers">
                <connect broker="b1"/>
                <publish topicGroup="topics" count="100" rate="1/1s"/>
                <disconnect/>
            </lifeCycle>
        </stage>
    </stages>
</scenario>

Persistent Session Scenario

This scenario adds node-1, node-2, and node-3 to a HiveMq Swarm cluster (1) and creates the following entities:

A subscribers client group with 24 MQTT clients and the client IDs subscriber-00 to subscriber-23 (2)
A publisher client group with 1 MQTT client (3).
An exclusive-topics topic group with 24 topics named topic/subtopic-00 to topic/subtopic-23 (4).

In the initial subscribe stage of the scenario, all 24 clients in the subscribers client group connect to the node-1 broker with a 2-day session expiry setting, and a clean start flag set to true to create a persistent session (5).
Next, each client in the subscribes client group subscribes to the associated topic in the exclusive-topics topic group, and then disconnects (6). For example, subscriber-00 subscribes to topic/subtopic-00, and so on.

In the publish stage of the scenario, the single client in the publisher client group connects to the node-2 broker, publishes 10 messages with QoS 2 to each topic in the exclusive-topics topic group (a count of 240 messages total), and then disconnects (7).

In the final receive stage of the scenario, all clients in the subscribers client group reconnect to the node-3 broker. Each client receives 10 messages, and then disconnects (8).

Once all clients disconnect, the last stage is complete, and the scenario ends.

Persistent session scenario code example

<scenario>
    <brokers>
        <!-- 1 -->
        <broker id="node-1">
            <address>localhost</address>
            <port>1883</port>
        </broker>
        <broker id="node-2">
            <address>localhost</address>
            <port>1884</port>
        </broker>
        <broker id="node-3">
            <address>localhost</address>
            <port>1885</port>
        </broker>
    </brokers>
    <clientGroups>
        <!-- 2 -->
        <clientGroup id="subscribers">
            <clientIdPattern>subscriber-[0-9]{2}</clientIdPattern>
            <count>24</count>
        </clientGroup>
        <!-- 3 -->
        <clientGroup id="publisher">
            <clientIdPattern>publisher</clientIdPattern>
        </clientGroup>
    </clientGroups>
    <topicGroups>
        <!-- 4 -->
        <topicGroup id="exclusive-topics">
            <topicNamePattern>topic/subtopic-[0-9]{2}</topicNamePattern>
            <count>24</count>
        </topicGroup>
    </topicGroups>
    <stages>
        <stage id="subscribe">
            <lifeCycle id="subscribers-1" clientGroup="subscribers">
                <!-- 5 -->
                <connect broker="node-1" sessionExpiry="2d" cleanStart="true"/>
                <!-- 6 -->
                <subscribe to="exclusive-topics"/>
                <disconnect/>
            </lifeCycle>
        </stage>
        <!-- 7 -->
        <stage id="publish">
            <lifeCycle id="publishers-1" clientGroup="publisher">
                <connect broker="node-2"/>
                <publish topicGroup="exclusive-topics" count="240" qos="2"/>
                <disconnect/>
            </lifeCycle>
        </stage>
        <!-- 8 -->
        <stage id="receive">
            <lifeCycle id="subscribers-2" clientGroup="subscribers">
                <connect broker="node-3" cleanStart="false"/>
                <receive count="10"/>
                <disconnect/>
            </lifeCycle>
        </stage>
    </stages>
</scenario>