Component Broker Log Analyzer

(C) COPYRIGHT International Business Machines Corp., 1999l
All Rights Reserved * Licensed Materials - Property of IBM

• Installation and Setup
• Starting the Log Analyzer

The Component Broker Log Analyzer takes one or more activity or trace logs, merges all the data, and displays the entries in UnitOfWork sequence. It analyzes error conditions in the log entries to provide error message explanations and also interprets General Inter-ORB Protocol (GIOP) packets and General Page Fault (GPF) call stacks. As seen in the following image, the Log Analyzer's main window has three panes:

• Logs pane (left)
• Record pane (upper right)
• Analysis pane (lower right)

Logs pane (left)
Lists all the UnitOfWork (UOW) instances and its associated entries from the logs that you have opened. The file name of the first log that you opened is shown in the pane's title bar. There is a root folder and under it, each UOW has a folder icon which you can expand to show all the entries for that UOW. All log entries without any UOW identification are grouped into a single folder in this tree view. The UOW folders are sorted to show the UOW with the latest timestamp at the top of the list. The entries within each UOW are listed in the reverse sequence, that is the first (earliest) entry for that UOW is displayed at the top of the list within that folder. If you have merged several logs in the Log Analyzer, all the log entries are merged in timestamp sequence within each UOW folder, as if they all came from the same log.

Each UOW line has the following format:

Click the icon next to the UOW folder to see all the log entries for the UOW. Each log entry's identification has the following format:

Every log entry is assigned an entry number, Rec_nnnn, when a log is opened in the Log Analyzer. If more than one file is opened in the Log Analyzer (merged files), the Rec_nnnn identification will not be unique because the number is relative to the entry sequence in the original log file and not to the merged data that the Log Analyzer is displaying. This Rec_nnnn appears in the first line (RecoredId) in the Records pane.

By default, each entry in this pane is color-coded to help you quickly identify the ones that have high severity errors.

• Non-selected log entry with background color of:
  • Pink indicates that it has a severity 1 error.
  • Yellow indicates that it has a severity 2 error.
  • White indicates that it has a severity 3 error.
• Selected log entry with background color of:
  • Red indicates that it has a severity 1 error.
  • Green indicates that it has a severity 2 error.
  • Blue indicates that it has a severity 3 error.

These colors are configurable and can be changed in the Log Analyzer's Preferences Log page. See changing background color for different error severity levels for more information on how to do this.

After the Analyze or Advanced analyze action has been invoked, each log entry that was analyzed has the following icons:

• indicates that the entry has some analysis information in one or more pages in the Analysis pane.
• indicates that the entry has some analysis information and that it has a Reraised exception. When diagnosing problems, you may want to look at the log entry prior to this one.
• indicates that the entry has either a severity 1 or 2 error but no additional analysis information is available for it.
• indicates that the entry has a severity 3 error and it has no analysis information.

Record pane (upper right)
When you select an entry under the UnitOfWork in the Logs pane, you see the entry in the Record pane. The entry's identification is shown in the pane's title bar. Right-click in this Record pane to see the actions that you can perform on the entry. There is a drop down arrow next to Record which allows you to go back to look at the last ten  records that you have viewed. The cache for the historical data (10, by default) is set in the Preferences General page. Note: The associated analysis data for these cached records are not shown. To see analysis information for cached data, reselect the entry from the Logs pane.

Note: The Log Analyzer's timestamp format must match the format that was used by the showlog command when formatting the log. See Changing timestamp format for more information on how to change the Log Analyzer's timestamp format.

You can enable/disable line wrap mode for the Record Pane using the Log Analyzer Preferences notebook: Record. To print contents of this pane, select Record > Print when the Record pane is in focus.

Analysis pane (lower right)
There are five tabbed pages in this pane. When Analyze action has been invoked and additional information is available, the information will appear in the first four pages. The last page, GPF, is filled in when the Advanced analyze action is invoked and there is a GPF dump. If the page tab is grayed out, there is no information in that page. The pages of the Analysis pane are:

• Symptom
  The Component Broker Log Analyzer provides a database of information to help you recover from some common Component Broker errors. As a part of the Analyze action, if such recovery information is found in the database for the selected log entry, the information is displayed in this page.
• ORB Trace
  If the selected entry contains ORB communication trace data, the ORB packet dump (GIOP packet) appears in this page. Also analysis is performed on the Op Code in the GIOP packet to identify its type, and the dump is formatted to let you quickly understand its contents. See General Inter-ORB Protocol (GIOP) packets, on pages 41-49 of the Problem Determination Guide, for more information on the format of these dumps.
• Minor Code
  If the selected entry contains a minor code (0x4942nnnn) message, this page displays the Minor Code Messages documentation from the Problem Determination Guide and positions the view to show that specific minor code. If there is no documentation for that minor code, the Problem Determination Guide's Minor Code Messages information is still displayed but the view is positioned to the beginning of that documentation. You cannot save or print the information that is in the Minor Code page. You can, however, highlight and copy its information to the clipboard.
• Message ID
  If the selected entry contains other error messages that have additional message documentation in Problem Determination Guide, then this text is also shown in this page. You cannot save or print the information that is in the Message ID page. You can, however, highlight and copy its information to the clipboard.
• GPF
  If the selected log entry contains a GPF dump and you invoked the Advanced analyze action, the Log Analyzer will translate all the entries in the stack to calculate the relative offset in each DLL. If the map file for the DLL is not available (for example, map files for the somxxxx.dll modules are only available to IBM Support staff), the Log Analyzer's calculation stops at this point. If the map file is available, the Log Analyzer will help you identify the method in DLL that caused the exception. See HandleSignal - General Page Fault exception, on pages 11-14 of the Problem Determination Guide, for more information on translating call stacks.

You can set line wrap for information that appears in some of the pages in the Analysis pane using the Log Analyzer Preferences notebook: Analyzer output.

Status line
There is a status line at the bottom of the window showing the status of actions.

Log Analyzer features
Here are some of the features of the Component Broker Log Analyzer:

• View activity logs in UnitOfWork sequence
  You can use the Component Broker Log Analyzer to view formatted activity logs (that is, after running showlog -debug activity.log). If you do not want to run the showlog utility yourself, name the log file activity.log. When you open a file named activity.log in the Log Analyzer, the tool runs the showlog utility prior to opening it for viewing. If the Log Analyzer finds that the activity.log file contains formatted data, it skips the showlog formatting step.
• View formatted component/object trace logs
  Furthermore, you can use the Component Broker Log Analyzer to view other component or object trace logs (from the service\server\ServerName directory) after you have formatted them with the showlog or Combtrace utilities. If the trace log file is renamed to activity.log, the Log Analyzer also runs the showlog command on the file to format it prior to opening it for viewing.
• Merge several logs and view all entries
  When you have several trace and activity logs relevant to the problem that you can diagnosing, you can use the Component Broker Log Analyzer to merge all these logs and display all the entries within timestamp sequence in the UOW folders. The data appears as if they came from one log.
• Highlighting with color and icons
  Log entries are color-coded to let you quickly find the ones that have high severity errors.
• Analyze action
  The Component Broker Log Analyzer tool has a very powerful analyze action that retrieves and displays additional documentation on known errors and error messages in the Analysis pane (Symptom, ORB trace, Minor code, and Message ID pages). You can invoke the Analyze action from the root folder, any UOW folder, or log entry. If you invoke Analyze for the root folder, then all the entries in the log will be analyzed. If some analysis information is available for an entry, it will either have a or icon next to it in the Logs pane.
• Advanced analyze action
  The advanced analyze action translates call stacks in GPF exceptions. You can invoke this action from any UOW folder, or selected log entry. You can also invoke the Advanced analyze action from the root folder. GPF records may take some time to process; there is a process indicator showing its status. You will be prompted to specify the map file directory when you select Advanced analyze.
• Saving logs
  If you intend to look at the same Log Analyzer data again at a later time, you may want to save the data as an XML file. Any retrieved Symptom, ORB Trace and GPF analysis information is also saved. If logs are merged in the Log Analyzer, the saved file contains entries of all the merged logs in the sequence that is shown in the Logs pane. You can also do selective saves by making multiple selections of folders and/or entries in the Logs pane. Note: If the merged logs have different timestamp formats, you should not save the merged information because the Log Analyzer only recognizes a single timestamp format for each file that it opens. See Saving logs for instructions on how to save the Log Analyzer's data.
• Printing logs
  You can print all the data displayed in the Log Analyzer or print selected folders and/or entries. Any retrieved Symptom, ORB Trace and GPF analysis information related to your saved entries is also printed. See Printing logs for instructions on how to do this.
• Copying log data
  You can highlight information in the Record and Analysis panes and copy it to the clipboard using Edit > Copy menu selection.
• Finding data
  You can easily locate relevant information in each pane by using Edit > Find action.

Setting Up (Installing) the Component Broker Log Analyzer
Download logbr.zip into the directory where Component Broker is installed (usually C:\CBroker) and expand it (unzip).

Starting the Component Broker Log Analyzer
The Component Broker Log Analyzer can be started by following these steps:

1. If the log file is named activity.log file, you can skip this step. If not, run showlog filename -debug command on your raw log file to format it for viewing. See related information on how to use the showlog utility.
2. Type in a command window:

    ivblogbr [logfilename logfilename ...] 

   and optionally specify one or more logfilenames which are fully qualified names of log files. If more than one file name is specified, all the data from the logs are merged. The Log Analyzer main window opens.

3. If you did not specify a file name when invoking the Log Analyzer, from the File menu, select open and specify the activity log or a previously saved XML file of a log.

Opening a formatted activity log or an XML file in the Log Analyzer
You can open your formatted activity or trace log by selecting Open from the File menu. You can choose to open your formatted log file or a previously saved XML file. If you already have a log file opened in the Log Analyzer, the system will prompt you to save and close that file prior to opening a new one.

If you get a "wrong timestamp format" error message, it means that the format of the timestamp (the date and/or the time) information that is in the formatted log does not match the Log Analyzer's timestamp format setting. See Changing timestamp format for more information on how to change the Log Analyzer's timestamp format.

Merging several logs in the Log Analyzer
You can open (merge) several logs in the Log Analyzer. The first file that you open, use the File > Open action. Subsequently, for each file that you open use the Merge with action. All the entries from the logs are merged in timestamp sequence within each UOW folder, as if they all came from the same log.

Analyzing logs
You can invoke the analyze and/or advanced analyze actions to obtain additional analysis data for the log that you have opened in the Log Analyzer. The analyze action populates information in the Analysis pane's Symptom, ORB trace, Minor code, and Message ID pages. The advanced analyze action populates information in the GPF page. Follow these steps to invoke these actions:

• From the Logs pane
  1. Select one or more folders and/or entries that you want to analyze. Hold down the Ctrl key to make multiple selections.

     Note: To perform analysis on all the records, select the root folder (the first folder) in the Logs pane.

  2. Right-click and select Analyze or Advanced analyze action, depending on the analysis that you require. If the analyze or advanced analyze action has already been performed, the selection will be grayed out.
  3. Analysis will be performed and when completed, you will see an icon next to the analyzed entries indicating if any analysis data is available for it.
• From the Record/Analysis panes
  1. Right-click and select Analyze or Advanced analyze action, depending on the analysis that you require. If the analyze or advanced analyze action has already been performed, the selection will be grayed out.
  2. Analysis will be performed and when completed, you will see an icon next to the analyzed entries indicating if any analysis data is available for it.

  Optionally, you can also select Analyze or Advanced analyze from the Record menu and analysis will be performed on the selected entries in the focused pane.

Changing background color for different error severity levels
You can use the settings in the Preferences notebook to change the default colors that are used to indicate the different severity levels of errors in log entries. Follow these steps to open the Preferences notebook to the Logs page:

1. From the File menu, select Preferences.
2. Click on Logs in the left pane.

To choose a background color for selected log entry that has a severity 1 error, do the following:

1. Select Selected node.
2. Select Severity 1.
3. Select the color by clicking on the Color graph. If you want to use the default setting, click Restore Default. If you want to see the result of your change, look at the Sample box and select the type of node that you just changed.
4. Click Apply to save that setting.

Repeat similar steps to change the background color for selected log entry that have severity 2 and 3 errors.

To choose a background color for an unselected log entry that has a severity 1 error, do the following:

1. Select Unselected node.
2. Select Severity 1.
3. Select the color by clicking on the Color graph. If you want to use the default setting, click Restore Default. If you want to see the result of your change, look at the node in the Sample box.
4. Click Apply to save that setting.

Repeat similar steps to change the background color for unselected log entry that have severity 2 and 3 errors.

When you are done, click OK to close the notebook and apply the changes.

Changing timestamp format
The showlog command writes all the timestamp data in the formatted log using the time and date formats in the workstation's Regional Settings. The Log Analyzer must use the same timestamp format to open the log. If the formats do not match, you will get a "wrong timestamp format" error message. Follow these steps to change the Log Analyzer's timestamp format:

1. From the File menu, select Preferences.
2. Click on Record in the left pane.
3. Select the right format for the Time format and Date format and click OK to save the change.

   If you do not see the format that you want in the time and/or date lists, do the following:

   1. Exit the Log Analyzer.
   2. Edit the ivblogbr.bat file to make sure that the format you want is listed in the settings of -DTimeStampDateFormat and -DTimeStampTimeFormat, as shown in the following:

      -DTimeStampDateFormat=
      
      
        "M/d/yyyy,MM/dd/yyyy,M/d/yy,MM/dd/yy,yy/MM/dd,dd-MMM-yy"
      
      
      -DTimeStampTimeFormat=
      
      
        "H:mm:ss.,h:mm:ss.,hh:mm:ss.,HH:mm:ss.,HH:mm:ss,hh:mm:ss"

   3. Save the change and start the Log Analyzer.
   4. Repeat steps 1 - 3.

Saving logs
If the first file that you opened is an XML file, select File > Save to resave the XML file with all the data that is currently displayed in the Log Analyzer. Any Symptom, ORB Trace and GPF analysis information is also saved. If logs are merged in the Log Analyzer, the saved file contains entries of all the merged logs in the sequence that is shown in the Logs pane. Note: If the merged logs have different timestamp formats, you should not save the merged information because the Log Analyzer only recognizes a single timestamp format for each file that it opens.

To save all the Log Analyzer's data in another file, select File > Save as.

To selectively save some of the entries, select the log entries that you want to save in the Logs pane and select Record > Save to file. Hold down the Ctrl key for multiple selections. You can select UOW folders, in which case, all the entries in the folders are selected and saved. All the retrieved Symptom, ORB Trace and GPF analysis information for those entries is also saved.

Printing logs
To print all the Log Analyzer's data, select File > Print log. All the retrieved Symptom, ORB Trace and GPF analysis information is also printed.

To selectively print some of the entries, select the log entries that you want to save and select Record > Print. Hold down the Ctrl key for multiple selections. You can select UOW folders, in which case, all the entries in the folders are selected and printed. All the retrieved Symptom, ORB Trace and GPF analysis information for those entries is also printed.

To print the Record Pane's contents, click the Record Pane to select the pane and then select Record > Print. This action prints the focused pane.

To print one of the Analysis pane's pages, select the page so that it is currently displayed in the pane and then select Record > Print.