The phrase collecting event data refers to the process of starting event logging on the IRIX target, and then capturing that data as it is uploaded to the host. After the event data is collected, you can analyze it. This chapter describes how to collect event data; Chapter 3, “Working with Event Data” describes how to examine and analyze it.
There are two methods for collecting event data with WindView for IRIX:
The basic method, using the WindView GUI to control event data collection; see “Using the WindView GUI”.
The advanced method, controlling event data collection with the rtmon-client program; see “Advanced Methods for Using WindView”.
Throughout this chapter, the following terms are used:
| event | This is any action undertaken by a process or an interrupt service routine (ISR) that can affect the state of the real-time system. Examples of events are process spawns and deletions, system clock ticks, and interrupts. The IRIX kernel has been instrumented to log this event information. | |
| event logging | This is the target activity of writing information about events to the WindView event buffer as the events occur. | |
| event data | This is information that is logged to the WindView event buffer and uploaded to the host by the WindView real-time monitoring daemon, rtmond. | |
| event log | This is a finite collection of event data that resides on the host. | |
| processed event log |
| |
| raw event log | This is the format of an event log collected by the rtmon-client tool; see “Using the rtmon-client Tool and the Analyze Menu Option”. |
This chapter assumes that WindView has been installed and configured for your environment; see the WindView release notes for details.
For specific information on any of the WindView GUI commands mentioned in this chapter, see Chapter 5, “Command Reference.”
This section covers the following topics:
 | Note: Before proceeding with this section, make sure that WindView has been correctly installed and the rtmond daemon is running. For more information, see the WindView release notes and “Starting the rtmond Daemon”. |
This section is intended to help you get WindView up and running quickly. Once you understand WindView operation, you may choose to use the advanced methods described in“Advanced Methods for Using WindView” to collect event data.
This section describes the following:
Before you can collect data from the target, you must invoke the windview program on the host. To use the following command, be sure to update your shell $PATH variable to include the pathname /usr/WindView/bin. Enter the windview command from an IRIX shell:
% windview |
When the windview command is successful, the WindView Main window appears. This window is described in the following section.
WindView's Main window is shown in Figure 2-1.
The WindView Main window includes a message area; when you first invoke WindView, the following message should appear:
Site Tcl Initialization Complete. |
The WindView Main window contains the following pulldown menus, which are discussed in this chapter and in Chapter 3, “Working with Event Data.” For detailed information on any of the menu commands, see Chapter 5, “Command Reference.”
| File | This menu contains the commands for analyzing raw event logs, and for opening and saving processed event logs. It also contains the Quit command, which allows you to exit a WindView session. | |
| Windows | This menu lets you display windows with which to control the target and examine event data, including the View Graph window. | |
| Help | This menu contains the Help commands; for details, see “Using Help”. |
Leave the WindView Main window open at all times: the message area provides feedback on WindView operations, and the commands in its menu bar are useful when examining event data.
To use the pulldown menus, use the left mouse button. You can also use the keyboard shortcuts: press the <ALT> key plus the letter underlined in the menu bar. For example, to display the File menu, press <ALT-F>. Then, to pick one of the commands from the menu, type the underlined letter. For example, to choose the Quit command, type Q when the File menu is open.
For other window-manipulation tips, see the documentation for your window manager.
The WindView online help facility provides two types of information: information on the current WindView release, and a hypertext, context-sensitive online help system.
To display information on the current WindView release, choose the “About WindView” command from the Help menu. The window shown in Figure 2-2 appears, showing the WindView version number and the copyright information. Click the OK or Cancel button to remove this window from your screen, or click the Help button to display information for this window.
To display the WindView Help contents, choose the “Content” command from the Help menu. The WindView Help window appears as shown in Figure 2-3; for information on how to use this window, choose commands from this window's Help menu.
To use context-sensitive help, go to the WindView Main window and choose the “For Context” command from the Help menu. The cursor turns into a question mark; you can move this question mark over any element of the user interface and click with the left mouse button to display information for that element.
In addition to these Help menu commands, many WindView windows (such as the Save Event File, Open Event File, and Analyze Event Log) contain their own Help button. Clicking on this button displays information for that window.
To exit WindView at any time, choose the “Quit” command from the File menu. The WindView Main window and all other WindView windows are removed from the screen.
| Note: When you exit WindView, you are not prompted to save your event data. To save event data before exiting, follow the instructions in “Save Command”. |
The process of importing event data consists of the following steps, which are described in this section:
Displaying a view graph.
Setting up for event logging.
Starting and stopping event logging on the target.
The View Graph window is used to view the event data. It is not necessary to open a View Graph window to collect event data. It can be opened at a later time to analyze the collected data.
 | Tip: To minimize intrusion on the target system, it is recommended that the event data not be viewed as it is being received. |
To display a View Graph, choose New Graph from the Windows menu. An empty View Graph window labeled View 1 appears; see Figure 2-4. This window is described in detail in “Understanding the View Graph”.
To set up for event logging, first open the Target window by choosing the Target command from the Windows menu. Figure 2-5 shows the Target window.
Then, follow these steps to use this window:
Type the target system's name in the Target Name field. (To find out the target system's name, type uname -n on the target system.)
Note: The target and the host may be the same system, in this case, enter the hostname of the system you are executing on. The default event port number of 6164 is displayed in the Event Data Port field. For more information, see “Setting the Event Port Number”.
In the Processor ID field, type in the processor number of the target system where you want to start event logging and click Start.
You can simultaneously monitor several processors on the same target system; type in a processor number and click Start followed by the next processor number and Start.
To start the logging of events on the target, click the Start button in the Target window. Event data will begin to appear in the View Graph; if it does not, see “Event Buffer Overflow Information”.
Pause event logging at any time by clicking the Stop button. Event logging ceases on the processor that is currently identified in the Processor ID field. To easily stop event logging on all processors, click the Disconnect button. You are now ready to analyze the event data; see Chapter 3, “Working with Event Data.”
| Note: If you stop event data collection with Disconnect and then click Start again, the event data displayed in the View Graph is overwritten by the new event data. You can save the previous event data with the Save command; see “Save Command”. |
If you click the Start button in the Target window, but no event data appears in the View Graph, or if it starts to appear but stops before you have clicked Stop, the following warning message may appear in a popup window:
Target event buffer overflow |
This occurs when the event rate exceeds the bandwidth of the connection. In this case, the event logging mechanism shuts itself off. Try one or more of the following strategies to solve this problem:
Toggle off the Track Incoming Data button in the View Control window. Doing so keeps the View Graph from being updated as new event data arrives. Instead, the View Graph is “frozen.” See “Examining Data” for details.
If you believe that network traffic may be the cause of the problem, isolate the host and target on a subnetwork or a standalone network.
Use the rtmon-client tool to collect the event data; see “Using the rtmon-client Tool and the Analyze Menu Option”.
You may find it convenient to save event data to a processed event log for later study. To do so, choose the Save command from the File menu. The Save Event File window shown in Figure 2-6 displays.
The current working directory is displayed in the Filter and Selection fields by default. Type the appropriate directory name and filename into the Selection field; then click the OK button or press the <Return> key to save the file and remove the Save Event File window from the screen. If the file that you wish to save to is listed in the Files subwindow, you can double-click the name to overwrite that file with the current event data. (For details on working with this window, see “Save Command”.)
When a processed event log is saved, two files are created: filename.wv and filename.wvd. These files must be kept together in the same directory, the .wv and .wvd suffixes intact, or the “Open” command will not be successful.
Now you can import the processed event log any time you wish to study it. Choose the “Open” command from the File menu. The Open Event File window shown in Figure 2-7 appears.
Use this window in the same way that you use the Save Event File window: type the appropriate directory name and filename.wv into the Selection field, then click the OK button or press the <Return> key to open the file and remove the Open Event File window from the screen. If the file that you wish to open is listed in the Files subwindow, you can double-click on the name to open it. (For details on working with this window, see “Open Command”.)
Note that processed event logs have the .wv suffix; if you attempt to open a raw event log with the .wvr suffix, an error message appears. A raw event log with the .wvr suffix is generated by the rtmon-client tool; see “Using the rtmon-client Tool and the Analyze Menu Option”.
If the processed event log is successfully opened, a message similar to the following appears in the Main window message area:
Processor 1: CPU: R4400 BSP: Silicon Graphics |
Then, if the View Graph is displayed, the processed event log is displayed there; see “Displaying a View Graph” for information. (Note that you can display the View Graph either before or after you have opened a processed event log.)
Now that you understand the basics of collecting data with WindView, you may choose to replace some of the GUI methods of collecting data with the more advanced methods detailed in this section. These methods can provide greater flexibility in your use of WindView, particularly in the ways in which you start event logging and import event data.
Specifically, this section covers these topics:
For greater flexibility at invocation, you can specify arguments to the windview command The following shows the complete syntax of the command:
windview [ -port number ] [ -target name ] [ -emc size ] [ –nx ] \ [ -x filename ] [ –xi expression ] [ -XToolkitFlag ...] |
Note that all flags are optional. The following is a description of each:
| -port number | Specifies the minimum event port number that you would like to use; the default is 6164. WindView attempts to obtain a port number, using this value as the minimum. That is, if you specify 5050, then 5050 is the lowest event port WindView attempts to own. | ||
The port number that WindView was successful in obtaining is displayed in the Event Data Port field of the Target window. Using this flag has the same effect as typing the port number in this window. See “Setting the Event Port Number” for information on using the Target window and for other issues involved with the event port number. | |||
| -target name | Specifies the name of the target that is to receive commands from WindView. The name you specify here is displayed in the Target Name field of the Target window. Using this flag has the same effect as typing the target name in this window; see “Setting the Event Port Number” for information. | ||
| -emc size | Specifies the size of the host event buffer in integer megabytes; the default is 8 MB, the minimum is 1 MB, and the maximum is determined by the amount of memory on your host. After this limit is reached, events accumulate in a file in the current directory named wndvw_unique_id. | ||
| -nx | By default, WindView reads the following Tcl initialization files, in the following order (for information on Tcl initialization files, see “Customizing WindView Tcl Initialization Files”): | ||
/usr/WindView/resource/tcl/WindView.tcl | |||
~/.windview.tcl | |||
./.windview.tcl | |||
The -nx flag prevents WindView from reading your personal and the current directory's WindView Tcl initialization files. Only the site WindView initialization file and files specified with the -x flag (see below) are read. | |||
Tcl initialization files are read automatically only at WindView startup. | |||
| -x filename | Reads additional Tcl initialization information from the specified file. This file is read only after the site Tcl initialization file, your personal Tcl initialization file, and the current directory's Tcl initialization file. If you supply multiple Tcl initialization files with multiple –x flags, only the last file is used. | ||
Tcl initialization files are read automatically only at WindView startup. | |||
| -xi expression | Evaluates the specified Tcl expression. This expression is evaluated only after any initialization files have been read, including any specified with the -x flag, above. If you specify multiple Tcl expressions with multiple -xi flags, only the last expression is evaluated. | ||
For example, you can use the -xi flag to get around the one-file-only restriction of the -x flag. The following shows the -xi flag being used to source both the foo file and the bar file:
| |||
Note that because there is more than one word in the specified expression, the words are enclosed in single quotation marks. | |||
| -xToolkitFlag | Any standard X Toolkit flags, such as -fg, -geometry, or -xrm. For additional information on the X Toolkit flags, see “Application-Specific Resources”. |
When the windview command is successful, the WindView Main window appears; see “Understanding the WindView Main Window” for information.
The event port number is the host TCP/IP port over which the WindView host component listens for event data from the event buffer daemon, rtmond.
If you invoke the windview command without specifying an event port number with the -port flag, WindView starts negotiating for a port number starting at number 6164. When the Main window appears, you can see which event port number WindView obtained by looking at the Event Data Port field in the Target window (choose the Target command from the Windows menu).
If WindView was successful in getting port 6164, and if you start event logging (see “Starting Event Logging and Instrumenting Timestamps”), you can now start your application. As soon as the application encounters the first event logging instruction, you will start to receive event data in your View Graph.
However, one of the following may be true:
WindView may not have been successful in getting port 6164.
You may have specified for WindView to start negotiating for a port number starting at a different minimum number with the -port flag; see “Specifying Arguments to the windview Command”.
You may now, or at some later point, want WindView to start negotiating for a port number starting at a different minimum number using the Target window (this has the same effect as using the -port flag); see the following section.
In any of the above cases, you must inform the target of the new event port number. The following subsections first describe how to set an event port number using the Target window, then describe how to inform the target of the new event port number.
Choose the Target command from the Windows menu to display the Target window, shown in Figure 2-5.
The successfully negotiated event port number is displayed in the Event Data Port field; in the figure above, WindView was successful in getting port 6164. If this is not the appropriate port number, you can change it with this window at any time.
To use this window, follow these steps:
Type the target's name in the Target Name field.
You can find the target name by typing uname -n at the command line on the target system.
If you used the -target flag to the windview command, that target name will be displayed in the Target Name field. You must specify the target's name before clicking the Start button of this window.
Type the processor number in the processor ID field. For example, to collect data on processor 3, type 3 in the Processor ID field.
If the event port number is appropriate for your use, click the Start button.
If the event port number is not appropriate, type the minimum port number you would like to use in the Event Data Port field. The valid range is 5001 to 32767. For example, if you would like to use any port number above 5050, type 5050.
Press the <Return> key. WindView attempts to obtain a new event data port number, using your input into the Event Data Port field as its minimum. That is, if you type 5050, then 5050 is the lowest event data port WindView will attempt to own.
When WindView has obtained a port number, the number it was successful in obtaining is displayed in the Event Data Port field.
Event logging is the target activity of writing event data to the target event buffer as the events occur. You can use the WindView GUI to collect events, described earlier in this chapter, or the rtmon-client tool, as described in this section. You add timestamps to user applications with the rtmon_log_user_tstamp() function.
The REACT/Pro user timestamp logging function, rtmon_log_user_tstamp(), is used to insert timestamps into user application code. This function logs events and passes them to rtmon_client or WindView. These user events can then be viewed from the Tcl Event Inspector window. For more information about implementing the rtmon_log_user_tstamp() function, see the rtmon_log_user_tstamp reference page.
In WindView for IRIX, user events greater than 20000 are operating system events. For a descriptions of these user events, see Table 4-2.
The REACT/Pro real-time monitoring daemon, rtmond, must be running on the target machine for WindView to collect event data. Only one copy of rtmond can run on a machine and it must be started at the command line. Once rtmond is started, data can be collected with WindView or rtmon-client.
To start the rtmond daemon, on the target machine at the command line, type:
/usr/react/etc/rtmond |
The daemon has two optional arguments:
| -d | Sends error messages to the terminal window where rtmond is started. By default, error messages are written to syslog. | |
| -p n | Determines how the process name is displayed on the View Graph. The following values are supported for n: | |
0 Displays the process name. | ||
1 Displays the process ID of the program with the timestamp in the format pid-x where x is the PID. | ||
2 Displays the process name and process ID in the format name(id) (this is the default). |
For more information on rtmond, refer to the reference page rtmond(1).
The rtmon-client tool offers a programmatic alternative to the WindView GUI for event collection. This tool allows you to collect a raw event log on the host without importing it into WindView until some later time. For example:
rtmon-client uses much less processor attention. Your real-time system generates a large amount of event data. Because the WindView GUI must process the event data before it can display it, you may encounter target event buffer overflow conditions if your host computer does not have enough speed to allow WindView to process the events in real time (see “Event Buffer Overflow Information”).
You want to collect event data at a remote site for later analysis at a lab. You can use rtmon-client to collect a raw event log as the remote system runs, and then import and view the event data with the WindView GUI at the lab.
You want to save event logs to multiple files, each generated from a different operating condition. rtmon-client provides an option that allows you to save event logs into multiple files; each time event logging is turned off and then on, a new file is generated.
To use rtmon-client, type the following at the command line on the target system:
/usr/react/bin/rtmon-client |
By default, the collected raw event log is saved to the host file eventLog.processor_number.wvr. You can change this name with the rtmon-client -f flag; note that if you do not specify the .wvr suffix, rtmon-client adds this suffix to the file. To stop rtmon-client, press <Ctrl-C>.
You can now import this raw event log into the WindView GUI with the “Analyze” command in the File menu, later saving it as a processed event log with the “Save” command if you wish; see “Event Buffer Overflow Information”.
Additional options to rtmon-client allow you to specify the number of seconds to run ( -t sec), to monitor other processors ( -p n) or hosts ( -h name), and turn debugging on or off ( -d 0|1). For a complete description of rtmon-client and its options, refer to the reference page rtmon-client(1).
To import the raw event log into the WindView GUI, choose the “Analyze” command from the File menu. The Analyze Event Log window, similar to the one shown in Figure 2-8, displays.
The current working directory is displayed in the Filter and Selection fields by default. Type the appropriate directory name and filename.wvr into the Selection field, then click the OK button or press the <Return> key to open the file and remove the Analyze Event Log window from the screen. If the file that you wish to import is listed in the Files subwindow, you can double-click on the name to import it. (For details on working with this window, see “Analyze Command”.)
Note that raw event logs have the .wvr suffix; if you attempt to open a processed event log with the .wv suffix, an error message appears.
If the raw event log is successfully opened, a message like the following appears in the Main window message area:
Processor 1: CPU: R4400 BSP: Silicon Graphics |
Then, if the View Graph is displayed, the event log is displayed there; see “Displaying a View Graph” for information. (Note that you can display the View Graph either before or after you have opened a raw event log.)
The “Analyze All” command is similar to the “Analyze” command, described above, but is used to open a trace that displays multiple processors. When invoked, it displays the Analyze All Event Log window, similar to Figure 2-8, which lets you import a raw event log collected with the rtmon-client tool into WindView.
As an example, to create traces for multiple processors, in this example, processors 1 through 3, and save them to the file, mp_test, type:
/usr/react/bin/rtmon_client -f mp_test -p 1-3 -t 10 |
This command collects data for 10 seconds ( -t 10) and then creates three files, mp_test.1.wvr, mp_test.2.wvr, and mp_test.3.wvr. (Note the syntax of the new filename is name.processor_number.wvr.) The filenames display in the Files pane (see Figure 2-8). Selecting the first name in the series (mp_test.1.wvr, for example) opens a trace that displays activity for all three processors. Additionally, each of the processor traces could be opened separately with the “Analyze” command.