github.com/mackerelio/mackerel-agent-plugins@v0.89.3/mackerel-plugin-jvm/README.md (about)

     1  mackerel-plugin-jvm
     2  ===================
     3  
     4  JVM(jstat) custom metrics plugin for mackerel.io agent.
     5  
     6  ## Synopsis
     7  
     8  ```shell
     9  mackerel-plugin-jvm -javaname=<javaname> [-pidfile=</path/to/pidfile>] [-jstatpath=</path/to/jstat] [-jpspath=/path/to/jps] [-jinfopath=/path/to/jinfo] [-remote=<host:port>] [-metric-key=<metric key>] [-metric-label=<metric label>]
    10  ```
    11  
    12  ## Requirements
    13  
    14  - JVM 1.6 or higher
    15  
    16  ## Example of mackerel-agent.conf
    17  
    18  ```
    19  [plugin.metrics.jvm]
    20  command = "/path/to/mackerel-plugin-jvm -javaname=NettyServer -jstatpath=/usr/bin/jstat -jpspath=/usr/bin/jps -jinfopath=/usr/bin/jinfo"
    21  user = "SOME_USER_NAME"
    22  ```
    23  
    24  ## Monitoring remote JVM
    25  
    26  This plugin can retrieve metrics from remote jstatd with rmi protocol by setting `-remote` option.
    27  In this case, following limitations are applied:
    28  - jps and jstat commands must be executable localy from this plugin
    29  - 'CMS Initiating Occupancy Fraction' metric cannot be retrieved remotely
    30  
    31  ## About javaname
    32  
    33  You can check javaname by jps command.
    34  
    35  ```shell
    36  # jps
    37  14203 NettyServer
    38  14822 Jps
    39  ```
    40  
    41  Please choose an arbitrary name as `javaname` when you use `pidfile` option. It is used as a mertric name and graph label.
    42  
    43  ## User to execute this plugin
    44  
    45  This plugin (as well as the jps command explained above) must be executed by the user who executes the target Java application process, while mackerel-agent usually runs under root privilege.
    46  Since the executing user may not be root, you are required to specify the user in `mackerel-agent-conf` as shown above.
    47  
    48  ## About the `PerfDisableSharedMem` JVM option issue
    49  
    50  Since there is a performance issue called [the four month bug](https://www.evanjones.ca/jvm-mmap-pause.html), several middlewares specify the `-XX:+PerfDisableSharedMem` JVM option as default.
    51  When the JVM option is enabled, this plugin is no longer able to work because which depends `jps` and `jstat` JDK tools.
    52  
    53  ## References
    54  
    55  - [Metric plugins - mackerel-plugin-jvm - Mackerel Docs](https://mackerel.io/docs/entry/plugins/mackerel-plugin-jvm)
    56  - https://github.com/sensu/sensu-community-plugins/blob/master/plugins/java/jstat-metrics.py
    57  - http://docs.oracle.com/javase/7/docs/technotes/tools/share/jstat.html
    58  - https://github.com/kazeburo/jstat2gf