═══ 1. Notices ═══ Pegasus Resource Monitor Pegasus Tools Version 1.0 Release 010 (c) 1993,1994 C.O.L. Systems Inc. All Rights Reserved C.O.L. Systems Inc. has been in the business of software development and consulting since 1987. Our software has, and will continue to be, geared towards performance and capacity management needs. From the standalone OS/2 station tools (Pegasus Resource Monitor and Pegasus Tools) to heterogenous performance and capacity management (Osrm2*), we continue to meet the users needs in sophisticated, low price, software. *Osrm2 (c) 1991,1994 C.O.L. Systems Inc. Contact and Support We have moved to a new location with new phones as well: Mailing Address: C.O.L. Systems Inc. 10 Watergate Drive Amawalk, NY. 10501 Telephone Numbers for: Voice - (914) 245-0442 FAX - (914) 245-0452 BBS - (914) 245-1561 Other Notices OS/2 is copyright by IBM Corporation. ═══ 2. License and Warranty ═══ License Agreement and Warranty Disclaimer You should carefully read the following terms and conditions before using this software. Use of this software indicates your acceptance of these terms and conditions. If you do not agree with them, do not use the software. Shareware Version You are hereby licensed to: use the Shareware Version of the software for a 21 day evaluation period; make as many copies of the Shareware version of this software and documentation as you wish; give exact copies of the original Shareware version to anyone; and distribute the Shareware version of the software and documentation in its unmodified form via electronic means. There is no charge for any of the above. You are specifically prohibited from charging, or requesting donations, for any such copies, however made; and from distributing the software and/or documentation with other products (commercial or otherwise) without prior written permission from C.O.L. Systems Inc. Unregistered use of Pegasus after the 21-day evaluation period is in violation of federal copyright laws. Evaluation and Registration This is not free software. This license allows you to use this software for evaluation purposes without charge for a period of 21 days. If you use this software after the 21 day evaluation period a registration fee is required as described in Registration Forms. Quantity discounts are available, see the apporirate order form for details. One registered copy of Pegasus may be dedicated to a single person who uses the software on one or more computers or to a single workstation used by multiple people. You may access the registered version of Pegasus through a network, provided that you have obtained individual license for the software covering all workstations that will access the software through the network. Governing Law This agreement shall be governed by the laws of the State of New York. Disclaimer of Warranty This software and the accompanying files are sold "as is" and without warranties as to performance of merchantability or any other warranties whether expressed or implied. Because of the various hardware and software environments into which this program may be put, no warranty of fitness for a particular purpose is offered. Good data processing procedure dictates that any program be thoroughly tested with non-critical data before relying on it. The user must assume the entire risk of using the program. Any liability of the seller will be limited exclusively to product replacement or refund of purchase price. ═══ 3. Registration Forms ═══ Registering Pegasus C.O.L. Systems Inc. will accept MasterCard, or Visa Credit Cards. C.O.L. Systems Inc. will accept checks or Money Orders in US funds only. After printing the appropriate form, mail it in with your payment ( or fax it if registering by Credit Card ). o For General Registration, print and fill in the information and fax or mail the REGISTER.DOC file. C.O.L. Systems Inc. maintains a Pegasus message and file area for registered users on it's BBS @(914) 245-1561. o For Os/2 Shareware BBS users, print, fill in the information and fax or mail the OS2SHARE.DOC file. C.O.L. Systems Inc. maintains a Pegasus file area for registered users. Once we receive registration we will notify you via Os/2 Shareware private e-mail with the password to this file area. o For Pyramid/2 BBS users, print, fill in the information and fax or mail the REGISTER.DOC file. C.O.L. Systems Inc. maintains a Pegasus file and message area for registered users. Once we have received registration we will have the Pyrmaid/2 sysop update your security level to proivde access to these areas. ═══ 4. APAR Notices ═══ The following are APARS and associated fixes that may be required to run the Pegasus Resource Monitor. These fixes are available from the IBM Corporation. The following APARs apply to OS/2 2.0 plus Service Pak 1. o PJ06434 - Disk Device Driver The fix concerns a problem where disk timers were getting corrupted. The following APARs apply to either OS/2 2.0 plus Service Pak 2 or OS/2 2.1. o PJ08459 - Occasional negative values for Process Page Fault Time. Page Fault time is a metric which measures how much time a thread has spent waiting on a page fault. This metric is part of the thread resource group. On a heavily loaded machine, this timer can go negative briefly. o PJ09410 - Trap E when collecting thread data on a busy system. On a heavily loaded managed system with excessive thread activity, there is a potential for a TRAP E to occur while collecting application/process/thread level data. To avoid this trap, obtain the selective fix for APAR PJ09410. o PJ09893 - Trap D on dirty HPFS disk. If you have HPFS installed, you may experience a trap D in OS2KRNL while collecting data. The trap occurs if chkdsk was run during config.sys time. If you experience this problem, obtain the selective fix for APAR PJ09893. o PJ10475 - A variety of traps in OS2KRNL During data collection on a heavily loaded machine. APAR PJ10475 fixes these traps. o APAR PJ10476 and PJ10275. If you start and stop data collection more than 140 times without rebooting, OS/2 stops returning data. To avoid this symptom, obtain the selective fix for APAR PJ10275 or PJ010476. ═══ 5. What is Pegasus? ═══ Pegasus ( The Greek Myth ) A winged horse that with a stroke of his hoof caused the fountain Hippocrene to spring forth from Mount Helicon. Pegasus Resource Monitor ( The OS/2 Product ) A 32 bit application that with a click of a mouse causes a fountain of performance statistics to spring forth from Mount OS/2 2.x! The Pegasus Resource Monitor is a kernel level, real-time, Presentation Manager monitoring tool for system and application resource usage under OS/2 2.x. Including a configurable sample rate, thresholds settings, exception notification and logging, working set analysis, kill process options, as well as graphical indicators, the Pegasus Resource Monitor provides the most comprehensive monitoring tool for OS/2. ═══ 6. The Interface ═══ Most of the control for Pegasus can be found in the main window. From here, you can select different display and configuration options. The following shows the main window with the System Activity view being selected. Accessing the Displays There are a number of views and a graph display that can be opened at the same time. Click or press enter with one of the following to learn more about Pegasus Views: o System Activity o I/O Activity o Application Activity o Per Process Memory o Mini-Monitor Configuring the system You can change most of the behaviour of the Pegasus resource monitor by selecting Options->Configuration from the main menu actions. More information about configuring the system can be found in Configuring Pegasus. ═══ 6.1. System Activity View ═══ The System Activity View displays general system resources in a detail container format as shown in the following example. Fields are described below this picture. To start the system view select Views->System Activity from the main menu. Depending on the refresh rate, as set in the configuration, the system view will begin updating in 5 seconds, 1 minute, or 15 minutes. The system view consists of five (5) rows of information. There are a number of columns that pertain to each of the five rows, and some of these columns are overlapped, as will be described: o Cpu This row has two (2) fields: 1. Busy - The percentage of the sample interval that the system was performing work. 39% busy in the example 2. Count - The task dispatch count during the measured interval. 405 times in the example. o Irq This row has two (2) fields: 1. Busy - The percentage of the sample interval that the system was busy servicing interrupts. 9% busy in the example 2. Count - The interrupt dispatch count during the measured interval. 1,670 times in the example. o Page In This row has three (3) fields: 1. Count - The number of pages that were swapped in from disk in the sample interval. 0 in this example. 2. Fault - The number of page faults that occured in the sample interval. 268 in this example. 3. Demand - The number of pages demand loaded from disk during sample interval. 136 in this example. o Page Out This row has three (3) fields: 1. Count - The number of pages that were swapped out to disk in the sample interval. 0 in this example. 2. Discards - The number of pages that were discarded during the sample interval. 0 in this example. 3. Reclaims - The number of pages that were reclaimed for use during the sample interval 28 in this example. o Memory This row has five (5) fields: 1. Resident - The number of pages in memory that are in the non-swappable/non-discardable arena. 753 in this example. 2. Free - The number of pages in physical memory that are available for use. 859 in this example. 3. Used - The number of pages, in physical memory, that are in use. 3,122 in this example. 4. Idled - The number of pages, in physical memory, that are marked idle. 32 in this example. 5. Reassigned - The number of idled pages that were reassigned for use by another process. 351 in this example. ═══ 6.2. I/O Activity View ═══ The I/O Activity View displays I/O event measurements in a detail container format as shown in the following example. Fields are described below this picture. To start the I/O view select Views->I/O Activity from the main menu. Depending on the refresh rate, as set in the configuration, the I/O view will begin updating in 5 seconds, 1 minute, or 15 minutes. The I/O view displays each of the I/O devices found on the system. These can consist of: o Floppy disk drives o Local Disk Partitions (FAT or HPFS) o Com Ports o Printer Ports For each of the devices listed above, the following fields are maintained: o Read Activity 1. Read Events - The number of read I/O events for this device in the sample interval. 2. Read Response Average - The average read response time for this device. 3. Average Bytes Per Read Event - The average number of bytes read per read event. o Write Activity 1. Write Events - The number of write I/O events for this device in the sample interval. 2. Write Response Time Average - The average write response time for this device. 3. Average Bytes Per Write Event - The average number of bytes read per read event. Note: Printer devices will not report read activty. In addition to these measurements, local disk partition storage is displayed for 1 and 15 minute sample rates. These measurements include: o Storage 1. Used - The number of megabytes on the partition that are allocated. 2. Avail - The number of megabytes on the partition that are still available. ═══ 6.3. Application Activity View ═══ The Application Activity View displays summary information for each process on the system in a detail container format as shown in the following example. Fields are described below this picture. To start the Application view select Views->Application Activity from the main menu. Depending on the refresh rate, as set in the configuration, the Application view will begin updating in 1 to 60 minutes. In addition to the display description, you can learn how to Sort the display and how to Run a Working Set Analysis or Kill runaway or background processes. The Application view displays each process found in the system. For each process the following fields are maintained: o General Information 1. Process Name - This is the name of the process module. Similar to the results of running PSTAT, but without the fully qualified path. 2. Process ID - This is the process id number assigned to the process by the system. o Activity Information 1. Threads - This is the total number of threads found in the process during the sample interval. 2. CPU Utilization - This is the percent system utilization by this process during the sample interval. 3. Dispatch Counts - This is the total number of times the process was dispatched during the sample interval. 4. Page Faults - This is the total number of page faults for the process during the sample interval. 5. Page Fault Wait Time - This is the amount of time the process spent waiting for a memory page fault to be resolved. 6. File I/O Wait Time - This is the amount of time the process spent waiting for a file I/O event to complete. o I/O Activity 1. Reads - This is the total number of file read I/O events during the sample interval. 2. Writes - This is the total number of file write I/O events during the sample interval. ═══ 6.3.1. Sort Options ═══ The Application activity screen provides a number of sort options as shown below. To activate the sort menu, click anywhere within the Application activity client area with the right mouse button (RMB). The following sort options are available: o Process Id o Process Name o Cpu Utilization o Dispatch Count o Thread Count ═══ 6.3.2. Run a Working Set Analysis ═══ Note: This option requires that the IBM Theseus/2 version 2.0v is installed on the machine. Although this package has been found on many OS/2 BBS, it is really part of a commercial product. C.O.L. Systems Inc. has aquired the rights to sell the Theseus/2 2.0v library component for an additional $75.00. If you would like to order a copy of the IBM Theseus/2 library, contact C.O.L. Systems Inc. at (914) 245-0442. By double clicking on an active process, and selecting the Working Set Analysis popup menu option, you can generate a report on how much memory an application uses over time. An applications working set is those pages of memory that the application references (reads or writes) over a period of time. The following example shows the Workplace Shell component being monitored. A description follows the picture. Working Set Interval You must set how many timer tic intervals are used to determine the working set. For example, if you selected 3 then at every Sample time the application will be checked for memory referenced over the past 3 timer tics. Even though the range is from 3 - 45, setting this value low will potentially mask out the dynamic memory reference for the process. Sample Rate This value controls how often the working set analyzer is called to calculate new values and display them on the screen. Valid range is from 3 to 50 seconds. The Display As the working set analysis runs, the display is updated with the following information: o Date-Time - The date and time stamp for the sample. The most recent sample is placed at the top. o Now(k) - How much memory was referenced in the current interval. o WS(k) - How much memory was referenced in the past Working Set Interval. o Accessed(k) - How much memory has been referenced since the analysis was started. Note: 1 k = 1024 bytes of memory Button Controls There are a number of buttons to use with the Working Set Analysis: o Start - Once you have configured the Interval and Sample rates, click this button to begin the analysis. o Stop - To stop the analysis at anytime, select this button. Also, closing the analysis window will stop the sampleing as well but you won't be able to save the report. o Save... - Once you have Stopped the sampling, you can save the report to an ascii disk file. When clicked, a file dialog will appear. Note: This button is only active once you have accumulated samples. ═══ 6.3.3. Kill Application Function ═══ By double clicking on an active process, and selecting the Kill Process popup menu option, you can attempt to kill that process. This may or may not work as described in the note at the end of this page. Killing a process is not the ideal way to shut it down. If possible, you should use the applications close function. On the otherhand, the kill function is ideal for background processes that don't have a keyboard or mouse interface. A message box will appear to confirm the request and will display the process name that you selected. Note: As mentioned, killing a process may not work if the process has registered a signal handler. The process may choose to ignore this signal. ═══ 6.4. Per Process Memory ═══ Pegasus now provides a function for displaying the private and shared memory allocated per process. Note: This option requires that the IBM Theseus/2 version 2.0v is installed on the machine. Although this package has been found on many OS/2 BBS, it is really part of a commercial product. C.O.L. Systems Inc. has aquired the rights to sell the Theseus/2 2.0v library component for an additional $75.00. If you would like to order a copy of the IBM Theseus/2 library, contact C.O.L. Systems Inc. at (914) 245-0442. The Display Once the Per Process memory option runs, the display is updated with the following information: o Process Name - The names of each process found in the system. o PID - The process id (PID) which is related to the process. o Private(k) - How much memory is allocated from the private memory pool by each process. o Shared(k) - How much memory is allocated from the shared memory pool by each process. Note: 1 k = 1024 bytes of memory Button Controls o Save... - You can save the report to an ascii disk file. When this button is clicked a file save dialog will appear. ═══ 6.5. The Mini-Monitor ═══ The Mini-Monitor Graph displays key system resources as bars in a graph window as shown in the following example. Fields are described below this picture. The Mini-Monitor resides in it's own window on the desktop. It is common to have the Mini-Monitor running and placed in a corner of the desktop, while the Pegasus main window is iconized. If some measure of activity displayed in the Mini-Monitor are of concern, then you just click on the Pegasus icon to restore it and view detailed measurement information. There is less overhead in running this way as well! To start the Mini-Monitor graph select View->Mini-Monitor from the main menu bar. The refresh rate for the Mini-Monitor is the same as for the system record refresh. The Mini-Monitor consists of three (3) key resources: 1. CPU - This is a bar graph of system utilization as measured during the sample interval. By default this bar will be BLUE. If the CPU utilization is equal to or exceeds a user configured threshold, then this bar will be RED. Next to the CPU legend is a numeric indication of the percent CPU busy, where 0.10 = ten percent, etc. 2. RAM - This is a multi-informational bar. This first indicator is colored GREEN, this portion of the bar represents the percent of total physical memory that is marked as resident.Resident storage is non-swappable and non-discardable. The second portion of the bar represents the percent of total physical memory that is in use. By default this bar will be BLUE, unless a threshold has been met or exceeded in which case it will be RED. Next to the RAM legend is a numeric indication of the percent RAM in use, where 0.10 = ten percent, etc. 3. SWP - Like the RAM bar, this is multi-informational. The first indicator represents the percent of calculated swap storage that was pre-allocated at boot time. This is based on the size defined in your config.sys file. The second portion of the bar represents the percent of calculated swap storage that is currently in use by swapper.dat Next to the SWP legend is a numeric indication of the percent of calculated disk storage is used by swapper.dat, where 0.10 = ten percent, etc. Note: Calculated space is defined as the current swap file size plus the available space on the partition where the swap file resides. As mentioned, each of the Mini-Monitor resources can show when a threshold is met or exceeded. The thresholds are defined in the Configuration Dialog When a bar turns RED, indicating a threshold exception has occured, the information is recorded to an in-memory exception log. This log can be viewed by double clicking the Mini-Monitor window with the right mouse button (RMB). See The Exception Log for more information on this dialog. ═══ 6.5.1. The Exception Log ═══ The Exception Log Dialog maintains a list of exceptions that met or passed the threshold as set in the Options->Configuration panel. An example log is shown and the entries are described below this picture. As new exceptions occur, they are added to the top of the list (most recent first). Each entry consists of the folowing form: At hh:mm:ss : RESOURCE Measured XX Threshold YY where: o hh:mm:ss is the time stamp that the exception was received. o RESOURCE is the resource for which this exception occured. It can be any one of: - CPU - RAM - SWP o XX is the resources actual measured value. o YY is the threshold as set in the configuration options. ═══ 6.6. Configuring Pegasus ═══ There are a number configuration options available from the Options->Configuration menu item. Most of the options go into effect as soon as the Save button is clicked, others take effect when Pegasus is restarted. The Configuration Panel has a display of what the option controls look like. ═══ 6.6.1. The Configuration Panel ═══ The following is an example of the Pegasus Configuration Options dialog window. Descriptions for each of the settings can be found after the picture. Detailed descriptions can be found in: Window Actions Refresh Rates Threshold Levels Control Buttons ═══ 6.6.2. Setting Automatic Window Actions ═══ There are two (2) types of window actions that can be configured: 1. Save Window Positions - This option, when set, will record all the open Pegasus Views and Mini-Monitor graph position and size information. 2. Auto Start - These options control which windows should be automatically opened when Pegasus is loaded. ═══ 6.6.3. Setting Sample Refresh Rates ═══ There are two (2) sample rates that can be configured in Pegasus: 1. System Refresh - This identifies the rate at which samples are taken for the System Activity, I/O Activity, and the Mini-Monitor. Valid settings for this value are 5 second, 1 minute, and 15 minute intervals. 2. Application Refresh - This identifies the rate at which samples are taked for the Application Activity View. ═══ 6.6.4. Setting Threshold Levels ═══ There are three (3) threshold percentages that can be set: 1. Cpu Busy Warning - This indicates the percent CPU busy that should generate an exception if met or exceeded. 2. Ram Used Warning - This indicates the percent of physical memory, when used, that should generate an exeption. 3. Swap Used Warning - This indicates the percentage of calculated swap space, when used by swapper.dat, that should generate an exception. ═══ 6.6.5. Control Buttons ═══ The control button on the bottom of the configuration dialog will: o Save - Any changes you have made in the dialog. o Reset - Reset the dialog to the settings before any changes made. o Help - Display the general help window for the dialog. In addition, context sensitive help is available for any of the configuration controls by pressing the F1 key when the control in question has the focus. You can also Cancel the dialog by double clicking on the system menu for the configuration dialog. ═══ 7. History Of Changes ═══ Version 1 Release 10 1. Dramatic reduction in overhead used by Pegasus. This is primarily the benefit of changing from a floating point collection engine to an integer engine. Over 90% improvement on non-x87 machines. 2. Changes to handling of non-OS/2 processes in application activity view. Checking is now performed for PMSHELL validation or VDM. 3. Addition of Per Process memory usage display and report. This feature requires the IBM Theseus/2 installed. 4. Added configuration option for displaying process ids (PIDs) in hex or decimal. Version 1 Release 9 1. If detect IBM Theseus/2 installed will allow working set analysis on a running process. See Run a Working Set Analysis for more information. 2. Changed double click action in Application Activity. Now pops up menu of choices (Working Set Analysis, Kill Process). 3. Added Exception Log save option. 4. Updated on-line help and documentation. Version 1 Release 8 A Refresh of PEGASUS.EXE only. 1. Modified Pegasus.Exe to track DOS and/or Window apps by their right name in the Application Activity View. Version 1 Release 8 1. Added text indicators next to Mini-Monitor graph bars. 2. Extended discount program to Os/2 Shareware BBS 3. Provided ability to register by Credit Card. Version 1 Release 7 1. New collection engine. 2. New documentation in OS/2 INF format. 3. Change to the configuration dialog provides more intuitive save and cancel procedures. 4. Loss of IO events corrected. 5. Abend when opening I/O Monitor window with certain CD-ROM or re-directed drive configurations corrected. 6. Abend when opening Exception Log Dialog corrected. Version 1 Release 5 1. Mini-Monitor Exception Log 2. Modified on-line help. Version 1 Release 4.B 1. Application Kill Process option added to Application View. 2. Added SWAP SPACE measurements to the Mini-Monitor. 3. Modified configuration options. Version 1 Release 4.0 1. Application screen sort options. 2. Added the resident memory (NONSWAP/NONDISCARD) percent to the Ram bar in the Mini-Monitor. 3. Modified on-line help. Version 1 Release 3.0R 1. Autosave and restore of last known window positions. 2. Mini-Monitor Added. 3. Enhanced configuration options. 4. Improved on=line help system. Version 1 Release 3.0 1. Removal of two (2) dynamic link library and one (1) executable as we have integrated the main collection code into the Pegasus executable. 2. Corrected random traps in the OS2DCF.EXE. ═══ 8. Frequently Asked Question (FAQ) ═══ This section provides answers to many of the questions often asked about the Pegasus Resource Monitor. We have organized the questions into relative sections and made reference to supporting areas of the Pegasus Resource Monitor when applicable. The following sections can be linked to from here: o FAQ about Memory o FAQ About I/O o FAQ About Application Activity ═══ 8.1. FAQ about Memory ═══ This section answers questions about system memory. Q: What is a page? A: A page is a fixed length block of storage that is transfered as a unit between physical memory and disk. In OS/2 2.x, a page is 4096 bytes in size. Q: What is a page event? A: A page event is when the memory management of OS/2 either writes the contents of a memory page to the swapper.dat file to make room for other process memory requirements, or when a process references a page (page fault) that is not longer in memory and it must be paged, or read, back in. Typically only data, not executable, memory is paged out. As OS/2 prohibits executable pages from being modified, the system can re-read the contents of a discarded code page back in from the EXE file. Note: Page In and Page Out events can be monitored in the System Activity View of Pegasus. Q: What is a page fault? A: A page fault is an exception that occurs when a process references a page of memory that is not present. This can be due to one of the following: 1. The original contents of that page of memory had been swapped out to make room for other processes memory. In this case, the memory manager swaps the page back in. 2. The original contents of that page have been discarded. Note: The number of Page faults for the system can be monitored in the System Activity View, and page faults per process can be monitored in the Application Activity View of Pegasus. Q: What is a resident page? A: A resident page of memory is a page that is never paged out or discarded. For the most part, this area of memory remains fixed. Typically this area contains operating system allocated areas, device driver allocated areas, cache buffers, etc.. Note: Resident pages are monitored in either the System Activity View or Mini-Monitor of Pegasus. Q: What is a reclaimed event? A: Pages of memory become candidates for a page out event based on the frequency of use. Before a page is physically paged out it is placed in the idle page queue. If a process references that page, and it is not yet paged out, it is reclaimed from the idle list. Note: Page reclaims can be monitored on the Page Out row of the System Activity View in Pegasus. Q:Right after bootup I show a large portion of memory as being used, but I don't have much running. A: When the operating system first loads, it uses as much memory as it needs. Much of this memory is taken up by parts of the operating system that are pageable or discardable. As soon as you start running other processes the oldest non-referenced pages are the first to be swapped or discarded. ═══ 8.2. FAQ About I/O ═══ This section answers questions about I/O. Q:The disk storage indicators on the I/O Monitor window are not updating, why? A: Disk storage is scanned once a minute, you probably have your system refresh set at 5 seconds. Q:I never see my COM devices update even though I run many communications programs A:Check your config.sys. If you are running SIO versus the IBM supplied com drivers you will not see I/O for com ports as the SIO driver does not contain the performance hooks neccessary to track activity. Q:What format are the response fields in? A: These fields are response time average in milleseconds. Q:What format are the byte fields in? A: These fields are bytes per I/O average. Q:What format is the disk storage fields? A: These fields are used and available storage in megabytes. ═══ 8.3. FAQ About Application Activity ═══ This section answers question about Application Activity. Q:Sometimes the application thread count goes to zero (0) and on the next refresh it disappears. A: This occurs when we detect that an application has ended. We felt that rather than remove it as soon as it ends, we would leave it displayed so that the last measurements before process end could be viewed. Q:There are two (2) entries for PMSHELL in my application display, is this right? A: Yes! The first entry, or lowest process id if you are sorting differently, is the actual PM Shell, the second is the Workplace Shell.