You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
The version 1.0 is released at 18th, Dec, 2017. Now the plugin supports share MQTT connection in the same threadgroup. Also, this version fixed some of bugs reported in the community.
1
+
# mqtt-jmeter Overview
2
+
MQTT JMeter Plugin extends your JMeter's capability to test against MQTT protocol, just as easy as ordinary HTTP protocal.
3
3
4
-
# mqtt-jmeter
5
-
MQTT JMeter Plugin, it's used for testing MQTT protocol. The plugin was used for EMQ's performance benchmark test, and here is [report link](https://github.com/emqtt/emq-xmeter-cn).
6
-
The plugin is developed and maintained by [XMeter](https://www.xmeter.net). XMeter is a professional performance testing service provider.
4
+
It has been used to benchmark EMQ server performance, and here is the [report link](https://github.com/emqtt/emq-xmeter-cn).
5
+
6
+
This plugin is developed and maintained by [XMeter](https://www.xmeter.net). XMeter is a professional performance testing service provider.
7
7
8
8
# Install instruction
9
-
The plugin is a standard JMeter plugin. You can download the latest version of mqtt-jmeter from [here](https://github.com/emqtt/mqtt-jmeter/releases), and then copy the downloaded JAR files into $JMETER_HOME/lib/ext folder. After restart the JMeter, then you can see the 3 samplers provided by this plugin.
9
+
The plugin is a standard JMeter plugin. You can download the latest version of mqtt-jmeter from [here](https://github.com/emqtt/mqtt-jmeter/releases), and then copy the downloaded JAR files into $JMETER_HOME/lib/ext folder. After restarting the JMeter, you can see "MQTT samplers" provided by this plugin.
10
10
11
-
We recommend to use JMeter 3.0 or above.
11
+
To use this plugin, we recommend you to install JMeter 3.2 or above.
12
12
13
13
## Build from source code
14
14
15
15
If you'd like to build binary by yourself, please clone the project and run 'mvn install'. Maven will download some JMeter dependency binary files, so the build elapsed time will up to your network status.
16
16
17
17
# How to use
18
-
The plugin includes 3 samplers:
18
+
The plugin includes 4 samplers:
19
19
20
-
-Connection sampler, which can be used for connection mock. For example, in a large scale system, there could have lots of backend connections with no data transimission except some hearbeat signal. The sampler can be used in this case.
20
+
-Connect sampler: Initiate MQTT server connection on behalf of a device. In addition to normal connection setup, this sampler can be used to simulate massive "background" connections(no data transimission but regular hearbeat signals) to the designated MQTT server or cluster system.
21
21
22
-
- Pub sampler, which can be used for publish message to MQTT server.
22
+
- Pub sampler: publish various messages to the target MQTT server.
23
23
24
-
- Sub sampler, which can be used for sub message from MQTT server.
24
+
- Sub sampler: subscribe message(s) from target MQTT server.
25
25
26
-
If MQTT JMeter plugin is installed successfully, then open JMeter and below 3 MQTT samplers can be found under 'Sampler'.
26
+
- DisConnect sampler: Reset the connection to target MQTT server.
-**Server name or IP**: The server install with MQTT server, it can be either IP address or server name. The default value is 127.0.0.1. **DO NOT** add protocol (e.g. tcp:// or ssl://) before server name or IP address!
40
+
-**Server name or IP**: The MQTT target to be tested. It can be either IP address or server name. The default value is 127.0.0.1. **DO NOT** add protocol (e.g. tcp:// or ssl://) before server name or IP address!
40
41
41
-
-**Port number**: The port that opens by MQTT server, the default value is 1883 for TCP protocol, and normally 8883 for SSL protocol.
42
+
-**Port number**: The port opened by MQTT server. Typically 1883 is for TCP protocol, and 8883 for SSL protocol.
42
43
43
-
-**MQTT version**: The MQTT version, default is 3.1, and another option is 3.1.1. Sometimes the version is probably required for establish connection to [Azure IoTHub](https://github.com/emqtt/mqtt-jmeter/issues/21).
44
+
-**MQTT version**: The MQTT version, default is 3.1, and another option is 3.1.1. Sometimes we found version 3.1.1 is required to establish connection to [Azure IoTHub](https://github.com/emqtt/mqtt-jmeter/issues/21).
44
45
45
46
-**Timeout(s)**: The connection timeout seconds while connecting to MQTT server. The default is 10 seconds.
46
47
47
48
### MQTT Protocol
48
49
49
-
The sampler supports for 2 protocols, TCP and SSL. For the SSL protocol, it includes normal SSL and dual SSL authentication.
50
+
The sampler supports 2 protocols, TCP and SSL. For SSL protocol, it includes normal SSL and dual SSL authentication.
50
51
51
-
If **'Dual SSL authentication'** is checked, please follow 'Certification files for SSL/TLS connections' at end of this doc to set the client SSL configuration.
52
+
If **'Dual SSL authentication'** is checked, please follow 'Certification files for SSL/TLS connections' at end of this doc to set the client SSL configuration properly.
User can configure MQTT server with user name & password authentication, refer to [EMQ user name and password authentication guide](http://emqtt.com/docs/v2/guide.html#id3).
58
59
59
-
-**User name**: If MQTT server configured with user name, then specify user name here.
60
+
-**User name**: If MQTT server is configured with user name, then specify user name here.
60
61
61
-
-**Password**: If MQTT server configured with password, then specify password here.
62
+
-**Password**: If MQTT server is configured with password, then specify password here.
62
63
63
64
### Connection options
64
65
65
-
-**ClientId**: Identification of the client. (Default value is 'conn_'.) If 'Add random client id suffix' is selected, JMeter plugin will append generated uuid as suffix to represent the client, otherwise, the text of 'ClientId' will be passed as 'clientId' of current connection.
66
+
-**ClientId**: Identification of the client, i.e. virtual user or JMeter thread. Default value is 'conn_'. If 'Add random client id suffix' is selected, JMeter plugin will append generated uuid as suffix to represent the client, otherwise, the text of 'ClientId' will be passed as 'clientId' of current connection.
66
67
67
68
-**Keep alive(s)**: Ping packet send interval in seconds. Default value is 300, which means each connection sends a ping packet to MQTT server every 5 minutes.
68
69
69
-
-**Connection keep time(s)**: The value is to set the connection elapsed time after successfully establishing MQTT connection. The default value is 1800 seconds, which means that the connection will be alive within 30 minutes.
70
-
71
70
-**Connect attampt max**: The maximum number of reconnect attempts before an error is reported back to the client on the first attempt by the client to connect to a server. Set to -1 to use unlimited attempts. Defaults to 0.
72
71
73
72
-**Reconnect attampt max**: The maximum number of reconnect attempts before an error is reported back to the client after a server connection had previously been established. Set to -1 to use unlimited attempts. Defaults to 0.
74
73
75
-
## Pub sampler
76
-
77
-
78
-
For **MQTT connection**, **User authentication**, **Connection options** and **MQTT version** section settings, please refer to *Connection sampler* for more detailed information.
79
-
80
-
-**Share conn in thread**: This option allows all of pub and sub samplers in the same threadgroup shares the same connection, this can simulate the situation of one device can be either pub or sub. For example, one IoT device can either send message to server, or receive the control message from server. Please notice, only those samplers in the same threadgroup check this option, then the connection will be shared. Also, the connection settings of first pub/sub sampler in the threadgroup will be used for shared connections, rests of connection settings in other samplers will be ignored if the option is checked. Please take a look at following 3 examples.
81
-
82
-
```
83
-
ThreadGroupSample1
84
-
PubSampler1 (shared connection), the connection settings will be used for the shared connection.
85
-
SubSampler1 (shared connection), use shared connection of PubSampler1, the connection setting of this sampler will be ignored.
86
-
87
-
88
-
ThreadGroupSample2
89
-
PubSampler1 (shared connection), the connection settings will be used for the shared connection.
90
-
SubSampler1 (not shared connection), another connection will be created with configuration in this sampler.
91
74
75
+
## Pub Sampler
76
+
92
77
93
-
ThreadGroupSample3
94
-
PubSampler1 (not shared connection), one connection will be created for the connection setting in this sampler.
95
-
SubSampler1 (shared connection), the connection settings will be used for the shared connection.
96
-
SubSampler2 (shared connection), use shared connection of SubSampler1, so the connection setting of this sampler will be ignored.
97
-
98
-
```
78
+
Pub sampler reuses previously established connection (by Connect sampler) to publish a message. If connection is not ready at this moment, pub sampler will just fail immediately.
99
79
100
80
### Pub options
101
81
102
82
-**QoS level**: The available QoS value, 0 is AT_MOST_ONCE, 1 is AT_LEAST_ONCE and 2 is EXACTLY_ONCE.
103
83
104
-
-**Topic name**: The topic name that the message will send to.
84
+
-**Topic name**: Name of the topic that the message will be sent to.
105
85
106
-
-**Add timestamp in payload**: Add timestamp in the payload or not. If the checkbox is enabled, then timestamp of running pub sampler will be added ahead of payload. Mostly it can be used together with **Sub sampler** to calculate message latency time.
86
+
-**Add timestamp in payload**: Add timestamp in the payload or not. If the checkbox is enabled, then timestamp of running pub sampler will be added before real payload. Mostly it's used together with **Sub sampler** to calculate message latency time.
For **MQTT connection**, **User authentication**, **Connection options** and **MQTT version** section settings, please refer to *Connection sampler* for more detailed information.
101
+
## Sub Sampler
102
+
124
103
125
-
For **Share conn in thread**, please refer to the Pub sampler.
104
+
Sub sampler reuses previously established connection (by Connect sampler) to subscribe message(s). If connection is not ready at this moment, sub sampler will just fail immediately.
126
105
127
106
### Sub options
128
107
129
108
-**QoS level**: The available QoS value, 0 is AT_MOST_ONCE, 1 is AT_LEAST_ONCE and 2 is EXACTLY_ONCE.
130
109
131
-
-**Topic name**: The topic name that subscriber will subscribe to. If want to subscribe multiple topics, please use comma to separate the different topics.
110
+
-**Topic name(s)**: A list of topic names (comma-separated) that will be subscribed to.
132
111
133
112
-**Payload includes timestamp**: If the checkbox is enabled, then it means the payload includes timestamp. It can be used to calcuate the message latency time.
Please notice, if the machine publish message is not the same as subscriber, then the calculated message latency time is not accurate.
139
118
It's because the time is almost not the same in different machines. So the latency time calculated by sub sampler could be only be a reference.
140
119
```
141
-
-**Sample on**: It controls how to sample. The default value is '**elapsed with specified time(ms)**', which means a sub sampler will be occurred every ms specified in next text field (default is 1000ms). During the 1000 ms, multiple messages could be received, and result in report is the summarized data during 1000 ms. If the value is set to 2000, then means summarized report during 2000 ms. Another option is '**received number of message**', which means a sub sampler will be occurred when received number of message that specified in next text field (default is 1).
120
+
-**Sample on**: It controls how to sample. The default value is '**elapsed with specified time(ms)**', which means a sub sampler will occur every specified milli-seconds (default is 1000ms). During the 1000 ms, multiple messages could be received, and result in report is the summarized data during 1000 ms. If the value is set to 2000, then means summarized report during 2000 ms. Another option is '**number of received messages**', which means a sub sampler will occur after receiving these specified number of messages (default is 1).
121
+
122
+
-**Debug response**: If checked, the received message will be print in response. It's recommended to enable this option when you debug your script.
-**Debug response**: If it's checked, then the received message will be print in response. It's recommend to enable it when you're debugging script.
128
+
This sampler is very simple, it just clear the previous created connection. Therefore, next time you run Connect sampler, it will initiate a new MQTT server connection for you. As you can imagine, Disconnect sample will fail immediately if no connection is detected at this moment.
129
+
130
+
131
+
## Example JMeter Scripts
132
+
As a reference, you can check out some example scripts in SampleScripts folder.
133
+
1) background_connection.jmx:
134
+
Simulate massive background MQTT connections to server. You can optionally subscribe to a topic when connecting. (Please modify "xmeter_runtime_vars" UDV to fit your needs.)
135
+
136
+
2) pubsub_unidirection.jmx:
137
+
Demonstrate how sub sampler can get messages from corresponding pub sampler, with two JMeter user groups and delay between opertions.
138
+
139
+
3) pubsub_bidirection.jmx:
140
+
Demonstrate how a set of Devices and Mobiles exchange messages in both directions.
0 commit comments