Cloud for AWS protocol

VuGen's Cloud for AWS protocol is used to create Vuser scripts that monitor the usage of Amazon Web Services Simple Queue Service (SQS).

About SQS

Amazon SQS is an AWS service that enables application components to communicate in the cloud, using a fully-managed message queueing service. The distributed messaging system allows the decoupling of producers and consumers.

There can be multiple end-to-end producers and consumers, and messages can be redundantly replicated on multiple servers. All message sending and receiving is highly configurable.

The basic flow for an SQS message is as follows:

Message sent to queue The producer sends a message to the queue via a SendMessage call.
Message stored The message is stored in the queue, up to MaximumReceiveCount or MessageRetentionPeriod.
Message received from queue The consumer receives the message from the queue via a ReceiveMessage call.
Message in flight The message is "in flight" and is processed within the VisibilityTimeout.
Message deleted from queue The message is deleted from the queue via a DeleteMessage call.

For more information on working with SQS, see the SQS documentation on the Amazon website.

Back to top

Cloud for AWS protocol for SQS

VuGen's Cloud for AWS protocol enables you to write scripts to monitor and load test an SQS-based system. When the Cloud for AWS script is run in LoadRunner Controller, it can collect specific metrics regarding the exchange of messages, both sent and received.

The Cloud for AWS protocol supports scripting in Java, using standard Java conventions. All standard Java methods are available, plus a set of SQS-specific APIs.

VuGen uses its own classes to represent the SQS classes. The main class that interacts with the queue is LrSqsClient. The LrSqsClient acts as producer and consumer, and also has some utility functions.

There are multiple auxiliary classes in addition to the SQS client, and SQS specific objects. For details on the SQS classes and functions, see Cloud for AWS functions in the Function Reference (select the relevant version).

Back to top

SQS queue types

The Cloud for AWS protocol supports both types of SQS queues: standard (default) and FIFO (first-in, first-out). These queues have the following attributes:

  Standard queues FIFO queues

Unlimited number of API calls per second.

300 API calls per second, up to 10 messages per call—this means support for up to 3000 messages per second.

Can also be switched to High-Throughput mode (up to 30,000 messages per second).

Groups Message groups are not supported.

Support for multiple groups. Each message must have a group ID.


No guaranteed ordering of messages.

Guaranteed ordering within the same group (but not within the whole queue).


A message is delivered at least once, and can be delivered multiple times (so the consumer must be idempotent).

Messages are delivered exactly once, using deduplication IDs (manually specified, or using MD5 hashing of message content).

Back to top

Key queue identifiers

The following describes some of the key identifiers used by VuGen with the Cloud for AWS protocol SQS APIs.

Identifier Description
Queue URL

The URL used within the SDK to identify the queue. To obtain the URL, open your Amazon console, select the queue, and copy the URL field.

This information is input to the SQS client, so that the client is initialized with both the region, which determines what queues are available, and then the exact queue URL.

Visibility timeout

The period of time that the message is hidden from other consumers.

For details, see Visibility timeout.

Message retention

The time a message remains in the queue if not processed. The possible range is 1 minute to 14 days.

Default: 4 days

Delivery delay

The time between the send request, and the message being actually added to the queue (configurable for queues and individual messages).

Receive message wait time

The length of time, in seconds, a ReceiveMessage call waits for the message. If there is no message, it returns after the wait time with no messages.

Possible range is 0 to 20 seconds.

Default: 0

ReceiveCount and maximum receives

Each time a message is received without being deleted, its ReceiveCount increases. When the ReceiveCount for a message reaches the maximum receives value that was set for the queue, the message is automatically sent to the dead-letter queue.

This provides a way to debug your messages—you can pick up the non-processed messages from the dead-letter queue and check what went wrong.


(FIFO messages only)

Defines the group to which a message belongs.


(FIFO queues only)

Whether the scope for deduplication is per message group (this is the faster method), or per queue.


(FIFO queues only)

Whether the throughput limit for messages in the queue is set per queue or per message group (MessageGroupId).

For high throughput, set to MessageGroupId.

Visibility timeout

When a consumer polls SQS for new messages (ReceiveMessage request), a message is selected from the queue and returned to the consumer. However, the message is not automatically deleted from the queue. While the message is being processed by the consumer, to prevent other consumers from processing the message again, SQS sets a visibility timeout.

During the visibility timeout, the message is exclusively visible to the consumer. The consumer must call DeleteMessage within the visibility timeout period, to signal it has finished processing. The message is then removed from the queue and no other consumer will see it. If the visibility timeout expires before the consumer deletes the message, the message becomes visible to other consumers for receiving.

The default visibility timeout is 30 seconds. You can modify this for a message if, for example, you think it needs more processing time.

Note: The standard queue may have duplicates of the message, so even after the original message is processed and deleted, consumers might receive one of the duplicates.

While the visibility timeout is still in effect, the handling of ReceiveMessage requests from other consumers is as follows:

  • Standard queue: Consumers receive another available message (no guarantee of ordering).

  • FIFO queue: Consumers receive a message from another message group. If the only messages are within the same message group, they are blocked to guarantee ordering.

    Note: SQS does not enable you to select the message group from which to receive the message. To receive from a specific group, you have to filter manually.

Back to top

Create and edit scripts

You can create Cloud for AWS SQS scripts using the VuGen editor and script designer.

Before creating a script, do the following:

  • Set up your Java environment. For details, see Set up the environment for Java protocols.

  • Initialize the SQS client and close the client, using VuGen's Cloud for AWS APIs.

  • When the Region option Use Unicode UTF-8 for worldwide language support is enabled in Windows, the JDK version used for replaying, recording, or generating a Cloud for AWS script must be compatible with the UTF-8 option.

To generate the script:

  1. In VuGen, open a Cloud for AWS script.
  2. In the toolbar, click Design Script (Ctrl+R) to open the Script Designer wizard.
  3. In the Initialize section, select a region, provide a URL, and indicate whether the queue uses FIFO mode. Click Save. The wizard adds the Initialize step to the list of Action Items in the right pane.
  4. Select actions from the Menu and fill in the relevant details. Hover over a field to see a description for it displayed at the bottom of the pane.

    In the Attributes sections, you can click + to add new attributes as relevant.

  5. Click Save to add the code to the script. The wizard adds the steps to the Action Items list.

  6. Add transactions and think time using the built-in actions pane.
  7. Check the order of the actions in the Action Items list. Drag the actions to change their location in the list. Double-click on an action to edit its contents.

  8. Click Generate. VuGen shows the script in the Editor window.
  9. Optionally copy additional custom Java code snippets into the script, into the relevant methods. Add all initializations in the init method and closures in the end method. For details, see Script classes and methods.

    Note: Cloud for AWS scripts run as a scalable multi-threaded application. Make sure that any code you include is thread-safe. For details, see Java protocol programming tips.

  10. Enhance your script with rendezvous points, output messages, and other elements. For more information, see Enhance a Java script.

Back to top

Script classes and methods

When working with a Cloud for AWS script, you place all your code in the Actions class that is displayed when you open the script in VuGen. The Actions class contains three methods: init, action, and end.

The following table shows what to include in each method and when each method is executed:

Script method
Method is executed
When the Vuser is initialized

This method emulates a login to a server and is executed only once. Place all login procedures and one-time configuration settings here, including initializing the SQS client.

Example: Inserting the following lines in the init method initializes the SQS client, using the region of the AWS cluster and the queue URL:

LrSqsClient.initClient(region, standardQueueUrl);

When the Vuser is in Running status
This method emulates client activity, and is executed according to the number of iterations you set in the runtime settings. Place all Vuser actions here.
When the Vuser finishes or is stopped

This method emulates a log off procedure and is executed only once. Place all procedures you want the Vuser to execute at the end of the script here, including closing the SQS client, and deallocating any resources used during the script.

Example: Inserting the following lines into the end method closes the SQS client:


Example script:

Copy code
import mf.protocols.lraws.*;
import mf.protocols.lraws.lrsqs.*;

public class Actions
    public int init() throws Throwable {
        LrSqsClient.initClient(LrAwsRegion.EU_CENTRAL_1, "your_queue_url_here");
        return 0;
    }//end of init

    public int action() throws Throwable {
        LrSqsClient.sendMessage("Hello, world!");
        LrSqsMessage m = LrSqsClient.receiveMessage();
        return 0;
    }//end of action

    public int end() throws Throwable {
        return 0;
    }//end of end

Back to top

See also: