mqsireadlog command

Supported platforms

Purpose

Use the mqsireadlog command to retrieve the trace log for the specified component. This command is valid for:
User trace
Specify the -u option.
Service trace
Specify the -t option. You are recommended to use this option only if directed to do so by the action described in a BIPxxxx message, or by your IBM Support Center.

You can specify the output to be directed to file, or to stdout. The trace records returned by this command are in XML format and can be browsed with an XML browser. If you direct output to file, the data is written in code page utf-8. The file is therefore platform-independent, and can be transferred to other systems for browsing or formatting using the mqsiformatlog command.

On HP-UX you are recommended to set the size parameter of the mqsichangetrace command to be less than 500 MB. Note that the size of the XML generated files is often half as much again as the original trace file, and setting the value of the size parameter to be greater than 500 MB can cause problems.

If you transfer this file to another system, ensure that you use a file transfer program that does not convert the data (for example, by specifying a binary transfer option).

If you specify a broker, or any of its resources (execution group or message flow) you must have deployed them before you can start trace and read the log files.

Syntax

User trace

Service trace

Parameters

component
(Required) The name of the component for which the log is to be read. This can be either a broker name or Configuration Manager name, or the fixed values , UserNameServer, workbench, or utility (all are case sensitive on Linux and UNIX systems and on z/OS).
-u
(Optional) Read the log contents from the user trace log. This is valid only if you select the broker component.
-e egroup
(Optional) The label of the execution group for which log information is to be read.
-o outputfilename
(Optional) The name of the file into which to write the log data. If you specify a full pathname, the file is created in the directory specified. If you specify just the filename, the file is created in the current working directory. The contents of the file are written in code page utf-8, which is platform-independent and preserves data such as DBCS characters.

You must specify a file name if you want to format the log using the mqsiformatlog command. If you do not specify a filename, the contents of the log are written to stdout. You are recommended to use a file extension of .xml.

-f
(Optional for User trace; required for Service trace). Read the log file directly from the file system. If you do not specify this option, the command sends an XML message to the component to request the log contents. If you have specified -t (service trace), you must specify this flag as well. Further details are given in Additional parameters exclusive to service trace.

If you specify this option, stop tracing (using mqsichangetrace) before you use the mqsireadlog command. If the log file is in use when you issue this command with this flag specified, partial XML records might be returned. You can reduce the risk of this happening by specifying -m safe on the mqsichangetrace command. If the component being traced has itself stopped, you do not then need to issue a mqsichangetrace command.

If you do not stop tracing before you issue this command, check the contents of the log file created and remove any partial records from the end using a text editor before using the mqsiformatlog command, as partial records cannot be read by the format command.

Additional parameters exclusive to service trace

Use these options only when directed to do so by your IBM Support Center or by a BIPxxxx message.

-t
(Required) Read the log contents from the service trace log.
-b qualifier
(Required) Read the contents of the log for the broker agent, Configuration Manager agent, or User Name Server agent, or for the specified command utility program. This option is valid only if you have specified -t (service trace).

The following table shows the valid combinations of qualifier and component for service trace.

This option is generally used to trace the commands themselves. If you want to trace a particular command, run that command with environment variable MQSI_UTILITY_TRACE set to debug or normal before you issue this command to read the trace output generated.

Enter these values exactly as shown.

The agent trace is initiated when you specify the -b flag on the mqsichangetrace command. Do this only when directed to do so by a WebSphere Message Broker error message or when instructed to do so by your IBM Support Center.

The service trace is initiated when you specify the -b flag on the mqsichangetrace command. The format of the command is:
mqsireadlog <brokername> -t -b service -f -o service.xml
Do this only when directed to do so by a WebSphere Message Broker error message or when instructed to do so by your IBM Support Center.
-f
(Required) Read the log file directly from the file system. When used with service trace, this flag has the same characteristics as when used with user trace. It remains optional if the -e flag is specified. You must specify this option if you specify the -b flag.
Qualifier Component= <broker_name> Component= ConfigMgr_name Component= UserNameServer Component= workbench Component= utility
mqsichangebroker x        
mqsichangeconfigmgr   x      
mqsichangetrace x x x    
mqsichangeusernameserver     x    
mqsiclearmqpubsub x        
mqsicreateaclentry         x
mqsicreatebroker x        
mqsicreateconfigmgr   x      
mqsicreateusernameserver     x    
mqsideleteaclentry         x
mqsideletebroker x        
mqsideleteconfigmgr   x      
mqsideleteusernameserver     x    
mqsiformatlog1         x
mqsijoinmqpubsub   x      
mqsilist2   x     x
mqsilist x        
mqsilistaclentry         x
mqsireadlog x x x   x
mqsireporttrace   x   x  
mqsistart x x x    
mqsistop x x x    
agent x x x    
service x x x    
workbench       x  
httplistener x        
Notes:
  1. Because this command does not have a component parameter, trace information is recorded in, and retrieved from, the utility component trace files. For further details see the mqsichangetrace command.
  2. If this command is invoked without a component, trace information is recorded in, and retrieved from, the utility trace files in addition to component specific files. For further details see the mqsichangetrace command.

Authorization

On UNIX platforms, the user ID must be a member of the mqbrkrs group. If the -f flag is specified, the user ID used to invoke this command must also have access to the trace file.

On Windows platforms, if the -f flag is specified, the user ID used to invoke this command must have access to the trace file. If the -f flag is not specified, the user ID used to issue the command must have mqbrkrs authority.

Responses

  • BIP8020 Unable to access database
  • BIP8029 Broker not configured
  • BIP8032 Unable to connect to queue
  • BIP8033 Unable to send XML message
  • BIP8035 Response not received within time-out
  • BIP8036 Negative response received
  • BIP8037 Unsupported flag selected
  • BIP8038 Unsupported command option
  • BIP8039 Execution group not available
  • BIP8040 Unable to connect to database
  • BIP8132 Invalid qualifier

Examples

User trace for broker WBRK_BROKER:

mqsireadlog WBRK_BROKER -u -e default -o trace.xml

Service trace for component ConfigMgr:

mqsireadlog ConfigMgr -t -b agent -f -o trace.xml

Service trace for utility mqsiformatlog:

mqsireadlog utility -t -b agent -f -o trace.xml

You can format the log file (trace.xml in the above examples) using the command mqsiformatlog, or view it using an XML editor or viewer.

Related tasks
Using logs