Ultra Pack/UltraComputing Technology Demos and Tools.iso/proctool/proc.help.txt

Text File | 1996-04-03 | 13.8 KB | 434 lines

proctool_info
ProCtool


ProCtool is a tool for monitoring and controlling processes on a system.
It is available on Solaris only.


Proctool is available in binary form for free.  It may also be freely
distributed within and outside of Sun Microsystems. It is not an official
Sun Microsystems product, and it carries no implied support or endorsement
from Sun Microsystems.  Please do not attempt to log proctool support
calls with the Sun Answer Center.


The authors, however, intend to support this product on their own time and
we encourage you to file bug reports, requests for enhancements and/or
comments with us at:


    [e-mail]   (Morgan Herrington)


and


    [e-mail]      (Walter Nielsen)


We will announce new versions of proctool outside of Sun on the newsgroup
"comp.unix.solaris", however, we will also maintain a separate "notification"
alias which we will use to inform interested users about new releases of
the tool.  If you would like to be added, just send a short email giving
us permission to add you (along with your preferred email address).


We intend to keep the latest version(s) of proctool (with documentation,
help and startup files) available to the general internet, via anonymous
ftp from:


    sunsite.unc.edu:/pub/sun-info/mde/proctool/proctool_X.Y.tar.Z


and available within Sun at:


    newstop.ebay:/sun/MDE/Performance/proctool/proctool_X.Y.tar.Z


(where X.Y is replaced by the appropriate Solaris version number).  Proctool
sometimes appears on other servers, however, these other locations are not
maintained by the authors.  If you would like to verify that the binaries
you download have not been tampered with, please contact the authors and
ask for checksums using "sum" or "md5" (whichever you prefer).


We have chosen not to release source for proctool.  We feel this reduces our
support burden and simplifies our relationship with Sun.  Please contact us
directly for any special situations.

FAQ:

---


Q: I applied some patches to my Solaris kernel, now ProCtool won't run.


A: ProCtool uses the uname() call to check with OS version is running on.
Some patches change the value uname() returns.  To override this, use the
-v option to ProCtool.   Note that ProCtool version 2.X runs only on Solaris
version 2.X.


Q: What does the following error message mean?


    Insufficient space for process information; use "-p MaxNumOfProcesses" option


A: Proctool currently initializes with some fixed sized tables, including
one to hold information for all active processes.  The defaults should be
large enough for *most* users, however, if you are running a large server
you can use the "-p" option to specify an upper bound on the number of
processes that you expect.  For example:


    proctool -p 1000


Q:  How do I change the default background color in Proctool ?


A:  Through your X defaults file.   The easiest way is to add an entry
in your $HOME/.Xdefaults file which looks like this:


proctool.*.background:   grey    # or some other color


Q: How do I change the default colors used in the various graphs ?


A: Currently ProCtool allocates only 8 colors for the graphs.  By
default, it would look like this in a X resource file.  To change it,
make the necessary modifications:


proctool.graph_color_1: green

proctool.graph_color_2: blue

proctool.graph_color_3: yellow

proctool.graph_color_4: red

proctool.graph_color_5: purple

proctool.graph_color_6: orange

proctool.graph_color_7: aquamarine

proctool.graph_color_8: magenta


Q: Do you support non-OpenWindow environments ?


A: Proctool is written using Motif under OpenWindows.  It requires the
Motif library libXm.so.3 under either /usr/dt/lib or /opt/SUNWmotif/lib.
ICCCM compliant and is known to work under olwm, olvwm, mwm, and oswm.
But the authors do have not the resources to test or support under other X
environments or window managers.



Q: How do I file a bug ?


A: Send a bug report to the authors with as much detail as possible.  In all
cases, we would need to know at least the architecture (Sparc/Intel), the
Solaris version, any kernel patches that have been applied, the number of CPUs.
When possible, please try to include a set of commands which reproduces
the problem.  Even more helpful would be a core file or a traceback from
dbx or adb.


Q: Can I get sources to ProCtool ?


A: We are not distributing sources to ProCtool.



*
proctool_win
ProCtool


ProCtool is a tool for monitoring and controlling processes on a system.
Most windows within Proctool has a help panel associated with it.  More
detailed help can be found in the User's manual.



The main window is split into three main panes, the Control Area, the Process
Area, and the System Area.  The Control area (on top) contains control and
status information for proctool.  The Process Area is a list of processes
similar to "ps(1)" output which are selectable with the mouse button.  (When
a process is selected, a window of detailed, process-specific
information is displayed.)  The System Area (on the bottom) contains system-wide
information along with with a per-CPU information line.  This area is also
mouse selectable to view in-depth system statistics.


The buttons on top of the main window control ProCtool in the following manner:


FILE       - Show the transcript file, turn on data logging, and save current
ProCtool state into a startup file.


VIEW       - Change the display characteristics of proctool.


COMMANDS   - Manipulate the state of the current processes.


GRAPH      - Graph system or process behavior.


PROPERTIES - Set properties for the tool, or display process or system properties.


*
log_win
Data Log Property Window


The Data Log Property Window allows the user to log the state of the
system and processes into a file for future analysis.  The file is
in ASCII format and written in a way that allows for easy text manipulation
via awk/sed/perl.


You can log system characteristics, a set of selected variables for up
to 8 processes, or some very detailed characteristics of one process.
Keep in mind, that certain operations such as Process Backtrace is very
time consuming so that a very low sampling periods should be avoided.
*
monitor_win
Monitor Window


A monitor is a user definable 'event' that triggers the execution of user
definable actions.


A monitor consists of an logical expression and a set of actions.  When
an active monitor is defined, it will apply the monitors expression
against the data.   For every process expression which evaluates to true,
the associated action is performed.  (Note that monitors are evaluated
in the same order as they are in the Monitor window.  This means that
the last active monitor will take precedence when conflicting visual
actions are specified.)


To create a monitor, enter an expression in the Expression input line
and a select a set of actions in Action pane.   All monitors must be
named and entered into the list of available monitors.  This is done
by selecting the INSERT button near the center of the window.


A monitor expression is a logical expression constructed from relational
operators, constants, and predefined variables.  The predefined variables
are the various fields from the process window along with some special
system wide variables.   Values may be integer, hexadecimal, floating point,
or string values.


When a monitor is active, its expression is applied against each process.  The
evaluation occurs when a new active monitor is defined  and every time
a new sample is taken.  (Only those monitors which are active will be evaluated;
active monitors are shown with a leading asterisk.)


Monitors can generate a number of predefined or user defined actions.  Two
of the simplest are the "Visual" and "Hide" actions which cause the entry
for a process to change color or disappear, respectively.  The "Beep" action
generates an audible bell when the monitor is triggered.  The "Popup"
action will cause a popup window to appear which will show the process
id's of the first ten processes that triggered the monitor.  (The remaining
processes can be seen in the transcript.)


A more complicated action is "Mail" which sends mail when the monitor
expression evaluates true.  By default, the mail is sent to the person
running proctool with a short message stating the command, process id
and monitor expression which generated the action.  You also have the
ability, via the "Edit Mail Template" button to customize the standard
template.  See "Help" under the "Compose Mail" window for more information.


The most general action is "Command" which invokes an arbitrary shell
command, after expanding predefined variables like $USER, $CMD, and $PID
to their actual values from the process which triggered the monitor.


NOTE:  The current version of proctool will hang until the generated
command is completed.


Monitors by default trigger for an indefinite period of time once they
are activated.   This "Monitor State" toggle allows the user to change
that behavior.  Selecting ONCE implies that the monitor will trigger
exactly once and then deactivate itself.


*
tool_prop_win
Tool Properties


This property window allows the user to set properties associated with
ProCtool.


Auto Update toggles whether the process window will automatically
be updated after a Proctool-invoked command.  If this feature is turned
on, the process window is updated after say a "Kill process" command.
This has the affect of keeping the process window in sync with the state
of the processes when issuing a lot of commands.


You may also select whether the transcript file will be appended to
an existing transcript or will instead overwrite an existing file on
startup (via "Transcript Mode).


The name of the transcript filename may be changed.  The change takes
place immediately.  In order for this change to take affect on the
next invocation of Proctool, you will need to save the current state.
*
sort_win
Sort Window


This window allows the user to specify what fields to use to sort the
processes visible in the process window.   To specify a sort, select one
or more variables (fields) to be used as sort keys.   Multiple key sorts
are allowed with up to 20 keys.


By default, ProCtool sorts in ascending order.  To sort in descending
order, select "Sort Descending" before selecting the sort key.  Descending
sort keys are denoted with a leading '~' character.


*
viewpoint_win
Viewpoint Window


This window allows the user to select which process fields are to be
displayed in the process window.   To create a viewpoint, select
a set of variables and "Apply" them.


Viewpoints can be saved for later selection by assigning a name under
"Viewpoint Name" and inserting it into the viewpoint database.  You
may later re-select this viewpoint and "Apply" it.


*
mail_win
Compose Mail


This window allows you to customize a mail message to be sent by proctool
when a monitor is triggered.  All predefined variables, like $USER,
$CMD, $PID, $RSS, $CPU, etc will be expanded to the actual values from the
process which triggered the monitor.


To customize the mail message, just edit the "Compose Mail" popup window.  The
edited template now becomes associated with the action for this
particular monitor.  All other unedited monitor mail templates are not
affected.


*
priocntl_win
Process Control Window


This window controls process binding and priority.


The first menu, "Bind to Processor #" allows you to select a set of
processes (via the selection mechanism in the main display) and
bind them to a particular processor (or alternatively, to unbind them).  Note
that this does not inhibit other processes from migrating to
this processor, however, it does keep the selected processes from
migrating away.


The second menu, "Change Priority To" allows you to control the scheduling
class (and parameters) of one or more processes.  Under the "Time-Share"
selection, you can set the Time-Sharing Priority and Priority Limit.  Under
"Real-Time", you can set the Real-Time Priority, Time Quanta, and
Time Resolution.


Users without root privileges may change the priority of only their processes.

*
signal_win
Signal Command Window


This command window allows the user to send a selected signal to all
processes selected in the main ProCtool process window.   The user must
be running in privileged mode in order to send a signal to a process
running under an effective user ID other than their own.


*
cpucntl_win
Processor Command Window


This window allows you to disable or enable particular processors.  Note that
you are not allowed to disable ALL processors simultaneously, and you must
have "root" privileges to successfully execute this operation.
*
process_win
Process Detail Window

This window allows you to look a some very detailed information about a
process.  The information provided here is not shown in the main process
window since it is typically very expensive to do for all the processes.
Unless you have "root" privileges, you cannot use this window
on another user's process.


Turning on the Auto-Update mode make this window refresh its data at
the same sampling period as the main process window.   The Update Once
button does this as a one-shot event.


For multi-threaded programs, the LWP window lets you select which
LWP you want look at.  The LWP selection is turned on only for
the Traceback, Resources, and I/O selections.  The other selections
apply to the process as a whole, and not to any individual LWP.
*
system_win
System Detail Window


This window gives some detailed information regarding the system as a whole.


Turning on the Auto-Update mode make this window refresh its data at
the same sampling period as the main process window.   The Update Once
button does this as a one-shot event.


The Hardware Configuration window is not very interesting right now
but expect that to be enhanced in some future release.  Also, unfortunately
the I/O statistics are not synchronized with the I/O graphs right now.
That will be fixed in some future release as well.
*