JProfiler HelpDownload

Command Line Executables For Working With Snapshots

When using offline profiling to save snapshots programmatically, it may also be necessary to programmatically extract data or reports from those snapshots. JProfiler offers two separate command line executables, one for exporting views from a snapshot and one for comparing snapshots.

Exporting views from a snapshot

The executable bin/jpexport exports view data to various formats. If you execute it with the -help option, you will get information on the available view names and view options. For reasons of conciseness, duplicate help texts in the output below have been omitted. 

Usage: jpexport "snapshot file" [global options]
              "view name" [options] "output file"
              "view name" [options] "output file" ...

where "snapshot file" is a snapshot file with one of the extensions:
           .jps, .hprof, .hpz, .phd, .jfr
      "view name" is one of the view names listed below
      [options] is a list of options in the format -option=value
      "output file" is the output file for the export

Global options:
    -obfuscator=none|proguard|yguard
        Deobfuscate for the selected obfuscator. Defaults to "none", for other
        values the mappingFile option has to be specified.
    -mappingfile=<file>
        The mapping file for the selected obfuscator.
    -outputdir=<output directory>
        Base directory to be used when the output file for a view is a 
        relative file.
    -ignoreerrors=true|false
        Ignore errors that occur when options for a view cannot be set and 
        continue with the next view. The default value is "false", i.e., the 
        export is terminated, when the first error occurs.
    -csvseparator=<separator character>
        The field separator character for the CSV exports. Defaults to ','.
    -bitmap=false|true
        Where appropriate, export a bitmap image instead of SVG for the main 
        content. The default value is false.

Available view names and options:
* TelemetryHeap, TelemetryObjects, TelemetryThroughput, TelemetryGC, 
  TelemetryClasses, TelemetryThreads, TelemetryCPU
  Options:
    -format=html|csv
        Determines the output format of the exported file. If not present, the
        export format will be determined from the extension of the output 
        file.
    -minwidth=<number of pixels>
        Minimum width of the graph in pixels. The default value is 800.
    -minheight=<number of pixels>
        Minimum height of the graph in pixels. The default value is 600.

* Bookmarks, ThreadMonitor, CurrentMonitorUsage, MonitorUsageHistory
  Options:
    -format=html|csv

* AllObjects
  Options:
    -format=html|csv
    -viewfilters=<comma-separated list>
        Sets view filters for the export. If you set view filters, only the 
        specified packages and their sub-packages will be displayed by the 
        exported view.
    -viewfiltermode=startswith|endswith|contains|equals
        Sets the view filter mode. The default value is "contains".
    -viewfilteroptions=casesensitive
        Boolean options for the view filter. By default, no options are set.
    -aggregation=class|package|component
        Selects the aggregation level for the export. The default value is 
        classes.
    -expandpackages=true|false
        Expand package nodes in the package aggregation level to show 
        contained classes. The default value is "false". Has no effect for 
        other aggregation levels and with csv output format.

* RecordedObjects
  like AllObjects, but with additional options:
    -liveness=live|gc|all
        Selects the liveness mode for the export, i.e., whether to display 
        live objects, garbage collected objects or both. The default value is 
        live objects.

* AllocationTree
  Options:
    -format=html|xml
    -viewfilters=<comma-separated list>
    -viewfiltermode=startswith|endswith|contains|equals
    -viewfilteroptions=casesensitive
    -aggregation=method|class|package|component
        Selects the aggregation level for the export. The default value is 
        methods.
    -class=<fully qualified class name>
        Specifies the class for which the allocation data should be 
        calculated. If empty, allocations of all classes will be shown. Cannot
        be used together with the package option.
    -package=<fully qualified package name>
        Specifies the package for which the allocation data should be 
        calculated. If empty, allocations of all packages will be shown. 
        Appending .** to the package name will select packages recursively. 
        Cannot be used together with the class option.
    -liveness=live|gc|all

* AllocationHotSpots
  Options:
    -format=html|csv|xml
    -viewfilters=<comma-separated list>
    -viewfiltermode=startswith|endswith|contains|equals
    -viewfilteroptions=casesensitive
    -aggregation=method|class|package|component
    -class=<fully qualified class name>
    -package=<fully qualified package name>
    -liveness=live|gc|all
    -unprofiledclasses=separately|addtocalling
        Selects if unprofiled classes should be shown separately or be added 
        to the calling class. The default value is to show unprofiled classes 
        separately.
    -valuesummation=self|total
        Determines how the times for hot spots are calculated. Defaults to 
        "self".
    -expandbacktraces=true|false
        Expand backtraces in HTML or XML format. The default value is "false".

* ClassTracker
  like TelemetryHeap, but with additional options:
    -class
        The tracked class. If missing, the first tracked class is exported.

* CallTree
  Options:
    -format=html|xml
    -viewfilters=<comma-separated list>
    -viewfiltermode=startswith|endswith|contains|equals
    -viewfilteroptions=casesensitive
    -aggregation=method|class|package|component
    -threadgroup=<name of thread group>
        Selects the thread group for the export. If you specify "thread" as 
        well, the thread will only be searched in this thread group, otherwise
        the entire thread group will be shown.
    -thread=<name of thread>
        Selects the thread for the export. By default, the call tree is merged
        for all threads.
    -threadstatus=all|running|waiting|blocking|netio
        Selects the thread status for the export. The default value is 
        "running".

* HotSpots
  Options:
    -format=html|csv|xml
    -viewfilters=<comma-separated list>
    -viewfiltermode=startswith|endswith|contains|equals
    -viewfilteroptions=casesensitive
    -aggregation=method|class|package|component
    -threadgroup=<name of thread group>
    -thread=<name of thread>
    -threadstatus=all|running|waiting|blocking|netio
    -expandbacktraces=true|false
    -unprofiledclasses=separately|addtocalling
    -valuesummation=self|total

* OutlierDetection
  Options:
    -format=html|csv
    -threadstatus=all|running|waiting|blocking|netio
    -viewfilters=<comma-separated list>
    -viewfiltermode=startswith|endswith|contains|equals
    -viewfilteroptions=casesensitive

* Complexity
  Options:
    -format=html|csv|properties
    -fit=best|constant|linear|quadratic|cubic|exponential|logarithmic|n_log_n
        The fit that should be exported. The default value is "best". No curve
        fitting data is exported to CSV.
    -method=<method name>
        The method name for which the complexity graph should be exported. If 
        not given, the first method will be exported. Otherwise, the first 
        method name that starts with the given text will be exported.
    -width=<number of pixels>
    -height=<number of pixels>

* ThreadHistory
  like TelemetryHeap, but with changed options:
    -format=html

* MonitorUsageStatistics
  Options:
    -format=html|csv
    -type=monitors|threads|classes
        Selects the entity for which the monitor statistics should be 
        calculated. The default value is "monitors".

* ProbeTimeLine
  like ThreadHistory, but with additional options:
    -probeid=<id>
        The internal ID of the probe that should be exported. Run "jpexport 
        --listProbes" to list all available built-in probes and for an 
        explanation of custom probe names.

* ProbeControlObjects
  Options:
    -probeid=<id>
    -format=html|csv

* ProbeCallTree
  Options:
    -probeid=<id>
    -format=html|xml
    -viewfilters=<comma-separated list>
    -viewfiltermode=startswith|endswith|contains|equals|wildcard|regex
    -viewfilteroptions=exclude,casesensitive
    -aggregation=method|class|package|component
    -threadgroup=<name of thread group>
    -thread=<name of thread>
    -threadstatus=all|running|waiting|blocking|netio
        Selects the thread status for the export. The default value is "all".

* ProbeHotSpots
  like ProbeCallTree, but with additional or changed options:
    -format=html|csv|xml
    -expandbacktraces=true|false

* ProbeTelemetry
  like TelemetryHeap, but with additional options:
    -probeid=<id>
    -telemetrygroup
        Sets the one-based index of the telemetry group that should be 
        exported. This refers to the entries that you see in the drop-down 
        list above the probe telemetry view. The default value is "1".

* ProbeEvents
  Options:
    -probeid=<id>
    -format=html|csv|xml

* ProbeTracker
  like TelemetryHeap, but with additional options:
    -probeid=<id>
    -index=<number>
        Sets the zero-based index of the drop-down list that contains the 
        tracked elements. The default value is 0.

Comparing snapshots

The executable bin/jpcompare compares different snapshots and exports them to HTML or a machine-readable format. Its -help output is reproduced below, again without any duplicate explanations. 

Usage: jpcompare "snapshot file"[,"snapshot file",...] [global options]
              "comparison name" [options] "output file"
              "comparison name" [options] "output file" ...

where "snapshot file" is a snapshot file with one of the extensions:
           .jps, .hprof, .hpz, .phd, .jfr
      "comparison name" is one of the comparison names listed below
      [options] is a list of options in the format -option=value
      "output file" is the output file for the export

Global options:
    -outputdir=<output directory>
        Base directory to be used when the output file for a comparison is a 
        relative file.
    -ignoreerrors=true|false
        Ignore errors that occur when options for a comparison cannot be set 
        and continue with the next comparison. The default value is "false", 
        i.e., the export is terminated, when the first error occurs.
    -csvseparator=<separator character>
        The field separator character for the CSV exports. Defaults to ','.
    -bitmap=false|true
        Where appropriate, export a bitmap image instead of SVG for the main 
        content. The default value is false.
    -sortbytime=false|true
        Sort the specified snapshot files by modification time. The default 
        value is false.
    -listfile=<filename>
        Read a file that contains the paths of the snapshot files, one 
        snapshot file per line.

Available comparison names and options:
* Objects
  Options:
    -format=html|csv
        Determines the output format of the exported file. If not present, the
        export format will be determined from the extension of the output 
        file.
    -viewfilters=<comma-separated list>
        Sets view filters for the export. If you set view filters, only the 
        specified packages and their sub-packages will be displayed by the 
        exported view.
    -viewfiltermode=startswith|endswith|contains|equals
        Sets the view filter mode. The default value is "contains".
    -viewfilteroptions=casesensitive
        Boolean options for the view filter. By default, no options are set.
    -aggregation=class|package|component
        Selects the aggregation level for the export. The default value is 
        classes.
    -liveness=live|gc|all
        Selects the liveness mode for the export, i.e., whether to display 
        live objects, garbage collected objects or both. The default value is 
        live objects.
    -objects=recorded|heapwalker|all
        Compare recorded objects, objects in the heap walker, or object counts
        from all objects dumps. The default is recorded objects for .jps files
        and heapwalker for HPROF/PHD files.
    -dumpselection=first|last|label
        The all objects dump that is used for calculating the comparison. 
        Default is the last value.
    -label
        If dumpselection is set to 'label', the name of the label for which 
        the comparison should be calculated.

* AllocationHotSpots
  Options:
    -format=html|csv
    -viewfilters=<comma-separated list>
    -viewfiltermode=startswith|endswith|contains|equals
    -viewfilteroptions=casesensitive
    -aggregation=method|class|package|component
        Selects the aggregation level for the export. The default value is 
        methods.
    -liveness=live|gc|all
    -unprofiledclasses=separately|addtocalling
        Selects if unprofiled classes should be shown separately or be added 
        to the calling class. The default value is to show unprofiled classes 
        separately.
    -valuesummation=self|total
        Determines how the times for hot spots are calculated. Defaults to 
        "self".
    -classselection
        Calculate the comparison for a specific class or package. Packages are
        specified by appending '.*' for a single package or '.**' for 
        recursive packages. Specify a package with a wildcard, like 
        'java.awt.*'.

* AllocationTree
  Options:
    -format=html|xml
    -viewfilters=<comma-separated list>
    -viewfiltermode=startswith|endswith|contains|equals
    -viewfilteroptions=casesensitive
    -aggregation=method|class|package|component
    -liveness=live|gc|all
    -classselection

* HotSpots
  Options:
    -format=html|csv
    -viewfilters=<comma-separated list>
    -viewfiltermode=startswith|endswith|contains|equals
    -viewfilteroptions=casesensitive
    -firstthreadselection
        Calculate the comparison for a specific thread or thread group. 
        Specify thread groups like 'group.*' and threads in specific thread 
        groups like 'group.thread'. Escape dots in thread names with 
        backslashes.
    -secondthreadselection
        Calculate the comparison for a specific thread or thread group. Only 
        available if 'firstthreadselection' is set. If empty, the same value 
        as for 'firstthreadselection' will be used. Specify thread groups like
        'group.*' and threads in specific thread groups like 'group.thread'. 
        Escape dots in thread names with backslashes.
    -threadstatus=all|running|waiting|blocking|netio
        Selects the thread status for the export. The default value is 
        "running".
    -aggregation=method|class|package|component
    -differencecalculation=total|average
        Selects the difference calculation method for call times. The default 
        value is total times.
    -unprofiledclasses=separately|addtocalling
    -valuesummation=self|total

* CallTree
  Options:
    -format=html|xml
    -viewfilters=<comma-separated list>
    -viewfiltermode=startswith|endswith|contains|equals
    -viewfilteroptions=casesensitive
    -firstthreadselection
    -secondthreadselection
    -threadstatus=all|running|waiting|blocking|netio
    -aggregation=method|class|package|component
    -differencecalculation=total|average

* TelemetryHeap
  Options:
    -format=html|csv
    -minwidth=<number of pixels>
        Minimum width of the graph in pixels. The default value is 800.
    -minheight=<number of pixels>
        Minimum height of the graph in pixels. The default value is 600.
    -valuetype=current|maximum|bookmark
        Type of the value that is calculated for each snapshot. Default is the
        current value.
    -bookmarkname
        If valuetype is set to 'bookmark', the name of the bookmark for which 
        the value should be calculated.
    -measurements=maximum,free,used
        Measurements that are shown in the comparison graph. Concatenate 
        multiple values with commas. The default value is 'used'.
    -memorytype=heap|nonheap
        Type of the memory that should be analyzed. Default is 'heap'.
    -memorypool
        If a special memory pool should be analyzed, its name can be specified
        with this parameter. The default is empty, i.e. no special memory 
        pool.

* TelemetryObjects
  Options:
    -format=html|csv
    -minwidth=<number of pixels>
    -minheight=<number of pixels>
    -valuetype=current|maximum|bookmark
    -bookmarkname
    -measurements=total,nonarrays,arrays
        Measurements that are shown in the comparison graph. Concatenate 
        multiple values with commas. The default value is 'total'.

* TelemetryClasses
  like TelemetryObjects, but with changed options:
    -measurements=total,filtered,unfiltered

* TelemetryThreads
  like TelemetryObjects, but with changed options:
    -measurements=total,runnable,blocked,netio,waiting

* ProbeHotSpots
  Options:
    -format=html|csv
    -viewfilters=<comma-separated list>
    -viewfiltermode=startswith|endswith|contains|equals|wildcard|regex
    -viewfilteroptions=exclude,casesensitive
    -firstthreadselection
    -secondthreadselection
    -threadstatus=all|running|waiting|blocking|netio
    -aggregation=method|class|package|component
    -differencecalculation=total|average
    -probeid=<id>
        The internal ID of the probe that should be exported. Run "jpexport 
        --listProbes" to list all available built-in probes and for an 
        explanation of custom probe names.

* ProbeCallTree
  like ProbeHotSpots, but with changed options:
    -format=html|xml

* ProbeTelemetry
  like TelemetryObjects, but with additional or changed options:
    -measurements
        The one-based indices of the measurements in the telemetry group that 
        are shown in the comparison graph. Concatenate multiple values with 
        commas, like "1,2". The default value is to show all measurements.
    -probeid=<id>
    -telemetrygroup
        Sets the one-based index of the telemetry group that should be 
        exported. This refers to the entries that you see in the drop-down 
        list above the probe telemetry view. The default value is "1".

Automatic output formats

Most views and comparisons support multiple output formats. By default, the output format is deduced from the extension of the output file:

  • .html

    The view or comparison is exported as an HTML file. A directory named jprofiler_images will be created that contains images used in the HTML page.

  • .csv

    The data is exported as CSV data where the first line contains the column names.

    When using Microsoft Excel, CSV is not a stable format. Microsoft Excel on Windows takes the separator character from the regional settings. JProfiler uses a semicolon as the separator in locales that use a comma as a decimal separator and a comma in locales that use a dot as a decimal separator. If you need to override the CSV separator character, you can do so by setting the global csvseparator option.

  • .xml

    The data is exported as XML. The data format is self-descriptive.

If you would like to use different extensions, you can use the format option to override the choice of the output format.

Analyzing snapshots

If the generated snapshots have heap dumps in them, you can use the bin/jpanalyze executable to prepare the heap dump analysis in advance. Opening the snapshot in the JProfiler GUI will then be very fast. The usage information of the tool is shown below: 

Usage: jpanalyze [options] "snapshot file" ["snapshot file" ...]

where "snapshot file" is a snapshot file with one of the extensions:
           .jps, .hprof, .hpz, .phd, .jfr
      [options] is a list of options in the format -option=value

Options:
    -obfuscator=none|proguard|yguard
        Deobfuscate for the selected obfuscator. Defaults to "none", for other
        values the mappingFile option has to be specified.
    -mappingfile=<file>
        The mapping file for the selected obfuscator.
    -removeunreferenced=true|false
        If unreferenced or weakly referenced objects should be removed.
    -retained=true|false
        Calculate retained sizes (biggest objects). removeunreferenced will be
        set to true.
    -retainsoft=true|false
        If unreferenced objects are removed, specifies if soft references 
        should be retained.
    -retainweak=true|false
        If unreferenced objects are removed, specifies if weak references 
        should be retained.
    -retainphantom=true|false
        If unreferenced objects are removed, specifies if phantom references 
        should be retained.
    -retainfinalizer=true|false
        If unreferenced objects are removed, specifies if finalizer references
        should be retained.

The removeUnreferenced, the retained and all the retain* command line options correspond to the options in the heap walker options dialog.