Sun ONE logo     Previous      Contents      Index      Next     
Sun ONE Message Queue, Version 3.0.1 Administrator's Guide



Chapter 5   Starting and Configuring a Broker

After installing Sun™ ONE Message Queue (MQ), you use the imqbrokerd command to start a broker. The configuration of the broker instance 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 instance. In addition, it also describes how you do the following:

  • edit a broker 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 instance 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 name of the broker instance (imqbroker by default). You can edit an instance configuration file to make configuration changes (see "Editing the Instance Configuration File").

If you connect broker instances in a cluster (see "Multi-Broker Clusters (Enterprise Edition)") 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
Diagram showing command line options override config.properties options, which override install.properties options, which override default options.

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 instance configuration file to customize the behavior and resource use of the corresponding broker instance.

The broker instance 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

(/var/imq/...on Solaris)

 

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.
brokerName}
 

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 1
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 1

 		 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 string1,
0 (no limit)

 		 0
 

Table 2-4

 
imq.transaction.autorollback
 

boolean

 		 false
 

Table 2-4

 
imq.user_repository.ldap.
property_name
 

 
 

Table 8-5

 
1 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 instance use the imqbrokerd command.


Note

You cannot start a broker instance using the Administration Console (imqadmin) or the Command Utility (imqcmd). The broker instance must already be running to use these MQ administration tools.

To override one or more property values, specify a valid imqbrokerd command-line 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 instance configuration file.

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

imqbrokerd       [[ -Dproperty=value]...]
    [ -backup fileName]
      [ -cluster "[broker] [[,broker]...]"
      [ -dbuser userName] [ -dbpassword password]
      [ -force]
      [ -h]
      [ -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.


Note

On Solaris, you can configure the broker to automatically restart after an abnormally exit, by setting the RESTART property in the /etc/imq/imqborkerd.conf configuration file to YES.



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 describes the options to the imqbrokerd command and describes the configuration properties, if any, affected by each option.

Table 5-2    imqbrokerd Options 

Option

Properties Affected

Description
-backup fileName
 

None affected.

 

Applies only to broker clusters. Backs up a Master Broker's configuration change record to the specified file. 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.

 

Applies only to broker clusters. 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 Clusters (Enterprise Edition)" 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 data store. 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.

 
-force
 

None affected.

 

Performs action without user confirmation. This option applies only to the -remove instance option, which normally requires confirmation.

 
-h
 

None affected.

 

Displays help. Nothing else on the command line is executed.

 
-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, or 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 imqbroker.
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. JMS clients connect to the broker instance using this 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. Requires user confirmation unless -force option is also specified.

 
-reset store| messages|
durables|
props
 

None affected.

 

Resets the data store (or a subset of the data store) or the configuration properties of a broker instance, depending on the argument given.

Resetting the data store clears out all persistent data, including persistent messages, durable subscriptions, and transaction information. This allows you to start the broker instance 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 instance 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.

 

Applies only to broker clusters. Replaces the Master Broker's configuration change record with the specified backup file. This file must have been previously created using the -backup option. 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 instance. 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 Clusters (Enterprise Edition)

This section describes the properties you use to configure multi-broker clusters, describes a couple of methods of connecting brokers, and explains how you manage clusters. For an introduction to clusters, see "Multi-Broker Clusters (Enterprise Edition)".

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.

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

    3. 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:

    3. 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/
(/var/imq/instances/brokerName/log/ on Solaris)

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.


Previous      Contents      Index      Next     
Copyright 2002 Sun Microsystems, Inc. All rights reserved.


Part Number 817-0354-10

Last Updated September 30, 2002