HiveMQ Swarm

Introduction to the HiveMQ Swarm

HiveMQ Swarm is an advanced IoT testing and simulation tool that gives you the load and reliability testing ability you need to determine the resilience and capacity of your complete IoT system.

IoT solutions usually involve massive distributed systems. Although MQTT system testing is an imperative for every business-critical IoT solution, successfully simulating your end-to-end production environment can be a big challenge.

HiveMQ Swarm provides a distributed simulation environment to successfully test millions of MQTT clients, with millions of MQTT messages, and hundreds of thousands MQTT topic names. With HiveMQ Swarm you can identify scalability, performance, and reliability issues, before they require costly and time-consuming correction in the field.

HiveMQ Swarm Features

Establish complete end-to-end testing of your IoT solution. HiveMQ Swarm lets you discover potential bottlenecks in your system before you deploy.
Create millions of unique network connections on a distributed platform. Use HiveMQ Swarm agents to spawn client connections from anywhere in the world.
Simulate millions of devices, messages, and MQTT topics. Scale your testing up and down to simulate actual production scenarios.
Develop reusable scenarios to simulate device behavior. Integrate your HiveMQ Swarm scenarios into your continuous development pipeline to ensure ongoing testing.
Create custom data generators that simulate complex use cases. Generate custom data to accurately replicate your unique application.
Produce intuitive reports to provide immediate feedback on test results. Use a pre-defined Grafana dashboard to quickly visualize your results or customize a dashboard to fit your requirements.
Set up easy resource-friendly deployments to public clouds such as AWS and Azure or on-premise Kubernetes deployments.

HiveMQ Swarm Quick Start Guide

You can run HiveMQ Swarm on your local machine straight out of the box. To help you get started quickly, the HiveMQ Swarm package contains a simple example scenario and a basic configuration that you can use for local execution.

Install HiveMQ Swarm

Since HiveMQ 4.6 platform release, HiveMQ Swarm is included in the tools folder of the HiveMQ Professional and HiveMQ Enterprise edition bundles:

└─ <HiveMQ folder>
    ├─ bin
    ├─ config
    ├─ data
    ├─ extensions
    ├─ license
    ├─ log
    ├─ third-party-licenses
    ├─ tools
    │   ├─ hivemq-swarm
    │   └─ ...

If you are using a trial version of the HiveMQ broker, you are limited to 25 client connections. Similarly, the trial version of HiveMQ Swarm only allows 25 clients and 1 agent. To run HiveMQ Swarm scenarios that require more connections, contact our sales team to request an extended evaluation licence or to learn more about HiveMQ Swarm options.

To activate your full version of HiveMQ Swarm, open to the tools folder of your HiveMQ instance and move your .slic file for HiveMQ Swarm into the hivemq-swarm/license folder.

Review the Directory Structure

HiveMQ Swarm has the following directory structure:

|-- Readme.md
|-- bin
    |-- hivemq-swarm
    `-- hivemq-swarm.bat
|-- config
    |-- Readme.md
    |-- config.xml
    |-- config.xsd
    `-- logback.xml
|-- lib
|-- license
|-- extensions
    `-- Readme.md
|-- scenario
    |-- Readme.md
    |-- scenario.xml
    `-- scenario.xsd
|-- scenario-dependencies
    `-- Readme.md

Table 1. HiveMQ Swarm Directory Content
Directory Name	Description
`bin`	Contains your HiveMQ Swarm executables: `hivemq-swarm` executes HiveMQ Swarm on Unix systems.
`config`	Contains your HiveMQ Swarm configuration: `config.xml` defines the configuration of your HiveMQ Swarm. `config.xsd` contains an XML schema file that formally describes the elements and structure of the HiveMQ Swarm `config.xml` file. `logback.xml` defines the logging configuration of your HiveMQ Swarm. *
`lib`	Contains the dependencies of your HiveMQ Swarm executable. *
`license`	Contain the `.slic` file for HiveMQ Swarm. If you have not yet installed a HiveMQ Swarm licence, clustering is disabled and the simulation is limited to 25 clients. To acquire a HiveMQ Swarm license, contact sales@hivemq.com.
`extensions`	Contains optional extension files that extend the logic of HiveMQ Swarm. All extensions in this directory must be in `.jar` files. The standard security extension is included by default.
`scenario`	Contains the scenario that HiveMQ Swarm executes: `scenario.xml` defines the configuration of the scenario that HiveMQ Swarm executes. contains an XML schema file that formally describes the elements and structure of the `scenario.xml` file. NOTE: If more than one `.xml` file is located in the `scenario` folder, HiveMQ Swarm ignores all of the files and the scenario fails.
`scenario-dependencies`	Must contain all resources that extensions in the `extensions` directory require for the selected scenario.

Run an Example Scenario

The example scenario provided in the scenario directory of your unpacked HiveMQ Swarm connects 10 MQTT clients to an MQTT broker at localhost:1883.
When you run the example scenario, each client publishes 10 messages and then disconnects.

Set Up a HiveMQ Test Broker

You can run a HiveMQ Enterprise MQTT broker in a convenient Docker container:

To make sure that you are running the most current version of HiveMQ, enter:

$ docker pull hivemq/hivemq4

To run HiveMQ in a Docker container, enter:

$ docker run --ulimit nofile=500000:500000 -p 8080:8080 -p 8000:8000 -p 1883:1883 hivemq/hivemq4

Or, follow this installation guide to download and install HiveMQ from a convenient ZIP file.

The official hivemq/hivemq-swarm Docker image is available for download on Docker Hub. HiveMQ Swarm is not part of the hivemq/hivemq4 Docker image.

Execute the Example Scenario Locally

To execute HiveMQ Swarm and start the example scenario on your local machine, go to the unpacked directory of HiveMQ Swarm and enter the one of the following commands, based on your operating system:

For Unix-based systems such as Linux and macOS:

$ ./bin/hivemq-swarm

Check Scenario Execution on the HiveMQ Control Center

To verify that the publishes in the example scenario executed successfully, open your HiveMQ Control Center.

If a HiveMQ instance is running on your local machine, and the default configuration of the HiveMQ Control Center is enabled, you can navigate to the http://localhost:8080/ URL to view your control center.

Control Center Views

Next Steps

Customize the example scenario to meet the specific needs of your individual use case.

For more information, see Create a HiveMQ Swarm Scenario.