https://github.com/lhotari/jfr-report-tool
Tool for creating reports from Java Flight Recorder dumps
https://github.com/lhotari/jfr-report-tool
Last synced: 9 months ago
JSON representation
Tool for creating reports from Java Flight Recorder dumps
- Host: GitHub
- URL: https://github.com/lhotari/jfr-report-tool
- Owner: lhotari
- License: apache-2.0
- Created: 2015-09-25T12:41:23.000Z (over 10 years ago)
- Default Branch: master
- Last Pushed: 2018-04-29T19:31:03.000Z (over 7 years ago)
- Last Synced: 2025-04-15T02:53:52.940Z (9 months ago)
- Language: Groovy
- Size: 164 KB
- Stars: 54
- Watchers: 3
- Forks: 11
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
- awesome-jvm - jfr-report-tool - Tool for creating reports from Java Flight Recorder dumps. (Profilers)
README
# jfr-report-tool
[](https://travis-ci.org/lhotari/jfr-report-tool)
Tool for creating reports from Java Flight Recorder dumps.
Influenced by https://github.com/chrishantha/jfr-flame-graph . Kudos to @chrishantha for the great work.
Uses [Java Flight Recorder internal API to read JFR dump files](http://hirt.se/blog/?p=446).
Uses [flamegraph.pl](https://raw.githubusercontent.com/brendangregg/FlameGraph/master/flamegraph.pl) from [FlameGraph](https://github.com/brendangregg/FlameGraph) for creating flamegraphs in SVG format.
## Requirements
`JAVA_HOME` environment variable must point to Oracle JDK 1.7.0_40+.
## Usage with provided shell script (requires bash)
```
./jfr-report-tool [dump_file.jfr]
```
The script will build the tool on first access using `./gradlew shadowJar` command. It will also use `curl` to download [flamegraph.pl](https://raw.githubusercontent.com/brendangregg/FlameGraph/master/flamegraph.pl) if it's not available on `PATH`.
```
usage: jfr-report-tool [-abcdefghilmnorsw] [jfrFile]
-a,--action Tool action. Valid choices:
flameGraph, stacks, topframes,
dumpinfo, recordtypes
--allocations Allocation flamegraph
-b,--begin Begin time
-c,--cutoff Cut off frame pattern
-d,--duration Duration of time window, splits
output in to multiple files
-e,--exclude Regexp exclude filter for methods
-f,--first-split First window duration half of
given duration
--flamegraph-command flamegraph.pl path
-g,--grep Regexp to include all stacks with
match in any frame
-h,--help Help
-i,--include Regexp include filter for methods
-l,--length Length of selected time
-m,--min Minimum number of samples
--min-samples-frame-depth Minimum samples sum taken at frame
depth
-n,--no-compress Don't compress package names
-o,--output Output file
-r,--reverse Process stacks in reverse order
-s,--sort Sort frames
-w,--width Width of flamegraph
Supported actions:
flameGraph creates flamegraph in svg format, default action
stacks creates flamegraph input file
topframes shows top methods
dumpinfo dump info
recordtypes dump record types
```
### Examples
#### Flamegraph
This creates a file `jfr_dump_file.jfr.svg` that is the flamegraph in SVG format. SVG files can be opened with most web browsers.
```
./jfr-report-tool jfr_dump_file.jfr
```
#### Disabling default filtering
```
./jfr-report-tool -e none -m 1 jfr_dump_file.jfr
```
By default, the tool removes all methods matching `^(java\.|sun\.|com\.sun\.|org\.codehaus\.groovy\.|groovy\.|org\.apache\.)` so that you can view hotspots in your own code. Use "-e none" to disable method filtering. By default, all stacks with 1 or 2 samples will be filtered. You can disable this be setting the `min` parameter to 1.
#### Allocations flamegraph
To visualize allocations, there is a new feature to render a flamegraph where each stacktrace is weighted with the allocation size made in each method. It uses the JFR `java/object_alloc_in_new_TLAB` and `java/object_alloc_outside_TLAB` events to get allocation data. These events are enabled when using `settings=profile` in `FlightRecorderOptions`.
See [Allocation Profiling in Java Mission Control](http://hirt.se/blog/?p=381) blog post for explanation of the events.
>Note that we, in the case of the (inside) TLAB allocation events, are not emitting an event for each and every location – that would be way too expensive. We are instead creating an event for the first allocation in a new TLAB. This means that we get a sampling of sorts of the thread local allocations taking place.
Since `java/object_alloc_in_new_TLAB` only capture the first allocation in a new TLAB, the events won't show all allocations. It's possible to pass `-XX:-UseTLAB` to record all allocations, but this adds a lot of overhead
to JFR profiling.
example of visualizing allocations with a flamegraph
```
./jfr-report-tool --allocations jfr_dump_file.jfr
```
## Java Flight Recorder
### Enabling Java Flight Recorder
Add these JVM startup parameters
```
-XX:+UnlockCommercialFeatures -XX:+FlightRecorder -XX:+UnlockDiagnosticVMOptions -XX:+DebugNonSafepoints -XX:FlightRecorderOptions=stackdepth=1024
```
Use this `FlightRecorderOptions` parameter to start recording from the start and create a dump on exit to the current directory:
```
-XX:FlightRecorderOptions=defaultrecording=true,settings=profile,disk=true,maxsize=500M,stackdepth=1024,dumponexit=true
```
This uses $JAVA_HOME/jre/lib/jfr/profile.jfc settings which has method sampling enabled.
### Controlling Java Flight Recorder at runtime from command line
`jcmd` is used to control JFR.
Help for all `jcmd` commands:
```
jcmd help
```
You can use `jps` to find the process id (PID) of the java process you want to profile.
The available commands are `JFR.stop`, `JFR.start`, `JFR.dump`, `JFR.check`
Help for `JFR.start`
```
jcmd help JFR.start
```
### Creating a recording by jcmd
starting recording with setting from $JAVA_HOME/jre/lib/jfr/profile.jfc
```
jcmd JFR.start name=myrecording settings=profile
```
dumping to file and continuing recording
```
jcmd JFR.dump name=myrecording filename=$PWD/mydump.jfr
```
### Customizing profiling settings
It's recommended to create a custom JFR settings file with highest sampling rate (10ms). [profiling.jfc](https://github.com/lhotari/gradle-profiling/blob/master/jfr/profiling.jfc) example.
You can use the Java Mission Control UI to edit JFR setting files. The feature is called "Java Flight Recording Template Manager".
### Controlling Java Flight Recorder at runtime from graphical user interface
Use `jmc` command to start the Java Mission Control UI. The UI can be used to do recordings.