Logtool Tutorial: All the files

This Web page contains all the files that make up the Logtool Tutorial.

You can print it out from your browser to get a hardcopy version of the entire Logtool Tutorial.

Logtool Tutorial: Summary

Logtool is an interactive utility that runs under the Support Tool Manager (STM). It allows you to monitor recoverable errors detected by the computer, such as single-bit memory errors, and I/O device errors. By analyzing this information, you can troubleshoot failures before they become acute.

Error information is contained in system log files. Since the raw files are hard to read, Logtool allows you to format the files and to filter them for desired entries (for example, for all entries related to SCSI disks).

Unlike other support tools, this utility program is not device specific and does not require selection of a device to run.

Running logtool usually consists of the steps summarized below. For details about each step, click on the hyperlink.

1. Start a version of STM

   xstm: /usr/sbin/xstm
   mstm: /usr/sbin/mstm
   cstm: /usr/sbin/cstm

2. Start logtool from STM (Start in xstm / Start in mstm)

   xstm: Tools | Utility | Run | (select "logtool")
   mstm: Tools | Utility | Run | (select "logtool")
   mstm (shortcut): press lowercase "L" and RETURN.
   cstm: runutil logtool

3. Select a raw log file (Raw logs). Usually you are interested in the current log file, the name of which ends in ".cur".

   xstm: File | Select Raw | (select desired raw log file)
   mstm: File | Select Raw | (select desired raw log file)
   cstm: At a UNIX prompt, see what log files are available (ls /var/stm/logs/os); then sr (selectraw).

   When you select a raw log file, logtool automatically displays a summary of the events in the log (Logtool versions 2.0 and above).

4. Make the log file easier to read by turning it into a formatted log file (Formatted Logs).

   xstm: File | Format Raw
   mstm: File | Format Raw
   cstm: fr (formatraw)

   After you format the log, logtool automatically displays a summary of the events in the log (Logtool versions 2.0 and above).

5. Select (filter) the entries you want to see by using the commands under the Filters menu (Filters).

   Logfiles can contain many entries. You can specify a filter to be applied during the formatting process, or to be applied when viewing a file. Use the commands under the Filters menu.

Other tasks you can perform with Logtool (Other tasks).

• Save a log as a file.
  
• Create a new "current" raw log file.
  
• Monitor and control memory error logging.

Logtool Tutorial: Start logtool in xstm

In xstm, the sequence to start logtool is:

Tools | Utility | Run | (select "logtool")

This page goes through the process step-by-step.

The System Map

In the figure that follows, you can see the xstm system map with a diagram of all the devices that make up the system.

Go straight to the Tools pull-down menu. Since logtool is a utility, choose "Utility", then "Run".

With most other support tools (such as verifiers and exercisers), the first step is to select the devices on which you want the tools to run. For example, you select a disk, then run a verifier on it. Logtool, however, is not associated with any device -- you're just looking at logs. Therefore, you don't have to select a device.

Answering the Query

Since STM offers several kinds of utilities, you are next queried for the name of the utility. In xstm, a dialog box appears and you choose "logtool".

Initial Screen for logtool (xstm)

Afterwards, the program will open a new window exclusively for logtool. The original STM window with the system map will remain on your display.

Interacting with logtool

As you can see from the above figure, you interact with logtool in xstm by choosing commands from pull-down menus. Output is displayed in logtool's main window. Initially, some basic instructions for using logtool are displayed in the window. For more help, use the online help system available from the Help pull-down menu.

Logtool Tutorial: Start logtool in mstm

In mstm, the fastest way to call up logtool is with the shortcut:

Press lowercase "L" and RETURN.

Early versions of logtool don't support this shortcut. If you have an early version of logtool (below version 2.0), you will have to call up logtool with the normal process:

Tools | Utility | Run | (select "logtool")

This page describes the normal process for calling up logtool. Even if you use the shortcut, this page will help you become more familiar with the mstm interface.

System map

When you first call up mstm, you'll see a system map as in the following figure. All the devices in the system are listed, along with their path and some status information.

You can use the shortcut to call up logtool (press lowercase "L" and RETURN). This will send you directly to logtool's initial screen.

Another way to call up logtool is through the pull-down menu system.

Selecting commands in mstm

The pull-down menus in mstm correspond to the pull-down menus in xstm. To access commands in mstm:

1. Activate the menubar. There are two methods for accessing the pull-down menus:
   • Press the TAB key; it will move the cursor back and forth between the system map and the menubar, or:
   • Press the menubar on/off function key.
2. Use the left/right arrow keys to move to the desired menu.
3. Open the desired menubar. There are also two methods for this:
   • Press RETURN, or:
   • Press the Select/Deselect function key.
4. Use the up/down arrow keys to move to the desired command.
5. Press RETURN or use Select/Deselect function key to execute the command.

Calling up logtool with pull-down menus

The following example shows how to use the pull-down menus to call up logtool.

Press TAB or the menubar on/off function key; "file" is highlighted.

Press RETURN, and you will have access to the same commands as are available from the File pull-down menu in xstm.

As in xstm, we don't have to select any devices to call up logtool. Instead we use the left/right arrow keys to move the cursor to the "tools" pull-down menu and press RETURN. This will bring up the first set of tools.

To access the utilities (logtool is a utility), use the up/down arrow keys to move down until utility is highlighted, then press RETURN.

Make sure "run" is highlighted in the next box and press RETURN. Because STM offers several utilities, you are next prompted for the name of the utility to run.

Select the "logtool" entry by using the up/down arrow keys until logtool is highlighted, then press RETURN. The entire line will now be highlighted, then press the "OK" function key. You will now see the initial screen of logtool:

You interact with logtool in mstm the same way as in xstm, with pull-down menus. Output is displayed in the window. Initially, some basic instructions for using logtool are displayed in the window. For more help, use the online help system available through the "Help" pull-down menu.

Logtool Tutorial: Raw logs

When STM is installed on a computer, a logging daemon is activated to monitor recoverable errors that have been detected by the system. For example, the logging daemon monitors I/O errors (detected by drivers). The errors are recorded in raw log files. They are called "raw" because the raw logs have not yet been formatted and it is difficult to read them.

Selecting a Raw Log

The first step in using logtool is to select a raw log file:

xstm: File | Select Raw | (select desired raw log file)
mstm: File | Select Raw | (select desired raw log file)
cstm: At a UNIX prompt, see what log files are available (ls /var/stm/logs/os); then sr (selectraw).

In xstm you would see:

The current log file (the log file currently being written to) is the default. The current log file always ends in "cur". In the example below, the current log file is "log_0002.raw.cur".

NOTE: you may not see a current log file on the computer. A currrent log file is not created until an error is actually logged.

In mstm, the screen is almost the same:

---

NOTE: Because the xstm and mstm versions of logtool are so similar, we'll only show the xstm versions from this point on in the tutorial.

---

Viewing the Raw Log

Now that you've selected a raw log, you want to see what's in it. The quickest way is to look at the summary of the raw log, without doing any formatting.

When you select a raw log file, logtool automatically displays a summary of the events in the log (Logtool versions 2.0 and above).

A summary for a very short log file (13 entries) looks like this. This particular display is from an older log file, "log1.raw".

Displaying the Raw Log Summary

If your version of logtool is earlier than 2.0, or if you want to look at the summary at any other time while running logtool, you can display the summary with the command sequence:

xstm: View | Raw Summary
mstm: View | Raw Summary
cstm: rs (rawsummary)

In xstm, you pull down the View Menu, then select "Raw Summary". Then, if you want, you can select "Raw Log" to view the entire log file. Beware -- log files can be very long.

Logtool Tutorial: Formatted logs

If you choose to view the raw log file directly, you will see entries that look similar to the following figure:

Not very informative, is it?

In general, you'll want to format (decode) the raw log file so it is understandable. To do this:

xstm: File | Format Raw
mstm: File | Format Raw
cstm: fr (formatraw)

After you format the log, logtool automatically displays a summary of the events in the log (Logtool versions 2.0 and above).

Viewing a Formatted Log

Once you have formatted the selected raw log file, you can view the formatted version. Just as with raw log files, you can view the entire formatted log or just a summary. The command sequence is:

xstm: View | Formatted Summary or Formatted Log
mstm: View | Formatted Summary or Formatted Log
cstm: fl (formattedlog) or fs (formattedsummary)

Below is example text from a formatted entry in a log file. This is the formatted version of the previous raw log entry. As you can see, the Error Code is decoded for you: "No card in expected bus slot or wrong card in slot."

Logtool Tutorial: Filters

A typical log generally contains a large number of entries. When you are troubleshooting a problem, only certain entries may be relevant. For example, you may want to see only I/O errors that occurred during a certain time period on a certain hardware path.

Logtool offers three different occasions for filtering the entries that are relevant to your task.

• Format filter. To filter entries during the formatting of a raw log file, select the Format command in the Filters Menu. (mstm: filter | FORMAT )

  xstm: Filters | Format
  mstm: Filters | Format
  cstm: format (ff).

• Raw display filter. To filter entries during the viewing of a raw log file:

  xstm: Filters | Display | Raw
  mstm: Filters | Display | Raw
  cstm: displayraw (dr)

• Formatted display filter.To filter entries during the viewing of a formatted file:

  xstm: Filters | Display | Formatted
  mstm: Filters | Display | Formatted
  cstm: displayformatted (df)

Logtool Tutorial: Other tasks

Other Tasks You Can Do With Logtool

System error log file. This log contains I/O error entries, LVM error entries, Sys overtemp errors, etc. In addition to the logtool commands for viewing and formatting this log, logtool provides commands to manage it:

Save the current system error log as a file.
xstm: File | Save As
mstm: File | Save As
cstm: sav (save)

Clear the current system error log file and create a new one:
xstm: File | Switch Log
mstm: File | Switch Log
cstm: sl (switchlog)

The existing system error log file is renamed. A new system error log file is started the next time there is an error to be logged. For example, the Switch Log command moves "log5.raw.cur" to "log5.raw," causing the logger process to open a new raw log file called "log6.raw.cur" the next time there is an error to be logged.

Monitor and control memory error logging. Use commands in the Memory pull-down menu. For example:

Clear the memory log file (deletes old file and starts a new one).
xstm: Memory | Clear Log
mstm: Memory | Clear Log
cstm: cl (clearlog)

Since this command DELETES the existing memory log file, you may want to view it first:
xstm: Memory | Report Log | View Detail
mstm: Memory | Report Log | View Detail
cstm: vd (viewdetail)

If desired, use an HP-UX command to save the memory log file (/var/stm/logs/os/memlog) to a different name.

View the error log and boot log. Use commands in the Chassis pull-down menu.

By now you know the basic tasks you can perform with Logtool. For more details, see the online help, available as a Web page (Logtool Reference) or through the online Help pull-down menu or Help function key from within logtool.