#
# Documentation for locktop. Written by Mark Goodwin (markgw@sgi.com)
#
# Copyright (c) 2000-2001 Silicon Graphics, Inc.  All Rights Reserved.
#

Locktop provides a "top locks" display for kernel locks, with the
ability to change the sort key at run-time. Locktop is a Performance
Co-Pilot client program, and hence can monitor remote hosts and
replay archives. This may help reduce performance intrusion on
lock tuning experiments.

== instructions for setting up to use locktop ==

0. patch your kernel with lock metering, rebuild and reboot. For
   details see http://oss.sgi.com/projects/lockmeter

1. use the lockstat program (../lockstat) to enable lock metering
   in the kernel (use "lockstat on").

2. install PCP. See http://oss.sgi.com/projects/pcp

3. configure and install the lockstat PMDA (see ../pmda_lockstat/README),

4. You can then run locktop. If you want to run it remotely (i.e. to
   monitor a remote server), use the -h option. Locktop works best
   with a big wide window.

== Instructions for creating PCP archives for use with locktop  ==

The "locktop_record" script is a simple script to capture a
PCP archive for replaying with locktop (or any other PCP monitoring
tools). Run the script and start your workload. When the workload
has finished, kill the pmlogger process (the script echos the
appropriate command and pid for this when you run it). You can then
replay the archive with "locktop -a myarchive", where myarchive is
the argument (name of the archive) supplied to the script.

== Questions ==

Send questions to Mark Goodwin (markgw@sgi.com) or the PCP mailing list
(pcp@oss.sgi.com)
