Deployment notes and troubleshooting

Broker naming and preferences

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

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

The broker preferences are stored using the value of /config/messaging/broker/name as a key. Broker names should 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 will be approximately the same as the associated transaction log but the message store will grow as necessary to store the messages that are yet to be delivered. A broker which continues to receive messages that are not being consumed can conceivably run out of disk space and will 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 that could be taken include deploying message stores onto a separate partition of the filing system from the main operating system or to a filing system to which additional storage can be added.

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

The javax.jms.Connection class exposes a method setClientID(String clientID). When creating Connections, the IBM Reliable Transport Extension automatically generates unique client IDs comprising three numbers separated by hyphens. The first of these numbers is a timestamp and thus indicative of the Connection's age. There are three different types of Connection recorded in the log files.

• Those generated by the Connection API's messaging protocol are assigned no prefix.
• Those generated by the external client are prefixed 'E'.
• Those generated by a bridge between broker instances are prefixed 'B'.

Broker logs will be found to contain messages of the form,

    INFO [ FMBT1756 testBroker1 Client '1211276930793-33-434379236' - Connected. 
        Listener: MqttTlsListener9091:/127.0.0.1:9091-/127.0.0.1:2854, client address: /127.0.0.1:2854 ]
2008-05-20 10:49:25 zero.messaging.broker.control.ZeroLogDestination::logMessage Thread-11
    INFO [ FMBT1756 testBroker1 Client 'E1211277011629-1-18916478' - Connected. 
        Listener: MqttTlsListener9091:/127.0.0.1:9091-/127.0.0.1:2868, client address: /127.0.0.1:2868 ]
2008-05-20 11:21:01 zero.messaging.broker.control.ZeroLogDestination::logMessage Thread-11

External client application code can change a Connection's clientID once by calling Connection.setClientID(String clientID). Further calls to this method will result in an Exception of the form,

javax.jms.IllegalStateException: The client ID for this connection is read-only.

Both the external client and messaging protocol pool Connections by default. This must be borne in mind when attempting to correlate connectionIDs with message producers.

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 will be 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 will log a SEVERE message indicating that an FFDC file has been written to a 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.

FFDCs of this nature can cause the broker to shutdown and restart and the client connections will time out or be disconnected.