Summary

Add commands to the jfr tool and jcmd to display predefined views of JFR data.

Problem

Today, users can visualize event data in JDK Mission Control (JMC), but this requires dumping a recording file, downloading it to the local machine, starting JMC and browsing to the correct view. This process is a bit cumbersome, and users may instead resort to other, more accessible means, such as thread dumps (jcmd Thread.print), which have more overhead and provides less information.

Furthermore, the views available in JMC have not been updated to reflect new events added in the last five years, perhaps because of a lack of knowledge on building Mission Control and using Eclipse technologies.

Visualization is also important when creating new events to validate the design and correctness of the data.

Solution

Add a command called 'view' to the jfr tool that displays predefined views declared in a file called view.ini located in the jdk.jfr module. This file is unavailable to users but can be edited by JDK engineers. When a new event is added to the JDK, an accompanying view can be created by adding a query to the file. More information about the query syntax can be found in JDK-8308230, but it does not impact this CSR.

Example usage:

$ jfr view pinned-threads file.jfr
...
$ jfr view --verbose finalizers file.jfr 
...
$ jfr view --width 120 started-processes file.jfr
...
$ jfr view allocation-by-site file.jfr

                                     Allocation by Site

Method                                                  Allocation Pressure
------------------------------------------------------- -------------------
java.lang.StringUTF16.compress(char[], int, int)                     37.50%
java.lang.Integer.valueOf(int)                                       13.75%
spec.jbb.infra.Util.TransactionLogBuffer.getLine(...)                 9.22%
java.math.BigDecimal.valueOf(long, int)                               8.92%
spec.jbb.CustomerReportTransaction.process(...)                       7.55%
java.math.BigDecimal.layoutChars(boolean)                             5.71%
...

If the text overflows, the table width, cell height and truncation mode can be set using the options --width, --cell-height and --truncation. Instead of a view, the name of an event type can also be specified.

Example usage

$ jfr view --cell-height 3 --width 60 --truncate beginning jdk.SystemProcess
                   System Process

Time     Process Identifier Command Line                   
-------- ------------------ -------------------------------
13:22:57 9184               WmiPrvSE.exe                   
13:22:57 18556              svchost.exe                    
13:22:57 20424              C:\Windows\System32\RuntimeBrok
                            er.exe                         
13:22:57 24648              svchost.exe                    
13:22:57 6208               C:\Program Files\Notepad2\Notep
                            ad2.exe                        
13:22:57 17576              ...Data\Local\Temp\is-DDLKQ.tmp
                            \CodeSetup-stable-ee2b180d582a7
                            f601fa6ecfdad8d9fd269ab1884.tmp
13:22:57 10576              ...\Temp\vscode-update-user-x64
                            \CodeSetup-stable-ee2b180d582a7
                            f601fa6ecfdad8d9fd269ab1884.exe
13:22:57 21880              svchost.exe                   

The diagnostic command JFR.view behaves similarly to 'jfr view' but operates against a live JVM. The benefit of a diagnostic command is convenience and reduced overhead since data don't need to be dumped into a file before constructing an aggregated view. The overhead of the safepoint required to rotate a file during a dump can also be avoided. For JFR.view to display a result, a recording must be started before the command is executed. If no data is available in the JFR disk repository, the command will fail with an error message explaining a recording must be started.

By default, a view will cover the last 32 MB of data, although not further back than 10 minutes. To set a custom time range, users can set the parameters maxage and maxsize. They work similarly to the maxage and maxsize parameters for the JFR.dump command.

Example usage:

$ jcmd 1739 JFR.view hot-methods maxage=20m

                         Java methods that execute the most

Method                                                        Samples Percent
------------------------------------------------------------- ------- -------
sun.java2d.marlin.Renderer._endRendering(...)                    1659  42.99%
sun.java2d.marlin.MarlinTileGenerator.getAlphaRLE(...)            592  15.34%
sun.java2d.marlin.MarlinCache.copyAARowRLE_WithBlockFlags(...)    447  11.58%
sun.java2d.marlin.MarlinCache.copyAARowNoRLE(...)                 246   6.37%
sun.java2d.marlin.Renderer.addLine(...)                            89   2.31%
sun.java2d.marlin.Renderer.copyAARow(...)                          86   2.23%
sun.java2d.marlin.ArrayCacheInt.fill(...)                          73   1.89%
...

To list available views, the commands 'jfr view' or 'JFR.view' can be executed without parameters. Also, the help commands for the tools can be used, for example, 'jfr help view'. Initially, the tools will come with about 75 predefined views, with more to be added later.

Specification

jfr view

 jfr view [--verbose]
          [--width <integer>]
          [--truncate <mode>]
          [--cell-height <integer>]
          <view>
          <file>

  --verbose               Displays the query that makes up the view

  --width <integer>       The width of the view in characters. Default value depends on the view

  --truncate <mode>       How to truncate content that exceeds space in a table cell.
                          Mode can be 'beginning' or 'end'. Default value is 'end'

  --cell-height <integer> Maximum number of rows in a table cell. Default value depends on the view

  <view>                  Name of the view or event type to display. See list below for
                          available views

  <file>                  Location of the recording file (.jfr)

JFR.view

 cell-height   (Optional) Maximum number of rows in a table cell. (INTEGER, no default value)

 maxage        (Optional) Length of time for the view to span. (INTEGER followed by
               's' for seconds 'm' for minutes or 'h' for hours, default value is 10m)

 maxsize       (Optional) Maximum size for the view to span in bytes if one of
               the following suffixes is not used: 'm' or 'M' for megabytes OR
               'g' or 'G' for gigabytes. (STRING, default value is 32MB)

 truncate      (Optional) How to truncate content that exceeds space in a table cell.
               Mode can be 'beginning' or 'end'. (STRING, default value 'end')

 verbose       (Optional) Displays the query that makes up the view.
               (BOOLEAN, default value false)

 <view>        (Mandatory) Name of the view or event type to display.
               See list below for available views. (STRING, no default value)

 width         (Optional) The width of the view in characters
               (INTEGER, no default value)