Uploaded image for project: 'JDK'
  1. JDK
  2. JDK-8306704

JFR: Summary views



    • CSR
    • Resolution: Approved
    • P3
    • 21
    • hotspot
    • None
    • jfr
    • behavioral
    • minimal
    • add/remove command in $JDK/bin
    • JDK



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


      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.


      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
      13:22:57 24648              svchost.exe                    
      13:22:57 6208               C:\Program Files\Notepad2\Notep
      13:22:57 17576              ...Data\Local\Temp\is-DDLKQ.tmp
      13:22:57 10576              ...\Temp\vscode-update-user-x64
      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.


      jfr view

       jfr view [--verbose]
                [--width <integer>]
                [--truncate <mode>]
                [--cell-height <integer>]
        --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)


       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)


        Issue Links



              egahlin Erik Gahlin
              egahlin Erik Gahlin
              Markus Grönlund
              0 Vote for this issue
              3 Start watching this issue