mackerel-plugin-jvm retrieves various metrics about the JVM from commands such as jstat, jinfo and jps.
This plugin will not work if PerfDisableSharedMem
is specified in the JVM options. For more information, see here for details.
Specification
Run the following jstat command on the application lvmid specified by --javaname
or the process ID of the file specified by --pidfile
and post the output as a metric. The string after the last dot (.) in the metric name corresponds to the name of each piece of information that can be retrieved with the jstat command.
- jstat -gc
- jstat -gccapacity
- jstat -gcnew
- jstat -gcold
Monitorable metrics
The XXX
in each graph name is set to the application name specified by the --javaname
option.
JVM XXX GC events
Metric Display Name |
Metric Name |
Diff |
Stacked |
Description |
Young GC event |
custom.jvm.#.gc_events.YGC |
✓ |
|
Number of Young GC events |
Full GC event |
custom.jvm.#.gc_events.FGC |
✓ |
|
Number of Full GC events |
Concurrent GC event |
custom.jvm.#.gc_events.CGC |
✓ |
|
Number of Concurrent GC events |
- Concurrent GC event is available in Java 11 or later.
JVM XXX GC time (sec)
Metric Display Name |
Metric Name |
Diff |
Stacked |
Description |
Young GC time |
custom.jvm.#.gc_time.YGCT |
✓ |
|
Execution time of Young GC |
Full GC time |
custom.jvm.#.gc_time.FGCT |
✓ |
|
Execution time of Full GC |
Concurrent GC time |
custom.jvm.#.gc_time.CGCT |
✓ |
|
Execution time of Concurrent GC |
- Concurrent GC time is available in Java 11 or later.
JVM XXX GC time percentage
Metric Display Name |
Metric Name |
Diff |
Stacked |
Description |
Young GC time |
custom.jvm.#.gc_time_percentage.YGCT |
✓ |
|
Percentage of Young GC in GC time per 60 seconds |
Full GC time |
custom.jvm.#.gc_time_percentage.FGCT |
✓ |
|
Percentage of Full GC in GC time per 60 seconds |
Concurrent GC time |
custom.jvm.#.gc_time_percentage.CGCT |
✓ |
|
Percentage of Concurrent GC in GC time per 60 seconds |
- Concurrent GC time is available in Java 11 or later.
JVM XXX New Space memory
Metric Display Name |
Metric Name |
Diff |
Stacked |
Description |
New max |
custom.jvm.#.new_space.NGCMX |
|
|
Maximum capacity of New Generation (KB) |
New current |
custom.jvm.#.new_space.NGC |
|
|
Current capacity of New Generation (KB) |
Eden used |
custom.jvm.#.new_space.EU |
|
|
Eden space usage (KB) |
Survivor0 used |
custom.jvm.#.new_space.S0U |
|
|
Current usage of Survivor space 0 (KB) |
Survivor1 used |
custom.jvm.#.new_space.S1U |
|
|
Current usage of Survivor space 1 (KB) |
JVM XXX Old Space memory
Metric Display Name |
Metric Name |
Diff |
Stacked |
Description |
Old max |
custom.jvm.#.old_space.OGCMX |
|
|
Maximum capacity of Old Generation (KB) |
Old current |
custom.jvm.#.old_space.OGC |
|
|
Current capacity of Old Generation (KB) |
Old used |
custom.jvm.#.old_space.OU |
|
|
Old space usage (KB) |
JVM XXX Permanent Space
Metric Display Name |
Metric Name |
Diff |
Stacked |
Description |
Perm max |
custom.jvm.#.perm_space.PGCMX |
|
|
Maximum capacity of Permanent Generation (KB) |
Perm current |
custom.jvm.#.perm_space.PGC |
|
|
Current capacity of Permanent Generation (KB) |
Perm used |
custom.jvm.#.perm_space.PU |
|
|
Permanent space usage (KB) |
- Java 8 or later is not supported.
Metric Display Name |
Metric Name |
Diff |
Stacked |
Description |
Metaspace capacity max |
custom.jvm.#.metaspace.MCMX |
|
|
Maximum capacity of metaspace (KB) |
Metaspace capacity min |
custom.jvm.#.metaspace.MCMN |
|
|
Minimum capacity of metaspace (KB) |
Metaspace capacity |
custom.jvm.#.metaspace.MC |
|
|
Metaspace capacity (KB) |
Metaspace utilization |
custom.jvm.#.metaspace.MU |
|
|
Metaspace usage (KB) |
Compressed Class Space Capacity |
custom.jvm.#.metaspace.CCSC |
|
|
Compressed class space capacity (KB) |
Compressed Class Space Used |
custom.jvm.#.metaspace.CCSU |
|
|
Compressed class space used (KB) |
JVM XXX MemorySpace
Metric Display Name |
Metric Name |
Diff |
Stacked |
Description |
GC Old Memory Space |
custom.jvm.#.memorySpace.oldSpaceRate |
|
|
Old generation usage rate |
GC New Memory Space |
custom.jvm.#.memorySpace.newSpaceRate |
|
|
New generation usage rate |
CMS Initiating Occupancy Fraction |
custom.jvm.#.memorySpace.CMSInitiatingOccupancyFraction |
|
|
Threshold to perform CMS GC |
- GC Old Memory Space is calculated as
(Old used / Old current ) * 100
.
- GC New Memory Space is calculated as
(Survivor0 used + Survivor1 used + Eden used) / (Survivor0 current + Survivor1 current + Eden current) * 100
.
- CMS Initiating Occupancy Fraction is not posted when the
--remote
option is specified.
- If the
--remote
option is not specified, the following command will be executed when retrieving information.
- jinfo -flag UseConcMarkSweepGC
- jinfo -flag CMSInitiatingOccupancyFraction
Configurable options
The options that can be specified for the plug-ins are as follows.
Option |
Description |
Required |
Default |
--host |
Deprecated: hostname of jps/jstat |
|
|
--port |
Deprecated: Target port of jps/jstat |
|
0 |
--remote |
Remote target for jps/jstat. Specified by hostname[:port][/servername] . |
|
|
--jstatpath |
Path to jstat command |
|
/usr/bin/jstat or $JAVA_HOME/bin/jstat |
--jinfopath |
Path to jinfo command |
|
/usr/bin/jinfo or $JAVA_HOME/bin/jinfo |
--jpspath |
Path to jps command |
|
/usr/bin/jps or $JAVA_HOME/bin/jps |
--javaname |
The name of the application to be used as the graph name |
✓ |
|
--pidfile |
Path to pidfile |
|
|
--tempfile |
Path to Temp file |
|
|
- If the
--remote
option is specified, jps and jstat must be executable locally from this plugin.
- If there is more than one application with the name specified in the
--javaname
option, only one of the metrics will be posted.
- To identify one of several applications with duplicate names, specify the pid file of the application to be monitored with the
--pidfile
option, or adjust the application name to avoid duplication.
Example configuration
[plugin.metrics.jvm-tomcat]
command = [ "mackerel-plugin-jvm", "--javaname", "tomcat", "--jstatpath", "/usr/bin/jstat", "--jpspath", "/usr/bin/jps", "--jinfopath", "/usr/bin/jinfo"]
If you have multiple JVMs running on the same host and wish to monitor each one individually, specify different values for [plugin.metrics.xxxxxx]
as follows
[plugin.metrics.jvm-app01]
command = [ "mackerel-plugin-jvm", "--jstatpath", "/usr/bin/jstat", "--jpspath", "/usr/bin/jps", "--jinfopath", "/usr/bin/jinfo", "--javaname", "app01", "--pidfile", "/path/to/app01pidfile" ]
[plugin.metrics.jvm-app02]
command = [ "mackerel-plugin-jvm", "--jstatpath", "/usr/bin/jstat", "--jpspath", "/usr/bin/jps", "--jinfopath", "/usr/bin/jinfo", "--javaname", "app02", "--pidfile", "/path/to/app02pidfile" ]
Troubleshooting
Failed to run exec jinfo. jinfo command timed out.
in mackerel-agent log
- It is thought that a timeout occurred when executing the jinfo command from the plugin, due to temporary host load or other factors.
- If the output is continuous, please run the jinfo command manually to check the status.
- It may be possible to avoid this problem by adjusting the timeout value (timeout_seconds) of the monitoring rule. Please refer to Configuration for details.
Repository
https://github.com/mackerelio/mackerel-agent-plugins/tree/master/mackerel-plugin-jvm