Man Page gcmonitor.1
NAME
gcmonitor - web interface to Sun WorkShop Memory Monitor
SYNOPSIS
gcmonitor [ -h ] [ -p port ] [ -v ] [ -m report-dir ] [ -r ]
DESCRIPTION
gcmonitor, the GC Monitor, is the web interface to Sun
WorkShop Memory Monitor. The GC monitor is actually a spe-
cialized web server. It interacts via monitor files with
programs linked with the Sun WorkShop Memory Monitor's
debugging libraries and serves a number of informative web
pages making up an interactive debugging interface. With
the interface, you can:
o debug a program's memory management from within a web
browser;
o debug programs remotely;
o sort, filter, and summarize leak information;
o sort, filter, and summarize allocation and heap statis-
tics, to see where and how a program is using memory;
o view the Sun WorkShop Memory Monitor log file;
o view the Sun WorkShop Memory Monitor documentation.
OPTIONS
-h Prints help on how to use the gcmonitor command.
-p port
Sets the TCP/IP port through which the GC Monitor
serves its interface. The default port is 2660.
-v Puts the GC Monitor into verbose mode, which outputs
information for use by technical support on the stan-
dard error stream.
-m report-dir
Sets the debugging report directory, in which the GC
Monitor looks for monitor files, to report-dir. The
default directory is /tmp.
-r Puts the GC Monitor in "read only" mode. Monitor files
will not be deleted.
TROUBLESHOOTING
Problem
My browser shows a GC Monitor error: File not found
."/htdocs/index.html".
Solution
Have you moved the file gcmonitor from the gcmonitor direc-
tory in the Sun WorkShop Memory Monitor distribution? The
monitor depends on a relative path to numerous HTML pages,
including the on-line manual, and it cannot operate
correctly unless that path is maintained. Put the executable
back in its default directory, and see if the problem goes
away. (See also BUGS.)
Problem
No web page is found at http://127.0.0.1:2660.
Solution
Check to see if you are pointing your browser at a proxy
server (to get around a firewall, for instance). Turning off
the proxy server setting on your browser should make local
browsing of the loopback address work properly. In most
browsers you can disable the proxy server for just the
address 127.0.0.1, localhost, or even localhost:2660. Here
are instructions for some specific browsers. If yours is
not listed, refer to the documentation that came with your
browser.
Netscape 3:
1. Go to the "Option" menu and select "Network Prefer-
ences".
2. Choose the "Proxies" tab and view the "Manual Proxy
Configuration".
3. In the "No proxies for" box, add localhost:2660
4. Click OK to exit.
Netscape 4 ("Communicator"):
1. In the "Edit" menu, choose "Preferences".
2. Double click "Advanced" in the category tree and select
"Proxies".
3. View the "Manual Proxy Configuration" selection.
4. In the "Exceptions" box, add: localhost:49213
Problem
Port 2660 is unreachable when I debug remotely.
Solution
Check that the GC Monitor is running on the remote machine
(the one running the program to be debugged, not the one
with the browser) and connect to http://remote-address:2660/
and not 127.0.0.1.
Your firewall may be configured to refuse the incoming con-
nection. Some administrators may set up firewalls in such a
way as to preclude remote debugging through our web inter-
face. Consult someone who is familiar with your local secu-
rity setup.
If a firewall precludes remote debugging then you can use
ftp or e-mail to transfer a compressed copy of the monitor
file to the local machine and view it by running gcmonitor
locally. This will only allow you to do post-mortem debug-
ging.
Problem
I want the GC Monitor to use a port other than 2660.
Solution
You can specify a new port number when you launch gcmonitor
by using the argument -p port. If you want the GC Monitor
to use port 12345, for example, the correct syntax would be
gcmonitor -p 12345.
Problem
The web page complains that my browser doesn't support
frames and/or Javascript.
Solution
You may not have enabled Javascript on your browser. The GC
Monitor requires both frames and Javascript in order to pro-
duce its debug monitor pages, and it should complain infor-
matively if it does not find them.
Problem
The web page says "Bad GCMonitor File" across the top.
Solution
o You may not have run any programs with the debugging
library linked to them.
o You may not have set the debugging report directory to
the same directory where your programs are writing moni-
tor files. You can change the directory where your pro-
grams are writing monitor files by using the environment
variable GC_MONDIR.
o You may have cleaned the monitor file you are hoping to
look at out of your report directory.
Click on the "Select Program" tab of the web interface, and
confirm that the directory is set to the location (by
default, /tmp) where the monitor files you are interested in
viewing are being or have been written.
Then check that directory (using ls *.mon for example) to
confirm that there really are monitor files in there.
(Note that you can still use the on-line manual through the
web interface, even if there are no monitor files currently
available to examine.)
Problem
Too many old copies of my application are visible in the
"Select Program" tab.
Solution
Are you clearing out the debugging report directory often
enough? In order to allow you to compare the debug output
from multiple runs of the same program, a unique monitor
file is written every time you run an executable with the
debugging library linked in. These monitor files are per-
manent records of your program's memory allocation behavior
during that particular run, and they can be kept long after
the program has exited. Since they can grow quite large,
disk space constraints may compel you to prune these files
from time to time; it may make sense to coordinate this
housekeeping with the regular scheduling of your tape back-
ups, if any. Only those files that correspond to currently
running instances of your program can be interacted with in
real time through the "User Settings" tab, of course: there
is no way to change the operation of Sun WorkShop Memory
Monitor retroactively on a defunct process!
Problem
The web page keeps asking me to accept cookies.
Solution
You probably have your browser set to warn you whenever it
is given a cookie. A cookie is a persistent bit of data that
a web server gives your browser, and expects back whenever
the browser connects to it again. This provides a powerful
mechanism for personalizing your browsing experience on a
given site, as the server otherwise has no way to know who
you are or what options you have previously set. Some people
are concerned about privacy issues when they browse the web,
and have configured their browser to provide feedback when-
ever a cookie is offered. GC Monitor offers cookies when you
change which program's debug log you are examining, when you
modify user variables, and in response to some other user
actions. It may make sense to temporarily disable cookie
warnings for the duration of a debug session, since only
your local GC Monitor (and not Sun Microsystems or anyone
else on the Internet) sees the cookies you return to it
while debugging.
Problem
I can't find a known leak under the "Allocation Profiler"
tab.
Solution
Have you sorted the allocation sites by leaked memory? If
you are only displaying the top few allocation sites, your
leak may not be among them in the ordering you have chosen.
ENVIRONMENT
GC_MONDIR
GC_MONDIR tells the program linked with the Sun
WorkShop Memory Monitor's debugging library (libgc_dbg)
the directory where the monitor files are stored. By
default, monitor files are stored in /tmp.
FILES
/tmp The default debugging report directory, to which moni-
tor files are written. See the -m option.
BUGS
The GC Monitor must be started in the gcmonitor directory in
the Sun WorkShop Memory Monitor distribution because it
depends on relative paths to numerous files, including the
on-line manual, and cannot operate correctly unless this
path is maintained.
SEE ALSO
gcInitialize(3), gcFixPrematureFrees(3), gcStopFixingPrema-
tureFrees(3).
Sun WorkShop Memory Monitor User's Manual