Chapter 5   Starting and Configuring a Broker


After installing MQ, you use the imqbrokerd command to start a broker. The configuration of the broker is governed by a set of configuration files and by options passed with the imqbrokerd command, which override corresponding properties in the configuration files.

This chapter explains the syntax of the imqbrokerd command and how you use command line options and configuration files to configure the broker. In addition, it also describes how you do the following:

• edit a broker's instance configuration file

• work with broker clusters

• control logging for the broker

For a description of how to start and use the broker as a Windows service, see "Using a Broker as a Windows Service".

Configuration Files

---

Installed configuration files, which are used to configure the broker, are located in the following directory.

IMQ_HOME/lib/props/broker
(/usr/share/lib/imq/props/broker on Solaris)

This directory stores the following files:

• A default configuration file that is loaded on startup. This file is called default.properties and is not editable. You might need to read this file to determine default settings and to find the exact names of properties you want to change.

• An installation configuration file that contains any properties specified when MQ is installed. This file is called install.properties; it cannot be edited after installation.

In addition, the first time you run a broker, an instance configuration file is created that you can use to specify configuration properties for that instance of the broker. This file is maintained by the broker in response to administrative commands and can also be edited directly if you're careful. The instance configuration file is stored in the following location:

IMQ_VARHOME/instances/brokerName/props/config.properties
(/var/imq/instances/brokerName/props/config.properties on Solaris)

Where brokerName is the instance name of the broker (imqbrokerd by default). You can edit an instance configuration file to make configuration changes (see "Editing the Instance Configuration File").

If you connect brokers in a cluster (see "Multi-Broker Configurations (Clusters)") you may also need to use a cluster configuration file to specify cluster configuration information. For more information, see "Cluster Configuration Properties".

Merging Property Values

At startup, the system merges property values in the different configuration files. It uses values set in the installation and instance configuration files to override values specified in the default configuration file. You can override the resulting values by using imqbrokerd command options. This scheme is illustrated in Figure 5-1.

Figure 5-1    Broker Configuration Files

Property Naming Syntax

Any MQ property definition in a configuration file uses the following naming syntax:

propertyName=value[[,value1]...]

For example, the following entry defines the queue type for an auto-create queue:

imq.queue.default=single

The following entry defines the message expiration timeout value:

imq.message.expiration.timeout=90

Table 5-1 lists the broker configuration properties (and their default values) in alphabetical order.

Editing the Instance Configuration File

The first time a broker instance is run, a config.properties file is automatically created. You can edit this file to customize the behavior and resource use of the corresponding broker instance.

The broker reads the config.properties file only at startup. To make permanent changes to the config.properties file, you can either

• use administration tools. For information about properties you can set using imqcmd, see Table 6-5.

• edit the config.properties file while the broker instance is shut down; then restart the instance. (On Solaris and Linux platforms, only the user that first started the broker instance has permission to edit the config.properties file.)

Table 5-1 lists the broker instance configuration properties (and their default values) in alphabetical order. For more information about the meaning and use of each property, please consult the specified cross-referenced section.

Table 5-1    Broker Instance Configuration Properties 

Property Name	Type	Default Value	Reference
imq.accesscontrol.enabled	boolean	true	Table 2-6
imq.accesscontrol.file. filename	string	accesscontrol. properties	Table 2-6
imq.authentication.basic. user_repository	string	file	Table 2-6
imq.authentication. client.response.timeout	integer (seconds)	180	Table 2-6
imq.authentication.type	string	digest	Table 2-6
imq.autocreate.queue	boolean	true	Table 2-9
imq.autocreate.topic	boolean	true	Table 2-9
imq.cluster.url	string	null	Table 2-10
imq.keystore.property_name			Table 8-8
imq.log.console.output	string	ERROR|WARNING	Table 2-8
imq.log.console.stream	string	ERR	Table 2-8
imq.log.file.dirpath	string	IMQ_VARHOME/ instances/ brokerName/log	Table 2-8
imq.log.file.name	string	log.txt	Table 2-8
imq.log.file.output	string	ALL	Table 2-8
imq.log.file.rolloverbytes	integer (bytes)	0	Table 2-8
imq.log.file.rolloversecs	integer (seconds)	604800	Table 2-8
imq.log.level	string	INFO	Table 2-8
imq.log.syslog.facility	string	LOG_DAEMON	Table 2-8
imq.log.syslog.logpid	boolean	true	Table 2-8
imq.log.syslog.logconsole	boolean	false	Table 2-8
imq.log.syslog.identity	string	imqbrokerd_${imq. instancename}	Table 2-8
imq.log.syslog.output	string	ERROR	Table 2-8
imq.message.expiration. interval	integer (seconds)	60	Table 2-4
imq.message.max_size	byte string * 0 (no limit)	70m	Table 2-4
imq.metrics.enabled	boolean	true	Table 2-8
imq.metrics.interval	integer (seconds)	0	Table 2-8
imq.passfile.enabled	boolean	false	Table 2-6
imq.passfile.dirpath	string	IMQ_HOME/etc /etc/imq (on Solaris)	Table 2-6
imq.passfile.name	string	passfile	Table 2-6
imq.persist.file. destination.file.size	byte string *	1m	Table 2-5
imq.persist.file.message. cleanup	boolean	false	Table 2-5
imq.persist.file.message. fdpool.limit	integer	25 (Solaris & Linux) 1024 (Windows)	Table 2-5
imq.persist.file.message. filepool.cleanratio	integer	0	Table 2-5
imq.persist.file.message. filepool.limit	integer	10000	Table 2-5
imq.persist.file.sync. enabled	boolean	false	Table 2-5
imq.persist.jdbc.property_name			Table A-1
imq.persist.store	string	file	Table 2-5
imq.portmapper.port	integer	7676	Table 2-3
imq.queue.deliverypolicy	string	single	Table 2-9
imq.redelivered. optimization	boolean	true	Table 2-4
imq.resource_state. threshold	integer (percent)	0 (green) 60 (yellow) 75(orange) 90 (red)	Table 2-4
imq.service.activelist	list	jms,admin	Table 2-3
imq.service_name. accesscontrol.enabled	boolean	inherits value from system-wide property	Table 2-6
imq.service_name. accesscontrol.file.filename	string	inherits value from system-wide property	Table 2-6
imq.service_name. authentication.type	string	inherits value from system-wide property	Table 2-6
imq.service_name.max_threads	integer	1000 (jms) 500 (ssljms) 500 (httpjms) 500 (httpsjms) 50 (admin)	Table 2-3
imq.service_name.min_threads	integer	10 (jms) 10 (ssljms) 10 (httpjms) 10 (httpsjms) 4 (admin)	Table 2-3
imq.service_name.protocol type. hostname	string	null	Table 2-3
imq.service_name.protocol type. port	integer	0	Table 2-3
imq.service_name. threadpool_model	string	dedicated (jms) dedicated (ssljms) dedicated (httpjms) dedicated (httpsjms) dedicated (admin)	Table 2-3
imq.shared. connectionMonitor_limit	integer	512 (Solaris & Linux) 64 (Windows)	Table 2-3
imq.system.max_count	integer, 0 (no limit)	0	Table 2-4
imq.system.max_size	byte string*, 0 (no limit)	0	Table 2-4
imq.transaction.autorollback	boolean	false	Table 2-4
imq.user_repository.ldap. property_name			Table 8-5
* Values that are typed as a byte string, can be expressed in bytes, Kbytes, and Mbytes: For example: 1000 means 1000 bytes; 7500b means 7500 bytes; 77k means 77 kilobytes (77 x 1024 = 78848 bytes); 17m means 17 megabytes (17 x 1024 x 1024 = 17825792 bytes)

Starting a Broker

---

To start a broker and override one or more property values, use the imqbrokerd command, specifying a valid option. Command-line options override values in the broker configuration files, but only for the current broker session. Command line options are not written to the configuration property file.

The syntax of the imqbrokerd command is as follows (arguments are separated by a space):

imqbrokerd       [[ -Dproperty=value]...]

[ -backup filename]

[ -cluster "[broker] [[,broker]...]"

[ -dbuser username] [ -dbpassword password]

[ -javahome path | -jrehome path]

[ -ldappassword password]

[ -license name]

[ -loglevel level]

[ -metrics number]

[ -name brokername ] [ -port number]

[ -shared]

[ -password keypassword] [ -passfile filename]

[ -remove instance]

[ -reset data]

[ -restore filename]

[ -shared]

[ -silent] [ -tty]

[ -version] [ -vmargs arg [[arg]...]

For example, to start a broker that uses the default broker name and configuration, use the following command:

imqbrokerd

This starts a default instance of a broker (named imqbroker) on the local machine with the Port Mapper at port 7676.

Table 5-2 describes the options to the imqbrokerd command and describes the configuration properties, if any, affected by each option.

---

Note

On Solaris and Linux platforms, permissions on the directories containing configuration information and persistent data depend on the umask of the user that starts the broker instance the first time. Hence, for the broker instance to function properly, it must be started subsequently only by the original user.

---

Table 5-2    imqbrokerd Options 

Option	Properties Affected	Description
-backup filename	None affected.	Backs up a Master Broker's configuration change record to the specified file. Only applicable to broker clusters. See "Backing up the Master Broker's Configuration Change Record".
-cluster"[broker] [[,broker]...]" broker is either host[:port] [host]:port	Sets imq.cluster.brokerlist to the list of brokers to which to connect.	Connects to all the brokers on the specified hosts and ports. This list is merged with the list in the imq.cluster.brokerlist property. If you don't specify a value for host, localhost is used. If you don't specify a value for port, the value 7676 is used. See "Working With Broker Clusters" for more information on how to use this option to connect multiple brokers.
-dbpassword password	Sets imq.persist.jdbc. password to specified password	Specifies the password for a plugged-in JDBC-compliant database. See Appendix A, "Setting Up Plugged-in Persistence."
-dbuser userName	Sets imq.persist.jdbc.user to specified user name	Specifies the user name for a plugged-in JDBC-compliant database. See Appendix A, "Setting Up Plugged-in Persistence."
-Dproperty=value	Sets system properties. Overrides corresponding property value in instance configuration file.	Sets the specified property to the specified value. See Table 5-1 for broker configuration properties. Caution: Be careful to check the spelling and formatting of properties set with the D option. If you pass incorrect values, the system will not warn you, and MQ will not be able to set them.
-javahome path	None affected.	Specifies the path to an alternate Java 2- compatible JDK. The default is to use the bundled runtime.
-jrehome path	None affected.	Specifies the path to a Java 2 JRE.
-ldappassword password	Sets imq.user_repository. ldap.password to specified password	Specifies the password for accessing a LDAP user repository. See "Using an LDAP Server for a User Repository".
-license [name]	None affected.	Specifies the license to load, if different from the default for your MQ product edition. If you don't specify a license name, this lists all licenses installed on the system. Depending on the installed MQ edition, the values for name are pe (Platform Edition—basic features), try (Platform Edition—90-day trial enterprise features), and unl (Enterprise Edition). See "Product Editions".
-loglevel level	Sets imq.broker.log.level to the specified level.	Specifies the logging level as being one of NONE, ERROR, WARNING, INFO. The default value is INFO. For more information, see "Logger".
-metrics int	Sets imq.metrics.report. interval to the specified number of seconds.	Specifies that metrics be reported at an interval specified in seconds.
-name brokerName	Sets imq.instancename to the specified name.	Specifies the instance name of this broker and uses the corresponding instance configuration file. If you do not specify a broker name, the name of the file is set to imqbrokerd. Note: If you run more than one instance of a broker on the same host, each must have a unique name.
-passfile filename	Sets imq.passfile. enabled to true. Sets jmq. passfile.dirpath to the path that contains the file. Sets imq.passfile.name to the name of the file.	Specifies the name of the file from which to read the passwords for the SSL keystore, LDAP user repository, or JDBC-compliant database. For more information, see "Using a Passfile".
-password keypassword	Sets imq.keystore. password to the specified password.	Specifies the password for the SSL certificate keystore. For more information, see "Security Manager".
-port number	Sets imq.portmapper.port to the specified number.	Specifies the broker's Port Mapper port number. By default, this is set to 7676. To run two instances of a broker on the same server, each broker's Port Mapper must have a different port number.
-remove instance	None affected.	Causes the broker instance to be removed: deletes the instance configuration file, log files, persistent store, and other files and directories associated with the instance.
-reset store| messages| durables| props	None affected.	Resets the broker's persistent store (or a subset of the store) or resets the broker's properties, depending on the argument given. Resetting the broker's persistent store clears out all persistent data, including persistent messages, durable subscriptions, and transaction information. This allows you to start the broker with a clean slate. You can also clear only all persistent messages or only all durable subscriptions. (If you do not want the persistent store to be reset on subsequent starts, then re-start the broker without using the -reset option.) For more information, see "Persistence Manager". Resetting the broker's properties, replaces the existing instance configuration file (config.properties) with an empty file: all properties assume default values.
-restore filename	None affected.	Replaces the Master Broker's configuration change record with the specified file. See "Restoring the Master Broker's Configuration Change Record".
-shared	Sets imq.jms. threadpool_model to shared.	Specifies that the jms connection service be implemented using the shared threadpool model, in which threads are shared among connections to increase the number of connections supported by a broker. For more information, see "Connection Services".
-silent	Sets imq.log.console. output to NONE.	Turns off logging to the console.
-tty	Sets imq.log.console. output to ALL	Specifies that all messages be displayed to the console. By default only WARNING and ERROR level messages are displayed.
-version	None affected.	Displays the version number of the installed product.
-vmargs arg [[arg]...]	None affected	Specifies arguments to pass to the Java VM. Separate arguments with spaces. If you want to pass more than one argument or if an argument contains a space, use enclosing quotation marks. For example: imqbrokerd -tty -vmargs "-Xmx128m -Xincgc"

Working With Broker Clusters

---

This section describes the properties you use to configure broker clusters, describes a couple of methods of connecting brokers, and explains how you manage clusters. This feature is only available in the MQ Enterprise Edition (see "Product Editions").

For an introduction to clusters, see "Multi-Broker Configurations (Clusters)".

When working with clusters, make sure that you synchronize clocks among the hosts of all brokers in a cluster.

Cluster Configuration Properties

When you connect brokers into a cluster, all the connected brokers must specify the same values for cluster configuration properties. These properties describe the participation of the brokers in a cluster. Table 5-3 summarizes the cluster-related configuration properties.

Table 5-3    Cluster Configuration Properties  

Property	Description
imq.cluster.brokerlist	Specifies all brokers in a cluster in a comma-separated list; each item specifies the host and port of a broker. For example: host1:3000, host2:8000, ctrhost
imq.cluster.masterbroker	Specifies the host and port of the Master Broker. Set this value for production environments. For example, ctrhost:7676
imq.cluster.url	Specifies the location of the cluster configuration file. For example: http://webserver/imq/cluster.properties file:/net/mfsserver/imq/cluster.properies
imq.cluster.port	For each broker within a cluster, can be used to specify the port number for the cluster connection service. The cluster connection service is used for internal communication between brokers in a cluster. Default: 0 (port is dynamically allocated)
imq.cluster.hostname	For each broker within a cluster, can be used to specify the host (hostname or IP address) to which the cluster connection service binds if there is more than one host available (for example, if there is more than one network interface card in a computer). The cluster connection service is used for internal communication between brokers in a cluster. Default: null (all available hosts)

You can use one of two methods to set cluster properties:

• You set the cluster-related configuration properties in each broker's instance configuration file (or in the command line that starts each broker). For example, to connect broker A (on host1, port 7676), broker B (on host2, port 5000) and broker C (on ctrlhost, port 7676), the instance configuration file for brokers A, B, and C would need to set the following property.

  imq.cluster.brokerlist=host1, host2:5000, ctrlhost

  If you decide to change a cluster configuration, this method requires you to update cluster-related properties in all the brokers

• You set cluster configuration properties in one central cluster configuration file. These properties might include the list of brokers to be connected (imq.cluster.brokerlist) and optionally, the address of the Master Broker (imq.cluster.masterbroker).

  If you use this method, you must also set the imq.cluster.url property (for every broker in the cluster) to point to the location of the cluster configuration file. From the point of view of easy maintenance, this is the recommended method of cluster configuration.

The following code sample shows the contents of a cluster configuration file. Both host1 and ctrlhost are running on the default port. These properties specify that host1 and ctrlhost are connected in a cluster and that ctrlhost is the Master Broker.

imq.cluster.brokerlist=host1,host2:5000,ctrlhost imq.cluster.masterbroker=ctrlhost

The instance configuration file for each broker connected in this cluster, must then contain the url of the cluster configuration file; for example:

imq.cluster.url=file:/home/cluster.properties

Connecting Brokers

This section describes two methods of connecting brokers into a clusters. No matter which method you use, each broker that you start attempts to connect to the other brokers every five seconds; that attempt will succeed once the other brokers in the cluster are started up.

If you connect brokers into a cluster, it is not necessary to start the Master Broker first. If a broker in the cluster starts before the Master Broker, it will remain in a suspended state, rejecting client connections. When the Master Broker starts, the suspended broker will automatically become fully functional.

Method 1: No Cluster Configuration File

To connect brokers into a cluster

1. Use the -cluster option to the imqbrokerd command that starts a broker, and specify the complete list of brokers (to connect to) as an argument to the -cluster option.

2. Do this for each broker you want to connect to the cluster when you start that broker.

   For example, the following command starts a new broker and connects it to the broker running on the default port on host1, the broker running on port 7677 on host2 and the broker running on port 7678 on localhost.

   imqbrokerd -cluster host1,host2:7677,:7678

Method 2: Using a Cluster Configuration File

It is also possible to create a cluster configuration file that specifies the list of brokers to be connected (and optionally, the address of the Master Broker). This method of defining clusters is better suited for production systems. Remember, that each broker in the cluster must set the value of the imq.cluster.url property to point to the cluster configuration file.

Adding Brokers to Clusters

Once you have set up a broker cluster, you might need to add a new broker or restart a broker that is already part of the cluster.

To add a new broker to an existing cluster, you can do one of the following:

If you are not using a cluster configuration file, when you start the new broker, specify the imq.cluster.brokerlist and (if necessary) the imq.cluster.masterbroker properties on the command line using the -D option.

To add a broker to a cluster if you are using a cluster configuration file

1. Add the new broker to the imq.cluster.brokerlist property in the cluster configuration file.

2. Issue the following command to any broker in the cluster.

   imqcmd reload cls

   This forces all the brokers to reload the imq.cluster.brokerlist property and to make sure that all persistent information for brokers in the cluster is up to date.

Restarting a Broker in a Cluster

To restart a broker that is already a member of a cluster, you can do one of the following:

• If the cluster is defined using a cluster configuration file, use the -D option to specify the imq.cluster.url property on the command line used to start the broker.

• If the cluster is not defined using a cluster configuration file, when you start the new broker, specify the imq.cluster.brokerlist (and if necessary the imq.cluster.masterbroker) properties on the command line using the -D option. If the cluster does not include a Master Broker, you can simply use the -cluster option to specify the list of brokers in the cluster when you start the new broker.

Removing a Broker from a Cluster

Take note of the following when removing a broker from a cluster:

• If the brokers A, B, and C were all started using the following command line, then just restarting A will not remove it from the cluster.

  imqbrokerd -cluster A,B,C

  Instead, you need to restart all the other brokers with the following command line:

  imqbrokerd -cluster B,C

  Then, you need to start broker A without specifying the -cluster option.

• If the list of brokers was specified using a cluster configuration file, then you will need to do the following:
  • Remove mention of the broker from the configuration file.

  • Change or remove the imq.cluster.url property for the broker that is being removed so that it no longer uses the common properties.

  • Use the imqcmd reload cls command to force all the brokers to reload their cluster configuration and thereby reconfigure the cluster.

Backing up the Master Broker's Configuration Change Record

Each cluster can have one Master Broker that keeps track of any changes in the persistent state of the cluster: this includes durable subscriptions and physical destinations created by the administrator. All brokers consult the Master Broker during startup in order to synchronize information about these persistent objects. Consequently, the failure of the Master Broker can cripple the entire cluster. For this reason, it is important to backup the Master Broker's change record periodically by using the -backup option of the imqbrokerd command. For example,

imqbrokerd -backup mybackuplog

It is important you do this in a timely manner. Restoring a very old backup can result in loss of information: any persistent objects created since the backup was last done will be lost.

Restoring the Master Broker's Configuration Change Record

To restore the Master Broker in case of failure

1. Shut down all the brokers in the cluster.

2. Restore the Master Broker's configuration change record using the following command:

   imqbrokerd -restore mybackuplog

3. If you assign a new name or port number to the Master Broker, you must update the cluster configuration file to specify that the Master Broker is part of the cluster and to specify its new name (using the property imq.cluster.masterbroker).

4. Restart all the brokers.

The restoration of the broker will inevitably result in some stale data being reloaded into the broker's configuration change record; however, doing frequent periodic backups, as described in the previous section, should minimize this problem.

Because the Master Broker keeps track of the entire history of changes to persistent objects, its database can grow significantly over a period of time. The backup and restore operations have the positive effect of compressing and optimizing this database.

Logging

---

This section describes the default logging configuration for the broker and explains how you can change that configuration in order to redirect log information to alternate output channels, to change rollover criteria, and to report broker metrics. For an introduction to logging, see "Logger".

Default Logging Configuration

When you start the broker, it is automatically configured to save log output to a set of rolling log files located at

IMQ_VARHOME/instances/BrokerName/log/

The log files are simple text files. They are named as follows, from earliest to latest:

log.txt
log_1.txt
log_2.txt
...
log_9.txt

By default, log files are rolled over once a week; the system maintains nine backup files.

• To change the directory in which the log files are kept, set the property imq.log.file.dirpath to the desired path.

• To change the root name of the log files from log to something else, set the imq.log.file.filename property.

The broker supports three log categories: ERROR, WARNING, INFO (see Table 2-7). Setting a logging level gathers messages for all levels up to and including that level. The default log level is INFO. This means that ERROR, WARNING, and INFO messages are logged.

Log Message Format

Logged messages consist of a timestamp, message code, and the message itself. The volume of information varies with the log level you have set. The following is an example of an INFO message.

[13/Sep/2000:16:13:36 PDT] B1004 Starting the broker service using tcp [ 25374,100] with min threads 50 and max threads of 500

Changing the Logger Configuration

All Logger properties are described in Table 2-8.

To change the Logger configuration for a broker

1. Set the log level.

2. Set the output channel (file, console, or both) for one or more logging categories.

3. If you log output to a file, configure the rollover criteria for the file.

You complete these steps by setting Logger properties. You can do this in one of two ways:

• Change or add Logger properties in the config.properties file for a broker before you start the broker.

• Specify Logger command line options in the imqbrokerd command that starts the broker. You can also use the broker option -D to change Logger properties (or any broker property).

Options passed on the command line override properties specified in the broker instance configuration files. Table 5-4 lists the imqbrokerd options that affect logging.

Table 5-4    imqbrokerd Logger Options and Corresponding Properties 

imqbrokerd Options	Description
-metrics number	Specifies the interval (in seconds) at which metrics information is gathered.
-loglevel level	Sets the log level to one of ERROR, WARNING, INFO.
-silent	Turns off logging to the console
-tty	Sends all messages to the console. By default only WARNING and ERROR level messages are displayed.

The following sections describe how you can change the default configuration in order to do the following:

• change the output channel (the destination of log messages)

• change rollover criteria

• log broker metrics information

Changing the Output Channel

By default, error and warning messages are displayed on the terminal as well as being logged to a log file. (On Solaris error messages are also written to the system's syslog daemon.)

You can change the output channel for log messages in the following ways:

• To have all log categories (for a given level) output displayed on the screen, use the -tty option to the imqbrokerd command.

• To prevent log output from being displayed on the screen, use the -silent option to the imqbrokerd command.

• Use the imq.log.file.output property to specify which categories of logging information should be written to the log file. For example,

  imq.log.file.output=ERROR

• Use the imq.log.console.output property to specify which categories of logging information should be written to the console. For example,

  imq.log.console.output=INFO

• On Solaris, use the imq.log.syslog.output property to specify which categories of logging information should be written to Solaris syslog. For example,

  imq.log.syslog.output=NONE

  
  

  ---

  Note

  Before changing the destination of log messages, you must make sure that logging is set at the level that corresponds to the log category you are mapping to the output channel. For example, if you set the log level to ERROR and then set the imq.log.console.output property to WARNING, no messages will be logged because you have not enabled the logging of those level messages.

  ---

  
  

Changing Rollover Criteria

There are two criteria for rolling over log files: time and size. The default is to use a time criteria and roll over files every seven days.

• To change the time interval, you need to change the property imq.log.file.rolloversecs. For example, the following property definition changes the time interval to ten days:

  imq.log.file.rolloversecs=864000

• To change the rollover criteria to depend on file size, you need to set the imq.log.file.rolloverbytes property. For example, the following definition directs the broker to rollover files after they reach a limit of 500,000 bytes

  imq.log.file.rolloverbytes=500000

If you set both the time-related and the size-related rollover properties, the first limit reached will trigger the rollover. As noted before, the broker maintains up to nine rollover files.

Logging Broker Performance Metrics

The broker's default configuration, includes the following settings:

• imq.metrics.enabled=true

• imq.metrics.interval=0

• imq.log.level=INFO

As a result of these settings, the broker gathers performance metrics for the broker as well as for active connection services, but it does not generate metrics reports.

You can have the broker generate metrics reports in one of two ways:

• Use the -metrics option to the imqbrokerd command and specify the interval (in seconds) at which the broker generates reports.

• Set the imq.metrics.interval property to the interval (in seconds) at which you want the broker to generate reports.

Because metrics reports are included in the INFO category, metric reports, by default, are written to the log file output channel.

The following shows sample metrics information:

[31/Jan/2001:15:00:50 PST]

Connections: 0 JVM Heap: 6291456 bytes (5186320 free)

In: 0 mesgs (0bytes) 0 pkts (0 bytes)

Out: 0 mesgs (0bytes) 0 pkts (0 bytes)

Rate In: 0 msgs/sec (0 bytes/sec) 0 pkts/sec (0 bytes/sec)

Rate Out: 0 msgs/sec (0 bytes/sec) 0 pkts/sec (0 bytes/sec)

Table 5-5 describes the meaning of the metrics generated for each connection service.

Table 5-5    Metrics Gathered for Connection Services 

Metrics	Description
Pkts in (total)	Total number of packets read by the broker since the last reset. This includes MQ protocol packets, not just JMS messages.
Pkts out (total)	Total number of packets written by the broker since the last reset.
JMS Messages in (total)	Total number of JMS messages read by the broker since last reset.
JMS Messages out (total)	Total number of JMS messages written by the Broker since last reset.
Message Bytes in (total)	Total number of message bytes read by the Broker since last reset.
Message Bytes out (total)	Total number of message bytes written.
Current # connections	Current number of open connections.

Table 5-6 describes the metrics gathered and reported for each broker.

Table 5-6    Metrics Gathered for Each Broker 

Metrics	Description
VM heap size (bytes)	Maximum size of the Java VM heap.
VM heap free space (bytes)	Amount of free space left in the Java VM heap.

---

Note	This information is also available via the imqcmd metrics command.

---