Previous PageTable Of ContentsNext Page


The GC Monitor Web Pages


The GC Monitor Web Pages

The GC monitor is actually a specialized web server running on your computer. It serves a number of informative web pages to the debugging URL, making up Sun WorkShop Memory Monitor's interactive debugging interface. By clicking on the tabs at the left of the screen, you can explore the debug information Sun WorkShop Memory Monitor has logged about your program.

The Select Program screen

The top tab, "Select Program", brings up a list of all programs that are currently running or have recently been run in debugging mode. Each time you run a program linked to the libgc_dbg library, a unique Monitor file is generated and saved to your temporary directory (or in whatever directory you may have specified in the field in the upper frame). By default Sun WorkShop Memory Monitor saves only the last four Monitor files, but you can reset that number from this page.

To select a program run for examination, click on its hyperlink in the list. This will take you to the "Leak Information" screen for that run, which is described below.

The Leak Information Screen

After you have selected a program, the blue frame at the top will indicate which program you are monitoring and the total amount of leaked memory Sun WorkShop Memory Monitor has recovered in the course of this run. If you are monitoring a live program, this number will be updated whenever you update the display or change tabs.

The "Leak Information" screen is the usual starting point for memory debugging. All the objects which your program has leaked in the current run are listed here, with the most serious leaks listed first. Multiple occurrences of the same leak are listed as a single item (that is, multiple objects that were allocated through identical execution paths, as defined by stack trace, and subsequently leaked). Also listed are the total number and size of all allocations through that path, along with the number and size of leaked allocations. A full stack trace is given for each identified leak site, with file and line number listings if your program was compiled with the necessary debug information. (If not, the module name and program counter can still be useful for disassembly.)

You can change which leaks are shown and how they are sorted from the button panel in the upper frame. You can also filter the listings using a regular expression. Use the "Refresh" button to redisplay leak data (either because you've changed the parameters, or because time has passed and you'd like to see the most recent information). If you want to force Sun WorkShop Memory Monitor to do a garbage collection, click the "Collect Now" button." Of course, this only works if your program is still running; for obvious reasons this won't work if you are looking at an old run.

The Allocation Profiler Screen

Not all memory debugging concerns involve leaked objects. For example, an ever-growing linked list is not a memory leak in the technical sense: you still have a valid pointer chain to every element of the list, and so no garbage collector has a right to reclaim it out from under you. Nonetheless, if you have such an object, and its growth is unintentional and represents an obstacle to your program's ability to run continuously and stably for long periods, it is important that you be able to track it down. By providing a real-time profiler of all actual allocations within your heap, Sun WorkShop Memory Monitor can help you with this sort of debugging. With Sun WorkShop Memory Monitor's allocator and the GC Monitor, your heap is no longer a black box!

The Allocation Profiler tab shows the stack trace for every site at which your program allocates memory. For each site, "Live Memory" indicates how much memory is currently being used, which tells you what data structures are consuming the most memory at any given moment. "Allocated Memory" indicates how much memory (live, freed, or leaked and recovered by Sun WorkShop Memory Monitor) has been allocated at that site over the life of the program, telling you where the memory allocation "hot spots" in your code are. The display format is very similar to that used under the Leak Information tab, and once again the upper pane allows you to sort and filter the display as described under "The Leak Information Screen."

The Heap Statistics Screen

Sometimes the most useful real-time information about a program's dynamic memory use is its overall behavior, rather than just the profile of specific allocation sites. The Heap Statistics screen reports on the memory consumed by things other than live objects. Because Sun WorkShop Memory Monitor takes over your program's memory allocation, it has a unique `insider' perspective on the heap and how it is being used.

The Heap Statistics tab keeps a running total of leaked memory recovered by Sun WorkShop Memory Monitor and of memory that has been unmapped by explicit user calls to free() or delete. It also breaks down your total current heap, which is memory actually still in use, into several categories:

The sum of these categories is your current heap size, the actual footprint of your program in memory. Since Sun WorkShop Memory Monitor attempts to reduce the footprint whenever it can, the Heap Statistics page also shows the maximum heap, a high-water mark of heap usage over the life of your program.

Other Screens

Settings

Many internal settings can be adjusted in real time while the program is running, as well as by calls to our library in your code. The Settings tab shows you all these adjustable settings, and provides hyperlinks into the relevant entries in the user's manual. You can learn quite a bit about how to use Sun WorkShop Memory Monitor more effectively by exploring these settings.

Most of the numbers on the settings page can be changed by typing in new values and clicking "Apply." A few are read-only, and can be changed only by the program itself, rather than interactively. For more details, see "Configuring from the Web Interface."

Note: The changes you make on the Settings screen affect only that run of your program.

Log File

The Log File tab displays the log file, gc.log, that was generated by Sun WorkShop Memory Monitor for this program run. This file, unlike the GC Monitor files, is in a plain ASCII format that is well suited for piping through any custom scripts you may write.

Sun Microsystems

One of the nice things about a web-based interface is that we ourselves are always available -- our personal support starts where our documentation leaves off. You can use this last tab to submit support requests and comments, to inquire about updates and new ports, and to visit the Sun Microsystems web site for further information about our company and its products.

Help

Our full Sun WorkShop Memory Monitor documentation is online and always available to you from the Help tab, as well as from numerous hyperlinks throughout the GC Monitor interface. Special links in the top frame are shortcuts to the User's Manual table of contents, "Quick Start", "Troubleshooting the GC Monitor", and this guide to the GC Monitor web pages.

Troubleshooting the GC Monitor

For problems encountered while using the Memory Debugger (memdb), also read "The Memory Debugger".

Problem:

My browser shows a GC Monitor error: "File not found ."/htdocs/index.html"."

Solution:

Have you moved the file gcmonitor from the gcmonitor directory in the Sun WorkShop Memory Monitor distribution? The monitor depends on a relative path to numerous HTML pages, including the online 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.

Problem:

No web page is found at http://127.0.0.1:2660.

Solution:

Your web browser or your TCP/IP interface may be incorrectly configured. The IP address 127.0.0.1 is the loopback address, which refers to your own computer: it should always be reachable, even on machines that are not connected to the net and have no domain nameserver enabled. But if your networking is not set up to provide the TCP/IP protocol, you will be unable to use a web browser even on local files. Also, 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.

Problem:

Port 2660 is unreachable when I debug remotely.

Solution:

Your firewall may be configured to refuse the incoming connection. Some administrators may set up firewalls in such a way as to preclude remote debugging through our web interface. Consult someone who is familiar with your local security setup.

Problem:

I want the GC Monitor daemon to use 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 daemon to use port 12345, for example, the correct syntax would be gcmonitor -p 12345.

See also "A Note on Security".

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; if you are running Internet Explorer 3.0 or earlier, this is the default setup. At present, the GC Monitor daemon requires both frames and Javascript in order to produce its debug monitor pages, and it should complain informatively if it does not find them.

Problem:

The web page says "Bad GCMonitor File" across the top.

Solution:

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 explore that directory from the desktop to confirm that there really are monitor files in there.

(Note that you can still use the online 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 permanent records of your program's memory allocation behavior during that particular run, and they can be kept long after the program has been quit. Since they are quite large (at present, 8 MB each), 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 backups, 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 whenever 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) intercepts 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.

Problem:

My problem doesn't appear on this troubleshooting list.

Solution:

Send it to us! We probably need to add it, and will be happy to help you track it down

Previous PageTop Of PageTable Of ContentsNext Page