| --- | |
| # Copyright (c) 2004, 2024, Oracle and/or its affiliates. All rights reserved. | |
| # DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. | |
| # | |
| # This code is free software; you can redistribute it and/or modify it | |
| # under the terms of the GNU General Public License version 2 only, as | |
| # published by the Free Software Foundation. | |
| # | |
| # This code is distributed in the hope that it will be useful, but WITHOUT | |
| # ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or | |
| # FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License | |
| # version 2 for more details (a copy is included in the LICENSE file that | |
| # accompanied this code). | |
| # | |
| # You should have received a copy of the GNU General Public License version | |
| # 2 along with this work; if not, write to the Free Software Foundation, | |
| # Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. | |
| # | |
| # Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA | |
| # or visit www.oracle.com if you need additional information or have any | |
| # questions. | |
| # | |
| title: 'JSTAT(1) JDK @@VERSION_SHORT@@ | JDK Commands' | |
| date: @@COPYRIGHT_YEAR@@ | |
| lang: en | |
| --- | |
| ## Name | |
| jstat - monitor JVM statistics | |
| ## Synopsis | |
| **Note:** This command is experimental and unsupported. | |
| `jstat` *generalOptions* | |
| `jstat` *outputOptions* \[`-t`\] \[`-h` *lines*\] *vmid* \[*interval* | |
| \[*count*\]\] | |
| *generalOptions* | |
| : A single general command-line option. See [General Options]. | |
| *outputOptions* | |
| : An option reported by the `-options` option. One or more output options | |
| that consist of a single `statOption`, plus any of the `-t`, `-h`, and `-J` | |
| options. See [Output Options for the jstat Command]. | |
| `-t` | |
| : Displays a time-stamp column as the first column of output. The time stamp | |
| is the time since the start time of the target JVM. | |
| `-h` *n* | |
| : Displays a column header every *n* samples (output rows), where *n* is a | |
| positive integer. The default value is `0`, which displays the column | |
| header of the first row of data. | |
| *vmid* | |
| : A virtual machine identifier, which is a string that indicates the target | |
| JVM. See [Virtual Machine Identifier]. | |
| *interval* | |
| : The sampling interval in the specified units, seconds (s) or milliseconds | |
| (ms). Default units are milliseconds. This must be a positive integer. When | |
| specified, the `jstat` command produces its output at each interval. | |
| *count* | |
| : The number of samples to display. The default value is infinity, which | |
| causes the `jstat` command to display statistics until the target JVM | |
| terminates or the `jstat` command is terminated. This value must be a | |
| positive integer. | |
| ## Description | |
| The `jstat` command displays performance statistics for an instrumented Java | |
| HotSpot VM. The target JVM is identified by its virtual machine identifier, or | |
| `vmid` option. | |
| The `jstat` command supports two types of options, general options and output | |
| options. General options cause the `jstat` command to display simple usage and | |
| version information. Output options determine the content and format of the | |
| statistical output. | |
| All options and their functionality are subject to change or removal in future | |
| releases. | |
| ## General Options | |
| If you specify one of the general options, then you can't specify any other | |
| option or parameter. | |
| `-help` | |
| : Displays a help message. | |
| `-options` | |
| : Displays a list of static options. See [Output Options for the jstat | |
| Command]. | |
| ## Output Options for the jstat Command | |
| If you don't specify a general option, then you can specify output options. | |
| Output options determine the content and format of the `jstat` command's | |
| output, and consist of a single `statOption`, plus any of the other output | |
| options (`-h`, `-t`, and `-J`). The `statOption` must come first. | |
| Output is formatted as a table, with columns that are separated by spaces. A | |
| header row with titles describes the columns. Use the `-h` option to set the | |
| frequency at which the header is displayed. Column header names are consistent | |
| among the different options. In general, if two options provide a column with | |
| the same name, then the data source for the two columns is the same. | |
| Use the `-t` option to display a time-stamp column, labeled Timestamp as the | |
| first column of output. The Timestamp column contains the elapsed time, in | |
| seconds, since the target JVM started. The resolution of the time stamp is | |
| dependent on various factors and is subject to variation due to delayed thread | |
| scheduling on heavily loaded systems. | |
| Use the interval and count parameters to determine how frequently and how many | |
| times, respectively, the `jstat` command displays its output. | |
| **Note:** | |
| Don't write scripts to parse the `jstat` command's output because the format | |
| might change in future releases. If you write scripts that parse the `jstat` | |
| command output, then expect to modify them for future releases of this tool. | |
| `-statOption` | |
| : Determines the statistics information that the `jstat` command displays. | |
| The following lists the available options. Use the `-options` general | |
| option to display the list of options for a particular platform | |
| installation. See [Stat Options and Output]. | |
| `class`: Displays statistics about the behavior of the class loader. | |
| `compiler`: Displays statistics about the behavior of the Java HotSpot VM | |
| Just-in-Time compiler. | |
| `gc`: Displays statistics about the behavior of the garbage collected heap. | |
| `gccapacity`: Displays statistics about the capacities of the generations | |
| and their corresponding spaces. | |
| `gccause`: Displays a summary about garbage collection statistics (same as | |
| `-gcutil`), with the cause of the last and current (when applicable) | |
| garbage collection events. | |
| `gcnew`: Displays statistics about the behavior of the new generation. | |
| `gcnewcapacity`: Displays statistics about the sizes of the new generations | |
| and their corresponding spaces. | |
| `gcold`: Displays statistics about the behavior of the old generation and | |
| metaspace statistics. | |
| `gcoldcapacity`: Displays statistics about the sizes of the old generation. | |
| `gcmetacapacity`: Displays statistics about the sizes of the metaspace. | |
| `gcutil`: Displays a summary about garbage collection statistics. | |
| `printcompilation`: Displays Java HotSpot VM compilation method statistics. | |
| `-J`*javaOption* | |
| : Passes *javaOption* to the Java application launcher. For example, | |
| `-J-Xms48m` sets the startup memory to 48 MB. For a complete list of | |
| options, see [java](java.html). | |
| ## Stat Options and Output | |
| The following information summarizes the columns that the `jstat` command | |
| outputs for each *statOption*. | |
| `-class` *option* | |
| : Class loader statistics. | |
| `Loaded`: Number of classes loaded. | |
| `Bytes`: Number of KB loaded. | |
| `Unloaded`: Number of classes unloaded. | |
| `Bytes`: Number of KB unloaded. | |
| `Time`: Time spent performing class loading and unloading operations. | |
| `-compiler` *option* | |
| : Java HotSpot VM Just-in-Time compiler statistics. | |
| `Compiled`: Number of compilation tasks performed. | |
| `Failed`: Number of compilations tasks failed. | |
| `Invalid`: Number of compilation tasks that were invalidated. | |
| `Time`: Time spent performing compilation tasks. | |
| `FailedType`: Compile type of the last failed compilation. | |
| `FailedMethod`: Class name and method of the last failed compilation. | |
| `-gc` *option* | |
| : Garbage collected heap statistics. | |
| `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). | |
| `MC`: Metaspace Committed Size (KB). | |
| `MU`: Metaspace utilization (KB). | |
| `CCSC`: Compressed class committed size (KB). | |
| `CCSU`: Compressed class space used (KB). | |
| `YGC`: Number of young generation garbage collection (GC) events. | |
| `YGCT`: Young generation garbage collection time. | |
| `FGC`: Number of full GC events. | |
| `FGCT`: Full garbage collection time. | |
| `GCT`: Total garbage collection time. | |
| `-gccapacity` *option* | |
| : Memory pool generation and space capacities. | |
| `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). | |
| `MCMN`: Minimum metaspace capacity (KB). | |
| `MCMX`: Maximum metaspace capacity (KB). | |
| `MC`: Metaspace Committed Size (KB). | |
| `CCSMN`: Compressed class space minimum capacity (KB). | |
| `CCSMX`: Compressed class space maximum capacity (KB). | |
| `CCSC`: Compressed class committed size (KB). | |
| `YGC`: Number of young generation GC events. | |
| `FGC`: Number of full GC events. | |
| `-gccause` *option* | |
| : This option displays the same summary of garbage collection statistics as | |
| the `-gcutil` option, but includes the causes of the last garbage | |
| collection event and (when applicable), the current garbage collection | |
| event. In addition to the columns listed for `-gcutil`, this option adds | |
| the following columns: | |
| `LGCC`: Cause of last garbage collection | |
| `GCC`: Cause of current garbage collection | |
| `-gcnew` *option* | |
| : New generation statistics. | |
| `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). | |
| `TT`: Tenuring threshold. | |
| `MTT`: Maximum tenuring threshold. | |
| `DSS`: Desired survivor size (KB). | |
| `EC`: Current eden space capacity (KB). | |
| `EU`: Eden space utilization (KB). | |
| `YGC`: Number of young generation GC events. | |
| `YGCT`: Young generation garbage collection time. | |
| `-gcnewcapacity` *option* | |
| : New generation space size statistics. | |
| `NGCMN`: Minimum new generation capacity (KB). | |
| `NGCMX`: Maximum new generation capacity (KB). | |
| `NGC`: Current new generation capacity (KB). | |
| `S0CMX`: Maximum survivor space 0 capacity (KB). | |
| `S0C`: Current survivor space 0 capacity (KB). | |
| `S1CMX`: Maximum survivor space 1 capacity (KB). | |
| `S1C`: Current survivor space 1 capacity (KB). | |
| `ECMX`: Maximum eden space capacity (KB). | |
| `EC`: Current eden space capacity (KB). | |
| `YGC`: Number of young generation GC events. | |
| `FGC`: Number of full GC events. | |
| `-gcold` *option* | |
| : Old generation size statistics. | |
| `MC`: Metaspace Committed Size (KB). | |
| `MU`: Metaspace utilization (KB). | |
| `CCSC`: Compressed class committed size (KB). | |
| `CCSU`: Compressed class space used (KB). | |
| `OC`: Current old space capacity (KB). | |
| `OU`: Old space utilization (KB). | |
| `YGC`: Number of young generation GC events. | |
| `FGC`: Number of full GC events. | |
| `FGCT`: Full garbage collection time. | |
| `GCT`: Total garbage collection time. | |
| `-gcoldcapacity` *option* | |
| : Old generation statistics. | |
| `OGCMN`: Minimum old generation capacity (KB). | |
| `OGCMX`: Maximum old generation capacity (KB). | |
| `OGC`: Current old generation capacity (KB). | |
| `OC`: Current old space capacity (KB). | |
| `YGC`: Number of young generation GC events. | |
| `FGC`: Number of full GC events. | |
| `FGCT`: Full garbage collection time. | |
| `GCT`: Total garbage collection time. | |
| `-gcmetacapacity` *option* | |
| : Metaspace size statistics. | |
| `MCMN`: Minimum metaspace capacity (KB). | |
| `MCMX`: Maximum metaspace capacity (KB). | |
| `MC`: Metaspace Committed Size (KB). | |
| `CCSMN`: Compressed class space minimum capacity (KB). | |
| `CCSMX`: Compressed class space maximum capacity (KB). | |
| `YGC`: Number of young generation GC events. | |
| `FGC`: Number of full GC events. | |
| `FGCT`: Full garbage collection time. | |
| `GCT`: Total garbage collection time. | |
| `-gcutil` *option* | |
| : Summary of garbage collection statistics. | |
| `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. | |
| `M`: Metaspace utilization as a percentage of the space's current capacity. | |
| `CCS`: Compressed class space utilization as a percentage. | |
| `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. | |
| `-printcompilation` *option* | |
| : Java HotSpot VM compiler method statistics. | |
| `Compiled`: Number of compilation tasks performed by the most recently | |
| compiled method. | |
| `Size`: Number of bytes of byte code of the most recently compiled method. | |
| `Type`: Compilation type of the most recently compiled method. | |
| `Method`: Class name and method name identifying the most recently compiled | |
| method. Class name uses a slash (/) instead of a dot (.) as a name space | |
| separator. The method name is the method within the specified class. The | |
| format for these two fields is consistent with the HotSpot | |
| `-XX:+PrintCompilation` option. | |
| ## Virtual Machine Identifier | |
| The syntax of the `vmid` string corresponds to the syntax of a URI: | |
| > \[*protocol*`:`\]\[`//`\]*lvmid*\[`@`*hostname*\[`:`*port*\]\[`/`*servername*\] | |
| The syntax of the `vmid` string corresponds to the syntax of a URI. The `vmid` | |
| string can vary from a simple integer that represents a local JVM to a more | |
| complex construction that specifies a communications protocol, port number, and | |
| other implementation-specific values. | |
| *protocol* | |
| : The communications protocol. If the *protocol* value is omitted and a host | |
| name isn't specified, then the default protocol is a platform-specific | |
| optimized local protocol. If the *protocol* value is omitted and a host | |
| name is specified, then the default protocol is `rmi`. | |
| *lvmid* | |
| : The local virtual machine identifier for the target JVM. The *lvmid* is a | |
| platform-specific value that uniquely identifies a JVM on a system. The | |
| *lvmid* is the only required component of a virtual machine identifier. The | |
| *lvmid* is typically, but not necessarily, the operating system's process | |
| identifier for the target JVM process. You can use the `jps` command to | |
| determine the *lvmid* provided the JVM processes is not running in a | |
| separate docker instance. You can also determine the *lvmid* on Linux and | |
| macOS platforms with the `ps` command, and on Windows with the Windows Task | |
| Manager. | |
| *hostname* | |
| : A host name or IP address that indicates the target host. If the *hostname* | |
| value is omitted, then the target host is the local host. | |
| *port* | |
| : The default port for communicating with the remote server. If the | |
| *hostname* value is omitted or the *protocol* value specifies an optimized, | |
| local protocol, then the *port* value is ignored. Otherwise, treatment of | |
| the *port* parameter is implementation-specific. For the default `rmi` | |
| protocol, the port value indicates the port number for the `rmiregistry` on | |
| the remote host. If the *port* value is omitted and the *protocol* value | |
| indicates `rmi`, then the default rmiregistry port (1099) is used. | |
| *servername* | |
| : The treatment of the *servername* parameter depends on implementation. For | |
| the optimized local protocol, this field is ignored. For the `rmi` | |
| protocol, it represents the name of the RMI remote object on the remote | |
| host. | |
| ## Examples | |
| This section presents some examples of monitoring a local JVM with an *lvmid* | |
| of 21891. | |
| ## The gcutil Option | |
| This example attaches to lvmid 21891 and takes 7 samples at 250 millisecond | |
| intervals and displays the output as specified by the `-gcutil` option. | |
| The output of this example shows that a young generation collection occurred | |
| between the third and fourth sample. The collection took 0.078 seconds and | |
| promoted objects from the eden space (E) to the old space (O), resulting in an | |
| increase of old space utilization from 66.80% to 68.19%. Before the collection, | |
| the survivor space was 97.02% utilized, but after this collection it's 91.03% | |
| utilized. | |
| ``` | |
| jstat -gcutil 21891 250 7 | |
| S0 S1 E O M CCS YGC YGCT FGC FGCT GCT | |
| 0.00 97.02 70.31 66.80 95.52 89.14 7 0.300 0 0.000 0.300 | |
| 0.00 97.02 86.23 66.80 95.52 89.14 7 0.300 0 0.000 0.300 | |
| 0.00 97.02 96.53 66.80 95.52 89.14 7 0.300 0 0.000 0.300 | |
| 91.03 0.00 1.98 68.19 95.89 91.24 8 0.378 0 0.000 0.378 | |
| 91.03 0.00 15.82 68.19 95.89 91.24 8 0.378 0 0.000 0.378 | |
| 91.03 0.00 17.80 68.19 95.89 91.24 8 0.378 0 0.000 0.378 | |
| 91.03 0.00 17.80 68.19 95.89 91.24 8 0.378 0 0.000 0.378 | |
| ``` | |
| ## Repeat the Column Header String | |
| This example attaches to lvmid 21891 and takes samples at 250 millisecond | |
| intervals and displays the output as specified by `-gcnew` option. In addition, | |
| it uses the `-h3` option to output the column header after every 3 lines of | |
| data. | |
| In addition to showing the repeating header string, this example shows that | |
| between the second and third samples, a young GC occurred. Its duration was | |
| 0.001 seconds. The collection found enough active data that the survivor space | |
| 0 utilization (S0U) would have exceeded the desired survivor size (DSS). As a | |
| result, objects were promoted to the old generation (not visible in this | |
| output), and the tenuring threshold (TT) was lowered from 31 to 2. | |
| Another collection occurs between the fifth and sixth samples. This collection | |
| found very few survivors and returned the tenuring threshold to 31. | |
| ``` | |
| jstat -gcnew -h3 21891 250 | |
| S0C S1C S0U S1U TT MTT DSS EC EU YGC YGCT | |
| 64.0 64.0 0.0 31.7 31 31 32.0 512.0 178.6 249 0.203 | |
| 64.0 64.0 0.0 31.7 31 31 32.0 512.0 355.5 249 0.203 | |
| 64.0 64.0 35.4 0.0 2 31 32.0 512.0 21.9 250 0.204 | |
| S0C S1C S0U S1U TT MTT DSS EC EU YGC YGCT | |
| 64.0 64.0 35.4 0.0 2 31 32.0 512.0 245.9 250 0.204 | |
| 64.0 64.0 35.4 0.0 2 31 32.0 512.0 421.1 250 0.204 | |
| 64.0 64.0 0.0 19.0 31 31 32.0 512.0 84.4 251 0.204 | |
| S0C S1C S0U S1U TT MTT DSS EC EU YGC YGCT | |
| 64.0 64.0 0.0 19.0 31 31 32.0 512.0 306.7 251 0.204 | |
| ``` | |
| ## Include a Time Stamp for Each Sample | |
| This example attaches to lvmid 21891 and takes 3 samples at 250 millisecond | |
| intervals. The `-t` option is used to generate a time stamp for each sample in | |
| the first column. | |
| The Timestamp column reports the elapsed time in seconds since the start of the | |
| target JVM. In addition, the `-gcoldcapacity` output shows the old generation | |
| capacity (OGC) and the old space capacity (OC) increasing as the heap expands | |
| to meet allocation or promotion demands. The old generation capacity (OGC) has | |
| grown from 11,696 KB to 13,820 KB after the eighty-first full garbage | |
| collection (FGC). The maximum capacity of the generation (and space) is 60,544 | |
| KB (OGCMX), so it still has room to expand. | |
| ``` | |
| Timestamp OGCMN OGCMX OGC OC YGC FGC FGCT GCT | |
| 150.1 1408.0 60544.0 11696.0 11696.0 194 80 2.874 3.799 | |
| 150.4 1408.0 60544.0 13820.0 13820.0 194 81 2.938 3.863 | |
| 150.7 1408.0 60544.0 13820.0 13820.0 194 81 2.938 3.863 | |
| ``` | |
| ## Monitor Instrumentation for a Remote JVM | |
| This example attaches to lvmid 40496 on the system named `remote.domain` using | |
| the `-gcutil` option, with samples taken every second indefinitely. | |
| The lvmid is combined with the name of the remote host to construct a vmid of | |
| `40496@remote.domain`. This vmid results in the use of the `rmi` protocol to | |
| communicate to the default `jstatd` server on the remote host. The `jstatd` | |
| server is located using the `rmiregistry` command on `remote.domain` that's | |
| bound to the default port of the `rmiregistry` command (port 1099). | |
| ``` | |
| jstat -gcutil 40496@remote.domain 1000 | |
| ... output omitted | |
| ``` |