mqsireadlog command

Supported platforms

  • Windows
  • Linux and UNIX systems
  • z/OS through the BIPJLOG utility; see z/OS utility jobs

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.

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 the fixed values ConfigMgr, UserNameServer, workbench, or utility (all are case sensitive on Linux and UNIX systems).
-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
Start of change(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.

End of change

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 Business Integration Message Broker error message or when instructed to do so by your IBM Support Center.

Start of changeThe 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 Business Integration Message Broker error message or when instructed to do so by your IBM Support Center.End of change
-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 Component= UserNameServer Component= workbench Component= utility
mqsichangebroker x        
mqsichangeconfigmgr   x      
mqsichangetrace x x x    
mqsichangeusernameserver     x    
mqsiclearmqpubsub x        
mqsicreateaclgroup         x
mqsicreatebroker x        
mqsicreateconfigmgr   x      
mqsicreateusernameserver     x    
mqsideleteaclgroup         x
mqsideletebroker x        
mqsideleteconfigmgr   x      
mqsideleteusernameserver     x    
mqsiformatlog1         x
mqsijoinmqpubsub   x      
mqsilist2   x     x
mqsilistmqpubsub x        
mqsilistaclgroup         x
mqsireadlog x x x   x
mqsireporttrace   x   x  
mqsistart x x x    
mqsistop x x x    
agent x x x    
Start of changeserviceEnd of change Start of changexEnd of change Start of changexEnd of change Start of changexEnd of change    
workbench       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:

Start of change
mqsireadlog ConfigMgr -t -b agent -f -o trace.xml
End of change

Service trace for utility mqsiformatlog:

Start of change
mqsireadlog utility -t -b agent -f -o trace.xml
End of change

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