$Id: README,v 1.17 2004/01/09 20:29:27 type2 Exp $

Prospect README file         0.9.8b          prospect-users@lists.sf.net
========================================================================


This readme file contains the following sections:
-------------------------------------------------

    * Welcome to Prospect for Linux
    * Common Ways to Use Prospect
    * Using Prospect to Generate a Kernel Profile
    * Some Final Hints


Welcome to Prospect for Linux
-----------------------------

Prospect for Linux is Open Source and under GPL version 2. 

    Copyright (C) 2001-2003 Hewlett-Packard Company

    This program is free software; you can redistribute it and/or modify
    it under the terms of the GNU General Public License as published by
    the Free Software Foundation; either version 2 of the License, or
    (at your option) any later version.

    This program is distributed in the hope that it will be useful,
    but WITHOUT ANY WARRANTY; without even the implied warranty of
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
    GNU General Public License for more details.

    You should have received a copy of the GNU General Public License
    along with this program; if not, write to the Free Software
    Foundation, Inc., 59 Temple Place, Suite 330, Boston, 
    MA 02111-1307 USA

The following web sites are the home of prospect and you will find source
code and updates there.

        http://prospect.sourceforge.net
        http://sourceforge.net/projects/prospect

If you received the binary distribution of prospect, then the distribution
file should contain the following files:

        AUTHORS            -   Credits.
        NEWS               -   Release notes for this release.
                               Please see this file for news.
        README             -   This file.
        README.ia64        -   IA64 (IPF) specific instructions.
        README.INSTALL     -   Installation instructions.
        DISCLAIMER         -   HP Disclaimer.
        COPYING            -   The GPL Version 2.
        prospect           -   The prospect executable
        prospect.1         -   The Prospect man page.
        oprofile-[version] -   The supported oprofile source
                               distribution.
        patches.readme     -   Readme file describing included patches.
        patches/*          -   A collection of patches that may or may
                               not be applicable to your situation,
                               please read the README files.

Please read the COPYING and DISCLAIMER file provided with this 
distribution before proceeding any further.  Thank you.

If you grabbed the Debian or RPM distribution, then the doc files
above and the supported oprofile source distribution are installed
into /usr/share/doc/prospect (Debian) or /usr/share/doc/prospect-X.X.X
(RPM).  The binary prospect is installed into /usr/bin and the man
page into /usr/share/man/man1.  The Debian installer (.deb) asks you if
you want prospect to be root suid, whilst the RPM installer just
installs it as root suid.  If this is an issue for you, then you will
have to remove the sticky bit after the install.  If you do not
understand that statement, then it does not matter for you.

The file README.INSTALL covers installation of prospect and the oprofile
module that it depends on.  Dependencies are covered there too.  The
README.ia64 file covers installation and operation on Itanium systems.

Note: You may have heard of a version of prospect available for HP-UX.
In fact, prospect was first developed on that platform in 1988.
The HP-UX version of prospect is not Open Source, however, the binary
distribution is freely available for HP-UX platforms from HP and can be
downloaded from:

        http://www.hp.com/go/prospect    
        ftp://ftp.cup.hp.com/dists/networking/tools/prospect/

Operation and output from the HPUX prospect is similar though not
identical to Linux prospect.


Common Ways to Use Prospect
---------------------------

Prospect is used to gather a statistical profile of all processes
running on a system as well as a profile of the system itself.  Prospect
does this by using the oprofile kernel module.  Prospect does this
without any intrusion or special build requirements.

Prospect is interstitial in nature.  This means that prospect will
collect data over an interval of time.  This interval is usually
specified by the application that one wants to profile on the command
line.  For example,

    $ prospect -o output  my_app

This command line specifies to collect profile information for the
immediate child of prospect (my_app here) and output the profile into a
file called "output".  The results in that file will be some information
about the run, a user-space profile for my_app and kernel-space profile
for work the kernel did on behalf of my_app.

There are two other major ways to use prospect: following forks and
system wide.  These are best explained with a couple of examples.  Note
that long options are used here, however, all of these have short option
equivalents (type prospect --help for a list).

    $ prospect --follow-forks --output output2  bash

    Outputs only the information of all descendant children.  In this
    example we run a shell to specify the interval and to control
    our benchmarks - when done, exiting the shell will cause prospect
    to end the sampling and generate the report.  This mode is also
    useful for processes that spawn a lot of children such as web
    servers and shell scripts, for example.

    $ prospect --system-wide --output output3  sleep 60

    This asks prospect to output information about all processes that
    ran during the interval to the output file named "output3." In
    this example, a time interval of 60 seconds is specified by the
    sleep 60 command.  When --system-wide is used, a consolidated
    kernel profile is also produced at the end of the output.

There are many more options that prospect supports for controlling its
execution and outputting data (including assembly-level profiling
activated by "-e".)  We encourage you to try these out and read up on
them in the prospect man page and from the --help option.

A couple of hints for manually scanning the prospect output file.

    Search for:
        "==--"   to find processes.
        "USER"   to find user profiles.
        "KERNEL" to find kernel profiles.
        "Skip"   to find things skipped in output.


Using prospect to Generate a Kernel Profile
--------------------------------------------

When you use prospect to generate profiles of user processes, you get
kernel profiles of kernel code executed on behalf of each user process
as part of the output.  Hits to kernel code executed during interrupt
context are associated with the process that was interrupted.

With the Kernel Profiling feature, all kernel hits including those in
interrupt context are summed into one consolidated kernel profile.  This
can make it easier to see kernel hot spots that might be obscured when
the kernel hits are spread out among the process profiles.

The Kernel Profile feature is activated by the "--kernel-only" or "-k"
command line option.  Additionally, a kernel profile is appended to the
user output when --system-wide is used.  The time interval to sample is
specified as before.  Thus, to sample the kernel for 120 seconds and
output the results to a file called "output", do:

    $ prospect --kernel-only -o output  sleep 120

If you want process profiles as well as the kernel profile, use the
system wide mode instead:

    $ prospect --system-wide -o output  sleep 120


Some Final Hints
----------------

Prospect help for standard options:
    prospect -h  (or --help)

Change sample frequency (default is 200, untested above 5000):
    prospect -H <Hz> ... command

If things go wrong when oprofile loads, check dmesg.

Thank you for your support.
========================================================================
