About GCViewer Commandline
**************************

**GCViewer Commandline** is a modified version of **GC Viewer**.

**GC Viewer** is an excellent open source tool by `tagtraum industries incorporated <http://www.tagtraum.com/gcviewer.html>`_, to provide a
way to view the log file produced by the Java Garbage collector (GC).

This web site hosts a modified version of the GC Viewer tool (modified by Sean Ryan),
which allows you to run the tool with **NO interaction**, from the command line.

This is quite handy, if you use a lot of automated tests, and want to monitor the
Java GC.

The GC statistics are output to a CSV file, which can easily be parsed by your scripts.

Example Usage
=============

To parse a GC log file **my_gc_log.log** to a new CSV file **my_gc_summary.csv**:

.. sourcecode:: bat

        java -jar target/gcviewer-1.29.jar my_gc_log.log my_gc_summary.csv

This will summarise the statistics of the GC log file **my_gc_log.log**, to
the CSV file **my_summary.csv**.


The format of the CSV file:
---------------------------
.. sourcecode:: javascript

    {field name 1}, {value}, {units}
    {field name 2}, {value}, {units}
    {field name 3}, {value}, {units}
    ...
    ...


Example CSV output file:
------------------------
.. sourcecode:: bat

    gcLogFile, temp_gclog_input, -
    footprint, 128.25, M
    footprintAfterFullGC, 69.792, M
    footprintAfterFullGCs, 2232.118, K
    footprintAfterFullGCisSig, true, bool
    freedMemoryByFullGC, 2643.391, M
    freedMemoryByFullGCpc, 9.9, %
    avgFreedMemoryByFullGC, 17.623, M/coll
    avgFreedMemoryByFullGCs, 3874.805, K/coll
    avgFreedMemoryByFullGCisSig, true, bool
    ...
    ...

.. _download:

Download
********

Download Sourcecode
===================

Download the **Java source code** here:

`gcviewer-1.29-src-modified-released-20110405_1.zip <http://www.natureireland.com/GCviewer_cmd_line/gcviewer-1.29-src-modified-released-20110405_1.zip>`_

Download this guide as PDF
==========================

Download this user guide in PDF format:

:download:`GCViewerCommandline.pdf <../build/pdf/GCViewerCommandline.pdf>`

History
*******

+---------------------------+--------------------------------------------------------------------------------------------------+
| Version | Date            | Changes                                                                                          |
+=========+=================+==================================================================================================+
| 1.29.1  | 24th April 2011 | Started using Sphinx to auto-generate this documentation                                         |
|         |                 |.. image:: _static/smile.gif                                                                      |
+---------+-----------------+--------------------------------------------------------------------------------------------------+
| 1.29.1  | 4th April 2011  | * Added unit test for the CSV output, for the Sun JDK                                            |
|         |                 | * Made some changes to make the CSV more uniform, and easier to parse:                           |
|         |                 | * Removed embedded commas from the value field in the CSV output                                 |
|         |                 | * Added another column for the units for each field                                              |
|         |                 | * Lines that had an extra value for std. deviation, or for %, have now been split into two lines |
+---------+-----------------+--------------------------------------------------------------------------------------------------+
| 1.29.0  | 26th March 2011 | Released GC Viewer command line, with this user guide.                                           |
+---------+-----------------+--------------------------------------------------------------------------------------------------+

Versioning
==========
**GCViewer Commandline** follows the versioning of the main GCViewer application,
and appends one number at the end.

For example, for GCViewer version 1.29, the equivalent GCViewer Commandline version would be 1.29.x, where x is the build number.

This makes it easy to see what version of **GCViewer** was adapted to have the **Commandline** functionality.