Visit Azul.com Support

GC Log Analyser Command-Line Options

Table of Contents
Need help?
Schedule a consultation with an Azul performance expert.
Contact Us

You can control the behavior of the gcLogAnalyser tool by using command-line options from the options below.

Basic GC Log Analyser Command-Line Options

Command-Line Option Description

[-help ]| -h]

Prints information about the command-line options.

[-helpdate | -datehelp]

Prints X-axis date and elapsed time use help message.

[-f nameOfGCFileToOpen]

File name of the Azul Zing Builds of OpenJDK (Zing) GC log file to open

[-esg]

Enable use of detailed, low-level graphs in GC Log Analyser.

[-wse]

Write warning and error messages to stderr. This is used to capture warnings and errors for documentation when reporting bugs.

[-ipe | -ignoreParsingErrors]

Ignore Parsing Errors: Ignore lines in the file with parsing errors but write each skipped line to stderr.

[-parseFileWithMissingGCHLines]

Try parsing GC log files with missing GC log file header lines. When the Zing starts and a GC log is being created, information about the environment is printed to the log.

The information includes the start time for the Zing process.

If the file is very large and you are having trouble with memory use by GC Log Analyser then split the GC log file into smaller files that are easier to analyze.

Use this option to override the normal requirement that the initial information be present in the GC log file.

Alternatively, append the original file’s [GCHH and first [GCH lines to each of the smaller files.

[{-et | -elapsedTimeUnits} {ms | sec | min | hour |date} ]

Set the elapsed time units (X-axis values) to milliseconds, seconds, minutes, hours, or date and time (default is minutes)

[-samu | showAllMemUseInHeapUseGraphs]

Show all memory in use (including Pause Prevention) in the Java Heap Use graphs in GC Log Analyser

[-version]

Print gcLogAnalyser’s version and build time

Options for Converting Graphs to PNG Files Without Using the GUI

Use the following command-line options to create PNG files when running GC Log Analyser in the non-GUI mode.

Command-Line Option Description

[-graphsToConvertToPNG {graphID[,graphID]* | all}]

List of graphIDs to convert to PNG files or the string "all" to print all supported graphs. The set of "all" graphs is either the default set of graphs in the Graph menu or the complete set of graphs if the Graph menu’s "Show more graphs" menu item has been selected. To ensure conversion of the highest number of graphs to PNG files, also include the option: -esg GC LOog Analyser uses the data available in a GC log file to create the best set of graphs from that data. Some older graphs created when the data in the GC log file was more limited have been superseded by new graphs generated with updated information in GC log files generated by newer versions of Zing.

[-gidtogname | -printGraphIDToGraphNameList]

Prints the graphIDs to use as parameters to the graphsToConvertToPNG command line option. Eash line in the list generated to stdout has the graphID and its corresponding graph name.

[{-gtopngwxh | -graphToPNGWidthXHeight} widthxheight]

Width and height for the PNG image to be generated in units of pixels. Default value for widthxheight is 3000x1000. Suggested size for generating graphs to embed in documents: 1500x500.

[{-gtopngtpre | -graphToPNGTitlePrefix} "titlePrefix"]

String to add as the prefix to the title printed at the top of graph in the PNG file. Use the "^" character instead of spaces in the titlePrefix string. Substitutions in the titlePrefix string done by gcLogAnalyser:

  • %t – start time of the Zing process

  • %m – name of the machine on which the process was run

  • %p – PID for the process

Example:

-gtopngtpre "Eric’sCassandraRunon%t(%mPID:%p)-^"

[{-gtopngbfn | -graphToPNGBaseFileName} baseFileName]

Format of PNG file name to use: <baseFileName>_GraphName.png

The strings for which substitutions are made, %t, %m and %p, described in the use of the -graphToPNGTitlePrefix command line option can also be included in the baseFileName string.

[{-gtopngfnpre | -graphToPNGFileNamePrefix} fileNamePrefix]

Format of PNG file name: <fileNamePrefixProcessStartDate>_GCLogFileName_GraphName.png

Valid paths and directory names are accepted in fileNamePrefix.

Options for Restricting the Graphed Elapsed Time Interval

With the following options you can elapsed time interval initially displayed in the GUI mode graphs and displayed in the non-GUI-mode PNG files. When using the GUI-mode, the graphs opened respect the values supplied using the command line options until the toolbar’s Reset button is selected or the Edit > Reset Time Range menu item is selected. Subsequently, all graphs will use the minimum and maximum values from the GC log file until a toolbar Set Time Range or Edit > Set Time Range To Selected menu item has been selected.

Legend for [[h:]m:]s h is hours (integer); m is minutes (integer); s is seconds (real)

Command-Line Option Description

[{-getistart | -graphElapsedTimeIntervalStart} [[h:]m:]s]

Elapsed time since the launch of the process to use as the beginning of the interval of time to graph data when generating graphs or PNG files.

If not specified then the first elapsed time in the file’s data is used.

The supplied value must be positive and greater than or equal to the data’s first elapsed time.

The supplied value must be positive and less than the data’s last elapsed time, otherwise, the data’s first elapsed time is used.

A provided start time must be less than a provided end time.

[{-getiend | -graphElapsedTimeIntervalEnd} [[h:]m:]s]

Elapsed time since the launch of the process to use as the end of the interval of time to graph data when generating graphs or PNG files. If not specified then the last elapsed time in the file’s data is used.

The supplied value must be positive and less than or equal to the data’s last elapsed time, otherwise the last elapsed time is used.

A provided end time must be greater than a provided start time.

X-axis Date and Time Options

With the following options you can print help information about X-axis date and time command-line options, select date and time as the X-axis units, control the X-axis label orientation and correct for any issues with GC Log Analyser’s date and time auto-detection mechanism used to set the time zone when using the date-time values for the X-axis.

Command-Line Option Description

[-helpdate | -datehelp]

Prints X-axis date and time use help message.

[[{-et | -elapsedTimeUnits} date] | -useDateTimeXAxis | -usedatex]

Uses date and time for the X-axis rather than elapsed time in units of milliseconds, seconds, minutes or hours.

[{-useDateTimeXAxisLabelOrientation | -usedatexlabelorient} {vertical | horizontal}]

Orients the X-axis date and time labels vertically or horizontally.

Default orientation is vertical.

[{-xAxisTimeZoneOffsetHrs | -xTimeOffsetHrs} "real-number"]

The number of offset hours to obtain alignment of the times in the GC log file with times used by the graph. As a first approximation, the value that should be used is the difference between the UTC time zone where the GC log file was generated and the UTC time zone where gcLogAnalyser is being run. You should only need to use this option if gcLogAnalyser is not able to do the calculations correctly. Units for real-number are hours plus fractional hours.

Example:

File generated on machine with: India Standard Time UTC +5.5

gcLogAnalyser run on machine with: Eastern Standard Time UTC -5

Offset = IST - EST = 5.5 - (-5) = 10.5

Add option: -xAxisTimeZoneOffsetHrs 10.5

[{-dateMaxMSAdd | -dateTimeMaxMSToAddForDuplicateSeriesTimes} "integer"]

When using the X-axis date and time graphs, the X value (elapsed time) for each point in a series must be unique at millisecond granularity. Data in the GC log file is collected with microsecond accuracy and multiple events can occur per millisecond. To resolve this issue and ensure that all data in a series is displayed, gcLogAnalyser adds a millisecond to the elapsed time value if the value is the same as the previous, hoping to find a unique value. Incrementing the elapsed time value can be repeated.

The integer value (>0) provided using this option is the upper bound on the number of times to add a millisecond in an attempt to find a unique value.

Default value is: 5

[-printDateTimeMessages {true | false}]

Prints messages to stdout about the work done by gcLogAnalyser to process the X-axis values. The messages can include information about points with the same value for the X coordinate (gcLogAnalyser tries to plot them) and data series that are empty.