How to Analyze and Visualize jHiccup Logs

This article is applicable only to jHiccup v2.x. The jHiccup 2.x distro comes with two helper apps to help you analyze and visualize jHiccup's output. They are:


It's a two step process.

1. Use jHiccupLogProcessor to convert the jHiccup log file to human readable output files.
2. Use jHiccupPlotter.xls to visualize the data in the jHiccupLogProcessor output files.

Step 1: jHiccupLogProcessor

jHiccup logs hiccup information in a histogram log (see This histogram log contains a full, high fidelity histogram of all collected result sin each interval, in a highly compressed form (typically using only ~200-400 bytes per interval). However, other than the timestamp and maximum hiccup magnitude found in the given interval, the rest of the log line for each interval is not human readable (it is a base64 encoding of a compressed HdrHistogram).

To translate the jHiccup log file to a more human-readable form (identical to the form that jHiccup versions before jHiccup 2.0 had used), the jHiccupLogProcessor utility is provided. Here's a simple example:

% jHiccupLogProcessor -i jHiccup.log -o jHiccup.log.out

That example will produce two log files: jHiccup.log.out and jHiccup.log.out.hgrm. The first file, jHiccup.log.out, will contain a human readable interval log, with selected percentiles in each interval. The second file, jHiccup.log.out.hgrm, will contain a human readable histogram percentile distribution log.

Step 2: jHiccupPlotter.xls

Use jHiccupPlotter.xls to visualize the data in the files produced by jHiccupLogProcessor produced. The spreadsheet reads both of the jHiccupLogProcessor output files,

Click the Enable Content button if you get "SECURITY WARNING Some active content has been disabled." when you open the file.

Click the Open File icon in the Main Menu worksheet and point it to the jHiccupLogProcessor interval log. The spreadsheet needs both of the jHiccupLogProcessor output files, so both files must be in the same directory.

Click Go and the spreadsheet will create a new worksheet with a graph of your jHiccup results.

More Information

For more information about jHiccup and these tools please see the README file in the jHiccup 2.x distro. You can download the current version of jHiccup (v 2.0.6 as of this writing) from the Azul website.



Add Comment


  • For Mac users I can recommend the web based histogram plotter. The general performance of Macros on Excel for Mac is really poor so you would wait several minutes for normal hiccup.logs to render.

    Web based histogram plotter:

    As input file it requires the .hgrm created by jHiccupLogProcessor.


  • Another alternative is the following GUI tool which can directly load a jhiccup.out.log without the need for creating the hgrm file: 


Please sign in to leave a comment.

Was this article helpful?
0 out of 0 found this helpful