Share this page

# 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).

In this topic:

## 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:

Item | Description
--- | ---
Message sent to queue | The producer sends a message to the queue using 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 using 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 using a DeleteMessage call.

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

## 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 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.

## 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
--- | --- | ---
Throughput | 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.
Ordering | No guaranteed ordering of messages. | Guaranteed ordering within the same group (but not within the whole queue).
Delivery | 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).

## 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.
MessageGroupId (FIFO messages only) | Defines the group to which a message belongs.
DeduplicationScope (FIFO queues only) | Whether the scope for deduplication is per message group (this is the faster method), or per queue.
FifoThroughputLimit (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.

## 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 Java environment.

- 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 its description 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: A Cloud for AWS script runs 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.

## 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 | Details
--- | --- | ---
init | 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);`
action | 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.
end | 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: `LrSqsClient.closeClient();`

Example script:

Copy code

    import lrapi.lr;
    import ot.protocols.lraws.*;
    import ot.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();
            lr.log_message(m.body());
            LrSqsClient.deleteMessage(m);
            return 0;
        }//end of action

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

## See also

- Cloud for AWS monitoring
- Cloud for AWS functions
- Create and open Vuser scripts

https://admhelp.microfocus.com VuGen,Professional Performance Engineering,Performance Engineering for Developers 8942
Tips to improve your search results... OpenText™ Virtual User Generator Help Center OpenText™ VuGen Help 26.1-26.3 All View Local Help Center View Online Help Center Version: