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