Learning java jstat

Today, we will going to learn a java tool, which is incredibly useful if you are frequent coding for java application. This java tool is a monitoring tool known as jstat and it came with jdk. So you would ask why would I need to use jstat, my app run just fine. So for a simple java application, yes, you do not need to this monitoring tool. However if you have a long running application or big java codebase application, and sometime when your java application run midway hang (pause/freeze), then you should start to look into this tool really. In this article, I'm going to show you how I use it.

But first, let understand on what is jstat.

The jstat tool displays performance statistics for an instrumented HotSpot Java virtual machine (JVM).

As you aware, object that you wrote in the code will eventually get free from heap when it is not reference. If you has a lot of objects and heap usage grow, then you can use this monitoring tool to check out wassup of the heap allocation. Okay now, let's read into the command input.

jstat [ generalOption | outputOptions vmid [interval[s|ms] [count]] ]

so pretty simple, the commands jstat followed by a few parameters. The parameters can be explain below. You can find official documentation here.

generalOption
A single general command-line option (-help or -options)

outputOptions
One or more output options, consisting of a single statOption, plus any of the -t, -h, and -J options.

vmid
Virtual machine identifier, a string indicating the target Java virtual machine (JVM). The general syntax is
[protocol:][//]lvmid[@hostname[:port]/servername]
The syntax of the vmid string largely corresponds to the syntax of a URI. The vmid can vary from a simple integer representing a local JVM to a more complex construction
specifying a communications protocol, port number, and other implementation-specific values. See Virtual Machine Identifier for details.

interval[s|ms]
Sampling interval in the specified units, seconds (s) or milliseconds (ms). Default units are milliseconds. Must be a positive integer. If specified, jstat will produce its
output at each interval.

count
Number of samples to display. Default value is infinity; that is, jstat displays statistics until the target JVM terminates or the jstat command is terminated. Must be a
positive integer.

It should be very clear to you if you are season java coder and if you don't, take a look at an example below.

[iser@localhost ~]$ jstat -gcutil 12345 1s
S0 S1 E O P YGC YGCT FGC FGCT GCT 
10.08 0.00 70.70 69.22 59.49 122328 4380.327 355 43.146 4423.474
10.08 0.00 84.99 69.22 59.49 122328 4380.327 355 43.146 4423.474
0.00 15.62 0.00 69.24 59.49 122329 4380.351 355 43.146 4423.497

so jstat is instrument a local jvm with process id 12345 with an interval of 1 second and loop infinitely. There are different type of statistics can be shown and with the above example given, it show summary of garbage collection statistics. If you want to shown different types of gc statistics, you can use the command jstat -options and below is the table of summaries what these options display means.

Option 	                Displays...
class 	                Statistics on the behavior of the class loader.
compiler 	        Statistics of the behavior of the HotSpot Just-in-Time compiler.
gc 	                Statistics of the behavior of the garbage collected heap.
gccapacity      	Statistics of the capacities of the generations and their corresponding spaces.
gccause 	        Summary of garbage collection statistics (same as -gcutil), with the cause of the last and current (if applicable) garbage collection events.
gcnew 	                Statistics of the behavior of the new generation.
gcnewcapacity   	Statistics of the sizes of the new generations and its corresponding spaces.
gcold           	Statistics of the behavior of the old and permanent generations.
gcoldcapacity   	Statistics of the sizes of the old generation.
gcpermcapacity 	        Statistics of the sizes of the permanent generation.
gcutil          	Summary of garbage collection statistics.
printcompilation 	HotSpot compilation method statistics.

Out of all these options, probably the most frequently you will use is gcutil, gc and gccapacity. We will look at them with example. Please note that in order to protect the privacy of the user, there are some information is removed but what need to be presented in this article shall remained as is.

option gcutil



As can be read above, the command jstat with option gcutil on a java process id 23483. The statistics are generated with an interval at 1 second. It has 10 columns and these column can be explain below.

Column 	Description
S0 	Survivor space 0 utilization as a percentage of the space's current capacity.
S1 	Survivor space 1 utilization as a percentage of the space's current capacity.
E 	Eden space utilization as a percentage of the space's current capacity.
O 	Old space utilization as a percentage of the space's current capacity.
P 	Permanent space utilization as a percentage of the space's current capacity.
YGC 	Number of young generation GC events.
YGCT 	Young generation garbage collection time.
FGC 	Number of full GC events.
FGCT 	Full garbage collection time.
GCT 	Total garbage collection time.

First five columns depict space utilization in term of percentage. The next five depict amount of young generation collection and its time, full garbage collection and its time and last, total garbage collection time. With this screen capture, we see that the eden space is filling up quickly and promoted to either survivor space 0 or survivor space 1. At one instance, some object survived and eventually promoted to old space and increased the usage by 0.01% to 5.24%. Note that also YGC is increased by one as a result to 256. This young generation collection time took 13 milliseconds. Similar pattern happen again later and we see that, YGC is increased by oen to 257 with another 13 milliseconds of collection time. In this output, there is no change to full collection, which is good. It is only one full collection happened but with a pause of 94millseconds! You might want to keep an eye on the E column so it dont fill up quickly and adjust hte young gen in your java app accordingly. But for a long term solution, you might want to spend some time to find out which code take a lot of resources and improve it.

option gc

As can be read above, the command jstat with option gc on a java process id 28276. The statistics are generated with an interval at 1 second. It has 15 columns and these column can be explain below.

Column 	Description
S0C 	Current survivor space 0 capacity (KB).
S1C 	Current survivor space 1 capacity (KB).
S0U 	Survivor space 0 utilization (KB).
S1U 	Survivor space 1 utilization (KB).
EC 	Current eden space capacity (KB).
EU 	Eden space utilization (KB).
OC 	Current old space capacity (KB).
OU 	Old space utilization (KB).
PC 	Current permanent space capacity (KB).
PU 	Permanent space utilization (KB).
YGC 	Number of young generation GC Events.
YGCT 	Young generation garbage collection time.
FGC 	Number of full GC events.
FGCT 	Full garbage collection time.
GCT 	Total garbage collection time.

The statistics shown the capacity in term of kilobytes. First ten columns are pretty easy, the space capacity and its current utilization. The last five columns are the same as gcutil last five columns. Notice that when the column EU value near to the column EC value, young generation collection happened. Object promoted to survivor spaces. Notice that column OU grow gradually. This statistics almost the same with gcutil except that the statistics shown here display in term of bytes whereas gcutil statistics display in term of percentage.

option gccapacity



As can be read above, the command jstat with option gccapacity on a java process id 13080. The statistics are generated with an interval at 1 second. It has 16 columns and these column can be explain below.

Column 	Description
NGCMN 	Minimum new generation capacity (KB).
NGCMX 	Maximum new generation capacity (KB).
NGC 	Current new generation capacity (KB).
S0C 	Current survivor space 0 capacity (KB).
S1C 	Current survivor space 1 capacity (KB).
EC 	Current eden space capacity (KB).
OGCMN 	Minimum old generation capacity (KB).
OGCMX 	Maximum old generation capacity (KB).
OGC 	Current old generation capacity (KB).
OC 	Current old space capacity (KB).
PGCMN 	Minimum permanent generation capacity (KB).
PGCMX 	Maximum Permanent generation capacity (KB).
PGC 	Current Permanent generation capacity (KB).
PC 	Current Permanent space capacity (KB).
YGC 	Number of Young generation GC Events.
FGC 	Number of Full GC Events.

These output is similar to the output of option gc but with minimum and maximum for the individual java heap.

That's it for this article and I will leave three links for your references.

http://www.cubrid.org/blog/dev-platform/how-to-monitor-java-garbage-collection/
http://docs.oracle.com/javase/7/docs/technotes/tools/share/jstat.html
http://oracle-base.com/articles/misc/monitoring-java-garbage-collection-using-jstat.php