Best Practices

It is recommended that you use the following best practices when developing applications to publish or receive messages using Solace PubSub+.

General Best Practices

The following general best practices should be used for the Java, C, and .NET APIs.

Tuning Guidelines for Guaranteed Messaging

Reductions in the rate at which clients receive messages can occur when a high volume of Guaranteed messages (particularly when they are large messages) is received over many Flows. In this situation, the number of Flows used and the Guaranteed window size used for each Flow affects the buffer usage of the per‑client priority queues that the Solace message broker uses for Guaranteed messages. These queues, called the G-1 queues, hold Guaranteed messages for the clients that waiting for delivery out of the message broker or have been sent but are waiting for acknowledgment from the clients.

Each G-1 queue is allocated a maximum depth buffer. This maximum depth is measured in work units, whereby a work unit represents 2,048 bytes of a message. (By default, each G-1 queue is given a maximum depth of 20,000 work units.)

To address slow Guaranteed message delivery rates caused by high demands on the buffer allocated by G-1 queues, you should reduce the Guaranteed message window size used for each Flow and, when possible, reduce the number of Flows used. Refer to Number of Flows and Guaranteed Message Window Size.

If it is not possible to reduce the Guaranteed message window size or the number of flows, you can also effectively increase the G-1 queue size by adjusting the min-msg-burst size used by the message broker. Refer to Minimum Message Burst Size.

Reapply Subscriptions

The Solace messaging APIs have the ability to track and re-apply subscriptions on a reconnection to the message broker through the Reapply Subscriptions Session property. By default, this property is not enabled. However, if you allow the API to reconnect automatically after a fail over, it usually makes sense to enable this property, so that the Session will automatically re-apply the subscriptions.

Number of Flows and Guaranteed Message Window Size

The amount of buffers used by a client for receiving Guaranteed messages is primarily determined by the number of Flows used per Session * the Guaranteed Message window size of each Flow. To limit a client’s maximum buffer use, you can reduce the number of Flows used and/or reduce the Guaranteed Message window size of each Flow. (The Guaranteed Message window size for each Flow is set through the Flow properties; refer to Important Flow (Message Consumer) Properties.)

Consider, for example, a client using Flows with a window size of 255 to bind to 10 Queues, and the Guaranteed messages from those Queues have an average size of 20kB. In this scenario, the Flow configuration for the client is not appropriately sized, as the client’s maximum buffer usage (approximately 24,902 work units) exceeds that offered by the router (20,000 work units). However, if the Flows are reconfigured with a window size of 25, then the client’s maximum buffer usage will fall within an acceptable range (approximately 2,441 work units).

  • Work units are fixed size buffers on the message broker that are used to process messages according to set queue depths. A work unit represents 2,048 bytes of a message.
  • If you are using the Java API, you also need to tune the size of the Java consumer notification dispatcher queue so that it is large enough to buffer the maximum number of notifications that can be generated by all consumer flows (Guaranteed message flows as well as direct consumers) contained in all Sessions in a Context.


    GDFlows is all of the Guaranteed message consumer Flows in a Context.

    FCL is the default consumer Flow congestion limit.

    Nconsumers is the number of Direct message consumers in a Context.

Minimum Message Burst Size

If you cannot reduce the number of Flows or the Guaranteed Message window size, you can adjust the size of the G-1 queue. The simplest way to increase the queue is to adjust the min-msg-burst size. The min-msg-burst size specifies the number of messages that are always allowed entry into the queue. The min‑msg‑burst size is set on a per-client basis through client profiles.

Under normal operating conditions it is not necessary to change the default min‑msg-burst value for the G-1 queue. However, in situations where a client is consuming messages from multiple endpoints, it is important that the min‑msg‑burst size for the G-1 queue is at least equal to the sum of all of the Guaranteed message window sizes used for the Flows that the client consumes messages from. For example, if the client connects to 1,000 endpoints, and the Flows have a window size of 50, then the min-msg-burst size should be set to 50,000 or more.

Tuning the min-msg-burst size in this manner ensures that the NAB holds enough messages to fill the client’s combined Guaranteed message window size when it comes online. If there are not enough messages held, messages that are not delivered to the client can be discarded, then another delivery attempt is required. This process of discarding, then resending messages results in a slow recovery for a slow subscriber (that is, a client that does not consume messages at a quick rate).

For information on how to set the min-msg-burst size, refer to Configuring Egress Per-Client Priority Queues.

Replication Best Practices

This section describes considerations that should be made when your client applications are to be used with Solace PubSub+ message brokers using the Replication facility, which provides a data center redundancy and disaster recovery solution for Solace PubSub+.

Messaging API Versions

It is strongly recommended that Replication-aware applications use release 7.1.2 or later Solace enterprise messaging APIs. These versions support automatic handling of replication failovers. When a replication failover occurs, the API properly handles any in-progress messages or transactions.

Host Lists

Applications should be configured with a host list of two addresses, one for the Guaranteed Messaging-enabled virtual router at each site. The addresses can be either IP addresses or hostnames.

When the application attempts to connect to a standby message broker, the connection will be rejected by the message broker. After the specified number of retries per host, the API will attempt to connect to the other host in the host list. Normally, for an application to be used with Replication, if a connection fails for one host it would be good to immediately attempt to connect to the other host before retrying the same host. Therefore, setting a reconnect retries per host of 1 is recommended.

Note:  Host lists should not be used if you are using an active/active Replication deployment, where clients are consuming messages from endpoints on the Replication active Message VPN or on its mate Replication standby Message VPN. For such a deployment, each consuming client should only attempt to connect to the Replication active Message VPN on one host or the Replication standby Message VPN on its mate.

Automatic Reconnect

When using a Solace messaging API’s automatic reconnect feature, it should be noted that the duration of a Replication fail-over will be minutes or hours because operator intervention is required for the switch‑over. Therefore, it is recommended to set the number of reconnect retries to -1, which allows a client application to attempt to reconnect indefinitely.

Related Samples

For an example of how to handle Replication reconnects, see the Replication sample that is included with the Solace messaging API that you are using.

Queue Network Names

The queue network name interface has been deprecated in the APIs with the release of Replication. The reason is that queue network names change between different virtual routers, but Replication applications need to ensure queue naming is consistent within a paired Replication site.

For the C messaging API, it is recommended to provide the application queue name directly as the SOLCLIENT_ENDPOINT_PROP_NAME and the SOLCLIENT_FLOW_PROP_BIND_NAME, rather than obtaining the name from a call to solClient_createQueueNetworkName(), which is a deprecated function.

For the Java messaging API, it is recommended to call JCSMPFactory.createQueue(String name) rather than JCSMPFactory.createQueue(String name, String virtualRouterName). The latter is a deprecated method.