Home

Awesome

aws-iot-mqtt-load-generator

Configurable load generator for MQTT messages

LoadConfiguration

A load configuration is the entity that as a unit can be started and stopped. A load configuration contains:

A running load configuration is called a metrics series.

Topic

The topic that the metrics series are published to. The topic can contain the following variables that will be replaced in runtime:

Templates

Two kinds of templates are supported by the load generator. JSON and CSV.

The templates cannot currently be created or edited in the GUI, but can be visualized.

The templates can contain a number of variables that will be replaced when instantiated. The form of a template parameter is a ”$” followed by the template variable. The following template parameters are supported:

Control topic

A running load generator can be controlled through a control topic. The commands can either be a string with the command in capital letters, or a json with an attribute called "action" and the value being a string in all caps with the command.

The following commands are supported:

The following variables are supported in the control-topic:

Functions

Each function has a function type which will specifify the types of values and the configuration parameters supported. A function will generate a single output value based on the following input parameters:

Each function specifies the output variable name, that can be used in templates.

RANDOM

Genarate a random value, either of Integer or float type.

The parameters supported are:

TEXT

A function which will generate a single text value, from a configured set. It can be randomly selected through a set of weights. The sum of all the weights are added and a random number is generated to select the string randomly with probability according to the weights.

The supported parameters are:

EXPR

Algorithmic expression evaluation function where the alogirhtmic language supported by the exp4j library http://www.objecthunter.net/exp4j/. For example complex algorithmic expressions "X^3+4+sin(x)*x^2” can be expressed and generate interesting behaviors over time.

In the expressions the variables ”tick” and ”elapsed” are available for modelling. Elapsed is in milliseconds.

The parameters supported by the EXPR function are:

In addition to the standard functinality of exp4j two custom functions have been added:

API

There is a REST-API, the resource endpoint is <host>:<port>/mqttloadapp/webresources. The API only supports application/json as content type.

The API resources are

/config
	- GET - Return a list of load config ids as well as their "running" status
	- POST - Create a new Load configuration representation with the content of the POST body
	/{load config id}
		- GET - Return the detailed Load config object
		- PUT - Updates the representation of the load config object
		- POST - Start a metrics series based on the config
		- DELETE - Yupp, you guessed it, it deletes the load config

/series
	- GET - Returns a list of running metrics series
	/{load config id}
		- DELETE - Deletes the metrics series and stops the process generating load
		- GET - Retrieve information about the running metrics series

/template
	GET - Returns a list of templates
	POST - Create template
	/{template-id}
		GET - Returns the template object
		DELETE - Delete the template

Examples

Create Load Configuration

Create a load configuration with 2 functions, publishing values to the "foo/expr" topic at a rate of 5 per minute. One with random int values between 10 and 100 assigned to variable y. Another one with calculating the cosine of the scaled number of ticks, by a factor of 10. So that the first value will have a value of cos(0.1), second one cos(0.2) and the 100th will have cos(10.9), this function value will be assigned variable when instantiating the template.

{
    "functions": [
        {
            "function": "RANDOM",
            "variable": "y",
            "parameters": [
                {
                    "type": "INT",
                    "maxvalue" : 1000,
                    "minvalue" : 10
                }
            ]
        },
        {
            "function": "EXPR",
            "variable": "x",
            "parameters": [
                {
                    "expression": "cos(tick) * elapsed^2 - tick^3",
					"tickscalefactor" : 10
                }
            ]
        }
    ],
    "rate": 5,
    "templateid": "test",
    "topic": "foo/expr"
}

Web Interface

The web interface is built using AngularJS and is completly stand-alone, it could be delivered as a separate deployment unit and served from S3, but given scope and the fact that a server needs to be available to run the load, the web interface is delivered from the packaged WAR-application

Server

The server is currently built and developed and tested using Glassfish 4 but should run a container supporting JAX-RS. A small tweak to the configuration had to be done to ellinimate a problem with a version of Guava in Glassfish "leaking" into the application and interfered with Guava functionality used in the application.

Configuration

Configuration locations can be either in a local file system or in S3. All S3 locations are on the form s3://<bucket>/<key>. When configuring the root, then all objects are accessed relative to that.

The values of the XYZ_root variables can either be done through java system properties or environment variables, in that order.

config_root

An absolute path to a local file system or an S3 object key on the format s3://<bucketname>/<s3-folder-prefix>.

mqtt.properties

Contains properties for establishing the connection to the MQTT Gateway of Icebreaker. The following properties need to be provided for the connection to the MQTT-broker

template_root

Template root can be either local filesystem or S3. By detault it's ${config_root}/templates. Template-files are stored in this location, files can have 2 extensions, ".csv" or ".json" indicating the formats supported. The name of a template is the file/object key infront of the extension.

loadconfig_root

Can be either local filesystem or S3, by default it's ${config_root}/loadconfig_root.

Getting started

Installation

There is a AWS CloudFormation template available that will spin up an AWS ElasticBeanstalk environment, in the default VPC of the account. The Beanstalk environment will be a single-instance configuration to keep the cost to a minimum. The template will have the following parameters:

Output parameters will be the URL at which the environment is accessible

Create a LoadConfiguration

Start a load configuration

Stop a running metrics series