Home

Table of contents

• Why yet another profiler?
• Basic Usage
  

Profiler modes:

• CPU profiling
  • Installing Debug Symbols
• Allocation profiling
• Java method profiling
• Wall clock profiling
• Embedded profiling as Java Agent

More info:

• Flame Graph visualization
• Profiling Java in a container
• Restrictions/Limitations
• Troubleshooting

Profiler Options

The following is a complete list of the command-line options accepted by profiler.sh script.

• start - starts profiling in semi-automatic mode, i.e. profiler will run until stop command is explicitly called.

• resume - starts or resumes earlier profiling session that has been stopped. All the collected data remains valid. The profiling options are not preserved between sessions, and should be specified again.

• stop - stops profiling and prints the report.

• check - check if the specified profiling event is available.

• status - prints profiling status: whether profiler is active and for how long.

• list - show the list of available profiling events. This option still requires PID, since supported events may differ depending on JVM version.

• -d N - the profiling duration, in seconds. If no start, resume, stop or status option is given, the profiler will run for the specified period of time and then automatically stop.
  Example: ./profiler.sh -d 30 8983

• -e event - the profiling event: cpu, alloc, lock, cache-misses etc. Use list to see the complete list of available events.

  In allocation profiling mode the top frame of every call trace is the class of the allocated object, and the counter is the heap pressure (the total size of allocated TLABs or objects outside TLAB).

  In lock profiling mode the top frame is the class of lock/monitor, and the counter is number of nanoseconds it took to enter this lock/monitor.

  Two special event types are supported on Linux: hardware breakpoints and kernel tracepoints:

  • -e mem:<func>[:rwx] sets read/write/exec breakpoint at function <func>. The format of mem event is the same as in perf-record. Execution breakpoints can be also specified by the function name, e.g. -e malloc will trace all calls of native malloc function.
  • -e trace:<id> sets a kernel tracepoint. It is possible to specify tracepoint symbolic name, e.g. -e syscalls:sys_enter_open will trace all open syscalls.

• -i N - sets the profiling interval in nanoseconds or in other units, if N is followed by ms (for milliseconds), us (for microseconds), or s (for seconds). Only CPU active time is counted. No samples are collected while CPU is idle. The default is 10000000 (10ms).
  Example: ./profiler.sh -i 500us 8983

• --alloc N - allocation profiling interval in bytes or in other units, if N is followed by k (kilobytes), m (megabytes), or g (gigabytes).

• --lock N - lock profiling threshold in nanoseconds (or other units). In lock profiling mode, record contended locks that the JVM has waited for longer than the specified duration.

• -j N - sets the Java stack profiling depth. This option will be ignored if N is greater than default 2048.
  Example: ./profiler.sh -j 30 8983

• -t - profile threads separately. Each stack trace will end with a frame that denotes a single thread.
  Example: ./profiler.sh -t 8983

• -s - print simple class names instead of FQN.

• -g - print method signatures.

• -a - annotate Java method names by adding _[j] suffix.

• -o fmt - specifies what information to dump when profiling ends. fmt can be one of the following options:

  • traces[=N] - dump call traces (at most N samples);
  • flat[=N] - dump flat profile (top N hot methods);
    can be combined with traces, e.g. traces=200,flat=200
  • jfr - dump events in Java Flight Recorder format readable by Java Mission Control. This does not require JDK commercial features to be enabled.
  • collapsed - dump collapsed call traces in the format used by FlameGraph script. This is a collection of call stacks, where each line is a semicolon separated list of frames followed by a counter.
  • flamegraph - produce Flame Graph in HTML format.
  • tree - produce Call Tree in HTML format.
    --reverse option will generate backtrace view.

• --total - count the total value of the collected metric instead of the number of samples, e.g. total allocation size.

• -I include, -X exclude - filter stack traces by the given pattern(s). -I defines the name pattern that must be present in the stack traces, while -X is the pattern that must not occur in any of stack traces in the output. -I and -X options can be specified multiple times. A pattern may begin or end with a star * that denotes any (possibly empty) sequence of characters.
  Example: ./profiler.sh -I 'Primes.*' -I 'java/*' -X '*Unsafe.park*' 8983

• --title TITLE, --minwidth PERCENT, --reverse - FlameGraph parameters.
  Example: ./profiler.sh -f profile.html --title "Sample CPU profile" --minwidth 0.5 8983

• -f FILENAME - the file name to dump the profile information to.
  %p in the file name is expanded to the PID of the target JVM;
  %t - to the timestamp at the time of command invocation.
  Example: ./profiler.sh -o collapsed -f /tmp/traces-%t.txt 8983

• --all-user - include only user-mode events. This option is helpful when kernel profiling is restricted by perf_event_paranoid settings.

• --cstack MODE - how to traverse native frames (C stack). Possible modes are fp (Frame Pointer), lbr (Last Branch Record, available on Haswell since Linux 4.1), and no (do not collect C stack).

  By default, C stack is shown in cpu, itimer, wall-clock and perf-events profiles. Java-level events like alloc and lock collect only Java stack.

• --begin function, --end function - automatically start/stop profiling when the specified native function is executed.

• --ttsp - time-to-safepoint profiling. An alias for
  --begin SafepointSynchronize::begin --end RuntimeService::record_safepoint_synchronized

• -v, --version - prints the version of profiler library. If PID is specified, gets the version of the library loaded into the given process.