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 namedjprofiler_imageswill 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
csvseparatoroption. -
.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.