Deployment notes and troubleshooting

Broker naming and preferences

When a messaging broker is created, it stores information regarding its configuration using the Java™ preferences store. These preferences are stored using a platform specific location outside the scope of the IBM WebSphere sMash application.

After a messaging broker has been created, it cannot be moved to another machine.

The broker preferences are stored in the preferences for the current user using a key that includes the broker name, as defined by /config/messaging/broker/name. Broker names must be unique on the local machine to ensure each maintains a separate identity.

Managing the message store

When it is first started, a messaging broker creates a message store file in which messages are kept until they are delivered. It is important to ensure that the message store is located on a suitable filing system to preserve the integrity of the information it contains. For example:

• The filing system must not use write caching, encryption or compression.
• The filing system should use redundancy or mirroring to protect data in the event of a hardware failure.
• The filing system should be large enough to contain the message store and transaction log.

The initial size of the message store file is approximately the same as the associated transaction log but the message store grows as necessary to store the messages that are yet to be delivered. A broker that continues to receive messages that are not being consumed can conceivably run out of disk space and then be unable to provide a messaging service to client applications. A messaging deployment should be designed to discourage large message buildups and report them promptly when they occur. Other precautionary measures include deploying message stores on to separate filing system partitions from the operating system or to filing systems that can be expanded later.

See Configuring a messaging broker for more information about configuring the message store location.

Messaging trace and first failure data capture location

If a problem is detected, the messaging broker places any first failure data capture (FFDC) and trace files in a diagnostics directory inside the message store directory.

The location of the message store directory can be specified using /config/messaging/broker/messageStore but defaults to messageStore inside the application root directory. For example, the diagnostics for broker1 might be found in messageStore\broker1\diagnostics.

When reporting a problem involving the messaging broker, the contents of the diagnostics directory should be collected, in addition to the contents of the application logs directory.

Client IDs and connection pooling

When creating connections, the IBM Reliable Transport Extension automatically generates unique client IDs comprising three segments separated by hyphens. The first segment contains a timestamp and so is indicative of the age of the client connection. The first segment can also have a prefix letter that indicates the origin of the connection:

• Client connections established using the APIs provided for use within a WebSphere sMash application have no prefix letter.
• Client connections established using the external client API and using the default client ID have the prefix letter E.
• Store-and-forward connections from remote messaging brokers have the prefix letter B.

Store-and-forward pipe problems

When a store-and-forward pipe is established it behaves in a similar manner to a client application connected to a remote broker. As a result, a store-and-forward pipe can experience similar exceptions to a client connection. For example, if a store-and-forward pipe does not receive a response from the remote broker within a specified amount of time, a MqttNegativeAckException is logged with a reason code of 5.

Timeouts can occur under situations of heavy load or when working with very large messages. The timeout for an individual store-and-forward bridge connection can be set using the deliveryTimeout broker connection property.

See the troubleshooting guide for zero.messaging.connection for more information on diagnosing exceptions logged by the store-and-forward pipe.

Exceeding the transaction log size

If a broker receives a message which is larger than the available space in the transaction log, it logs a SEVERE message indicating that an FFDC file has been written to the diagnostics directory. A full transaction log can be diagnosed from the exception recorded in the FFDC file, for example:

CWSOM1027E: Log file was too full to accommodate 2002728(long) bytes, 
    checkedBytesInLogBuffer=190(long) bytes, flushSetReserved=8205(long) bytes, 
    flushSetAllocated=447245(long) bytes.
com.ibm.ws.objectManager.LogFileFullException: CWSOM1027E: Log file was too full 
    to accommodate 2002728(long) bytes, checkedBytesInLogBuffer=190(long) bytes, 
    flushSetReserved=8205(long) bytes, flushSetAllocated=447245(long) bytes.

Exceptions of this nature can cause the broker to shutdown and restart, which can result in other client connections timing out or disconnecting.