Messaging: JMS, Mail & TCP

JMeter includes the JMS API jar, but no JMS client implementation. The provider’s jars go in JMeter’s lib directory, not in lib/ext (which is for plugins), or in a directory listed in the user.classpath property; JMeter must be restarted after adding them. Setting the CLASSPATH environment variable has no effect, because JMeter is started with java -jar. For ActiveMQ the getting-started guide asks for the single activemq-all-X.X.X.jar.

The version of the client jar matters more than the guide suggests, because the JMS API changed package name:

The 5.6.3 column is from the 5.6.3 build files (geronimo-jms_1.1_spec); ActiveMQ Classic 6.x moved its client to the Jakarta Messaging API, so a 6.x client jar dropped into JMeter 5.6.3 does not provide the javax.jms classes the samplers call. The broker version is a separate question: a 5.19 client talks OpenWire to a 5.19 or 6.x broker alike. The 6.0 column is from the master branch, whose JMS module now depends on jakarta.jms-api 3.1.0 and imports jakarta.jms.*; at the time of writing this is not yet listed in changes.xml, so treat it as planned and re-check the 6.0 release notes before upgrading. A plan written for 5.6.3 keeps working on 6.0 as far as the .jmx file is concerned; it is the jars in lib that will need replacing.

Source: Getting Started: JMS client (User Manual), Getting Started: Libraries for ActiveMQ JMS (User Manual), Getting Started: JMeter’s Classpath (User Manual) and ActiveMQ Classic download

All three samplers look up a connection factory and destinations through a JNDI InitialContext. They can build it in two ways:

For ActiveMQ Classic, the component reference gives these values:

The default connection factory name in ActiveMQ’s JNDI context is ConnectionFactory. Fixed JNDI names are defined with queue.<jndiName>=<physicalName> and topic.<jndiName>=<physicalName> entries, which is what the point-to-point tutorial does (queue.Q.REQ=example.A, queue.Q.RPL=example.B). An embedded vm:// broker is handy for a quick experiment, but it runs inside the load generator and competes with it for CPU and heap; a load test should always use a separate broker.

The Bookshelf jndi.properties, for the Publisher and Subscriber when the checkbox is used:

For ActiveMQ Artemis the equivalent JNDI factory is org.apache.activemq.artemis.jndi.ActiveMQInitialContextFactory, and connection factories are declared as connectionFactory.<name>=tcp://host:port entries, with the same queue. and topic. prefixes for destinations; with JMeter 5.6.3 use Artemis’s javax.jms client, not its Jakarta client.

Source: JMS Publisher (Component Reference), Building a JMS Point-to-Point Test Plan (User Manual), ActiveMQ Classic JNDI Support and Artemis: Using JMS or Jakarta Messaging

The numeric values are the 5.6.3 source’s JMS_COMMUNICATION_STYLE enum; older plans contain a JMSSampler.isFireAndForget boolean from before Read, Browse and Clear existed (they arrived in JMeter 4.0).

Source: JMS Point-to-Point (Component Reference)

With a fixed reply queue, many threads wait on the same queue, so JMeter must know which reply belongs to which request. Two checkboxes under Use alternate fields for message correlation decide which header fields are compared:

In both real patterns the application is responsible for populating the correlation ID. A correlation ID can be set on the request by adding a row named JMSCorrelationID to the JMS Properties table (the name is matched case insensitively in the 5.6.3 source, which also treats a JMSType row as the JMSType header since JMeter 5.4).

With the Request Response style and a reply queue, the sampler sets the request’s JMSReplyTo to that queue; one receiver per reply queue hands each reply to the thread waiting for its ID. Replies that arrive after the Timeout are discarded and the sample fails with the response message No reply message received.

Source: JMS Point-to-Point (Component Reference)

The JMX property names are from the 5.6.3 source (JMSSampler.java); the field labels and descriptions are from the component reference.

There are no user and password fields. JMeter uses the JNDI properties java.naming.security.principal and java.naming.security.credentials, if present, when it creates the queue connection; setting the JMeter property JMSSampler.useSecurity.properties=false disables that.

Source: JMS Point-to-Point (Component Reference) and Properties Reference

The smallest runnable JMS test needs nothing but the broker: request and reply on the same queue, with both correlation checkboxes selected, so every request comes back to its own thread as its "reply". It measures the broker’s send-plus-receive cost, which is a useful baseline before a service is involved.

The numbers are illustrative and depend on the machine. With no think time, each of the 10 threads does about 1000 / 11 ms ≈ 90 round trips per second, which matches the ≈ 850/s total: in a closed model with no pauses, throughput is just threads divided by response time. Because messages are persistent by default, most of those 11 ms are the broker’s store writes; selecting Use non-persistent delivery mode? usually makes the same run noticeably faster, which is exactly why the delivery mode of the test must match production.

Source: JMS Point-to-Point (Component Reference) and Getting Started: CLI Mode (User Manual)

The real Bookshelf loan worker listens on bookshelf.loan.requests, creates the loan, and replies to the request’s JMSReplyTo queue with the request’s JMSMessageID as JMSCorrelationID: the JMS Message ID pattern. The test measures the round trip a borrower’s request takes through the broker and the worker.

The plan follows the point-to-point tutorial (JNDI names mapped through JNDI Properties), with the Bookshelf values:

Add a Constant Timer of 1000 ms under the sampler (think time) and a Response Assertion on "status":"ACTIVE".

Worked numbers. With 20 threads, a 1 s think time and a typical 50 ms round trip, each thread completes one loan every 1.05 s, so the plan offers 20 / 1.05 ≈ 19 loan requests per second; the worker must process a request in under 1000 / 19 ≈ 52 ms on average just to keep the request queue from growing. Watch the queue depth in the ActiveMQ web console (or with a Browse sample) during the run: a depth that keeps rising means the worker, not JMeter, is the bottleneck, and the round-trip times will climb with it.

A stub worker for trying the plan without the real service. When the loan worker is not available, a small Groovy responder can stand in for it. It is not an official JMeter pattern, only a test stub; run it as a separate plan in a separate JMeter process (one Thread Group of 1 to 2 threads, Loop Count Infinite, one JSR223 Sampler with language groovy), so its samples do not pollute the load test’s results:

The stub uses the plain javax.jms API of the ActiveMQ client that is already in lib; JSR223 caching and the vars and props bindings are explained on Scripting with JSR223 & Groovy.

Source: Building a JMS Point-to-Point Test Plan (User Manual), JMS Point-to-Point (Component Reference) and JSR223 Sampler (Component Reference)

Leaving JNDI name Receive queue empty switches Request Response to temporary queues: JMeter sets JMSReplyTo to a temporary queue and the sending thread blocks until the reply arrives. The component reference stresses that this is very different from a fixed reply queue. The service under test sees the same JMSReplyTo contract, so it needs no change, but the broker now creates and deletes temporary destinations, which is extra load that production may not have. Use the same reply mechanism as the real clients.

The three utility styles make queue housekeeping part of the plan rather than a manual step:

Source: JMS Point-to-Point (Component Reference)

The message sources behave as follows: From file reads the file once and reuses it for all samples (since JMeter 3.0 it is reloaded when the file name changes, so the name can contain a variable); Random File from folder picks a random file each sample, and the folder must contain .dat files for bytes messages or .txt / .obj files for text and object messages; Textarea takes the message from the text area. Since JMeter 3.2, variables are supported for every message type and source.

A map message is read as lines of text, each with three comma-separated fields: entry name, class name (String assumes java.lang) and a string value converted with that class’s valueOf(String):

An object message needs the jar of the object’s class and its dependencies in lib, and the object serialized as XML with XStream, either in a .txt / .obj file or in the text area; property replacement happens in the text area but not in a file.

Source: JMS Publisher (Component Reference)

Since JMeter 3.0 a Subscriber sample is an error when the number of messages received differs from Number of samples to aggregate; before 3.0, one message was enough for success. The Timeout therefore has to cover the time the whole batch needs to arrive at the expected rate.

Source: JMS Subscriber (Component Reference) and Changes history

When a loan is created, the Bookshelf platform publishes a LoanCreated event on the bookshelf.loan.events topic; the notification, analytics, recommendation, audit and search-index services each subscribe. The test checks that the broker sustains the publish rate and delivers every event to every subscriber, mirroring the topic tutorial: five subscribers and one publisher.

Worked numbers. The publisher waits 200 ms and then spends a few milliseconds publishing, so it sends a little under 1000 / 200 = 5 events per second. Each of the 5 subscribers receives all of them, so the broker makes about 5 × 5 = 25 deliveries per second. A subscriber sample needs 10 events, so it completes about every 10 / 5 = 2 s, and the 10 s timeout leaves five times that margin; if the subscriber samples start failing with fewer than 10 messages, events are being lost or delayed, not merely slow. Over a 120 s run, minus the 5 s publisher delay, expect about 115 × 5 ≈ 575 events published and about 57 successful samples per subscriber. The tutorial’s own arithmetic is simpler (6 threads × 1 message × 10 iterations = 60 messages), because it only loops a fixed number of times.

The eventType property lets a subscriber use a JMS Selector: eventType = 'LoanCreated' makes, for example, the search-index subscriber receive only the events it cares about. A durable subscription (a Durable Subscription ID plus a Client ID such as search-index-${__threadNum}) keeps events for a subscriber that is temporarily disconnected, which is how to test catch-up after a consumer restart.

Source: Building a JMS Topic Test Plan (User Manual), JMS Publisher (Component Reference) and JMS Subscriber (Component Reference)

The topic tutorial explains Number of samples to aggregate by performance: small messages arrive very quickly, and if the sampler did not aggregate them JMeter would not be able to keep up. Each sample costs a result object, listener work and a line in the JTL file; at thousands of messages per second, one sample per message turns the load generator into the bottleneck. Aggregating 10 or 100 messages per sample divides that overhead accordingly. The flip side is that one sample’s elapsed time covers the whole batch, so per-message latency is not visible; when it matters, put a timestamp in the message body and compute it on the consumer side, or use request/reply.

The tutorial also notes that the two subscriber client implementations exist because some providers show zombie threads with one of them: if that happens, try the other.

The JMX property names are from the 5.6.3 source (SmtpSampler.java and SecuritySettingsPanel.java).

A successful sample has response code 200 and the response message Message successfully sent!; failures get response code 500 with the exception text, and a wrong user name or password shows up as AuthenticationFailedException.

Source: SMTP Sampler (Component Reference)

Worked numbers. With 10 threads and a 2 s pause, each cycle is the 2 s pause plus a few milliseconds of SMTP session, so the plan sends just under 10 / 2 = 5 messages per second, about 300 per minute, each as its own TCP connection: 5 connects, EHLO exchanges and QUITs per second on top of the message transfer. Against a relay that is configured for 50 messages per second, a ramp from 5 to 50 messages per second (10 to 100 threads at the same pause) answers whether the relay keeps up with the peak loan rate.

Source: SMTP Sampler (Component Reference) and GreenMail documentation

A second Thread Group, Mailbox reader, with 1 thread, Infinite loops and the same Duration, reads the mailbox the senders fill:

Worked numbers. At about 5 messages per second and one read every 10 s, each read finds about 50 messages, fetches their headers and deletes them, so the mailbox stays small. The summariser counts each read as one sample (the 280 SMTP samples plus 6 reads ≈ 286), while the messages appear as sub-samples in the JTL file when sub-results are saved. Reading All with full bodies, without deletion, from a mailbox that only grows would make every read slower than the last and measure the mailbox size rather than the server. The numbers are illustrative.

Source: Mail Reader Sampler (Component Reference), SMIME Assertion (Component Reference) and Changes history

The class is chosen by the TCPClient classname field, failing that by the tcp.handler property; a short name is looked up in the package org.apache.jmeter.protocol.tcp.sampler. Users can provide their own class, which must extend org.apache.jmeter.protocol.tcp.sampler.TCPClient.

The most common TCP Sampler bug follows from that table: with TCPClientImpl, no EOL byte and a server that keeps the connection open, "end of the input stream" never comes, so every sample waits for the Response Timeout (or forever, if none is set). Define how a response ends: an EOL byte, an EOM byte, a length prefix, or a server that closes the connection. And if an EOL or EOM byte is used, the Response Timeout must be long enough, because the read is cut off when it expires.

When tcp.status.prefix is defined, the response is searched for the text between prefix and suffix, which becomes the response code, and the message comes from the properties file if given. With prefix [ and suffix ], the response [J28] XI123,23,GBP,CR has response code J28. Response codes from 400 to 499 and 500 to 599 count as failures; everything else is a success.

Source: TCP Sampler (Component Reference) and Properties Reference

The JMX property names are from the 5.6.3 source (TCPSampler.java).

Add → Config Element → TCP Sampler Config provides default data for the TCP Samplers in its scope, exactly like HTTP Request Defaults for HTTP: TCPClient classname, ServerName or IP, Port Number, Re-use connection, Close connection, SO_LINGER, End of line(EOL) byte value, Connect Timeout, Response Timeout, Set Nodelay and Text to send, with the same JMX property names (it is stored as a ConfigTestElement with guiclass="TCPConfigGui"). A TCP Sampler leaves a field empty to inherit the value from the config. An EOL byte set in TCP Sampler Config takes precedence over tcp.eolByte.

Source: TCP Sampler Config (Component Reference)

The legacy Bookshelf stock service answers one line per request: STOCK <bookId> followed by a newline. Locally, a socat echo server stands in for it (it returns each line unchanged, which is enough to exercise the sampler):

Without the EOL byte, each sample of this plan would wait the full 5 s Response Timeout and fail, because cat keeps the connection open. The sampler records connect time (since JMeter 3.0) and latency (since 3.3) as well as the elapsed time, so the JTL file separates connection set-up from the service’s answer.

Source: TCP Sampler (Component Reference) and __char (Functions)

Binary protocols often frame messages with a length prefix. LengthPrefixedBinaryTCPClientImpl adds the 2-byte prefix to the request and reads exactly as many bytes as the response’s prefix announces, so it works on a connection that stays open. Against the same echo server, the response is the request itself:

On the wire JMeter sends 0004 0102002A (the prefix 4 in two bytes, then the data) and expects the same framing back. If the real protocol uses a 4-byte prefix, set tcp.binarylength.prefix.length=4. With plain BinaryTCPClientImpl, the same request would need tcp.BinaryTCPClient.eomByte or a server that closes the connection.

Source: TCP Sampler (Component Reference)

The TCP Sampler is light on CPU; its cost is sockets. Worked numbers for the stock lookup with 50 threads, a 1 s think time and a 5 ms response:

Reuse connections when the real clients do, and close them per sample only when the real clients do too. SO_LINGER 0 makes the close abortive and avoids TIME_WAIT, as the component reference notes, at the price of a reset instead of an orderly close; use it only when the server tolerates that. Set NoDelay matters for small request/response messages: with Nagle’s algorithm on, a small write can be delayed waiting for an acknowledgement, which inflates response times for reasons that have nothing to do with the server.

Source: TCP Sampler (Component Reference)