Skip to content

Latest commit

 

History

History
116 lines (96 loc) · 30.1 KB

ProfilerOptions.md

File metadata and controls

116 lines (96 loc) · 30.1 KB

Profiler options

The below tables list the profiler options available with asprof and also when launching as an agent. Some tables are output specific, which means some options are applicable to only one or more output formats but not all.

Usage: asprof [action] [options] [PID]

Actions

The below options are actions for async-profiler and common for both asprof binary and when launching as an agent.

Option Description
start Start profiling in semi-automatic mode, i.e. profiler will run until stop command is explicitly called.
resume Start or resume 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 Stop profiling and print the report.
dump Dump collected data without stopping profiling session.
check Check if the specified profiling event is available.
status Print profiling status: whether profiler is active and for how long.
meminfo Print used memory statistics.
list Show the list of profiling events available for the target process specified with PID.

Options applicable to any output format

asprof Launch as agent Description
-o fmt fmt Specifies what information to dump when profiling ends. For various dump option details, please refer to Dump Option Appendix.
-d N N/A asprof-only option designed for interactive use. It is a shortcut for running 3 actions: start, sleep for N seconds, stop. 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: asprof -d 30 <pid>
--timeout N timeout=N The profiling duration, in seconds. The profiler will run for the specified period of time and then automatically stop.
Example: java -agentpath:/path/to/libasyncProfiler.so=start,event=cpu,timeout=30,file=profile.html <application>
-e --event EVENT event=EVENT The profiling event: cpu, alloc, nativemem, lock, cache-misses etc. Use list to see the complete list of available events.
Please refer to Profiling Modes for additional information.
-i --interval N interval=N Interval has different meaning depending on the event. For CPU profiling, it's CPU time in nanoseconds. In wall clock mode, it's wall clock time. For Java method profiling or native function profiling, it's number of calls. For PMU profiling, it's number of events. Time intervals may be followed by s for seconds, ms for milliseconds, us for microseconds or ns for nanoseconds.
Example: asprof -e cpu -i 5ms 8983
--alloc N alloc=N Allocation profiling interval in bytes or in other units, if N is followed by k (kilobytes), m (megabytes), or g (gigabytes).
--live live Retain allocation samples with live objects only (object that have not been collected by the end of profiling session). Useful for finding Java heap memory leaks.
--nativemem N nativemem=N Native memory allocation profiling. N, if specified is the interval in bytes or in other units, if N is followed by k (kilobytes), m (megabytes), or g (gigabytes). Default N is 0.
--nofree nofree Will not record free calls in native memory allocation profiling. This is relevant when tracking memory leaks is not important and there are lots of free calls.
--lock DURATION lock=DURATION In lock profiling mode, sample contended locks when total lock duration overflows the threshold.
--wall INTERVAL wall=INTERVAL Wall clock profiling interval. Use this option instead of -e wall to enable wall clock profiling with another event, typically cpu.
Example: asprof -e cpu --wall 100ms -f combined.jfr 8983.
-j N jstackdepth=N Sets the maximum stack depth. The default is 2048.
Example: asprof -j 30 8983
-I PATTERN include=PATTERN Filter stack traces by the given pattern(s). -I defines the name pattern that must be present in the stack traces. -I can be specified multiple times. A pattern may begin or end with a star * that denotes any (possibly empty) sequence of characters.
Example: asprof -I 'Primes.*' -I 'java/*' 8983
-X PATTERN exclude=PATTERN Filter stack traces by the given pattern(s). -X defines the name pattern that must not occur in any of stack traces in the output. -X can be specified multiple times. A pattern may begin or end with a star * that denotes any (possibly empty) sequence of characters.
Example: asprof -X '*Unsafe.park*' 8983
-L level loglevel=level Log level: debug, info, warn, error or none.
-F features features=LIST Comma separated (or + separated when launching as an agent) list of stack walking features. Supported features are:
  • stats - log stack walking performance stats.
  • vtable - display targets of megamorphic virtual calls as an extra frame on top of vtable stub or itable stub.
  • comptask - display current compilation task (a Java method being compiled) in a JIT compiler stack trace.
  • pcaddr - display instruction addresses .
More details here.
-f FILENAME file 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;
%n{MAX} - to the sequence number;
%{ENV} - to the value of the given environment variable.
Example: asprof -o collapsed -f /tmp/traces-%t.txt 8983
--loop TIME loop=TIME Run profiler in a loop (continuous profiling). The argument is either a clock time (hh:mm:ss) or a loop duration in seconds, minutes, hours, or days. Make sure the filename includes a timestamp pattern, or the output will be overwritten on each iteration.
Example: asprof --loop 1h -f /var/log/profile-%t.jfr 8983
--all-user alluser Include only user-mode events. This option is helpful when kernel profiling is restricted by perf_event_paranoid settings.
--sched sched Group threads by Linux-specific scheduling policy: BATCH/IDLE/OTHER.
--cstack MODE cstack=MODE How to walk native frames (C stack). Possible modes are fp (Frame Pointer), dwarf (DWARF unwind info), lbr (Last Branch Record, available on Haswell since Linux 4.1), vm, vmx (HotSpot VM Structs) and no (do not collect C stack).

By default, C stack is shown in cpu, ctimer, wall-clock and perf-events profiles. Java-level events like alloc and lock collect only Java stack.
--signal NUM signal=NUM Use alternative signal for cpu or wall clock profiling. To change both signals, specify two numbers separated by a slash: --signal SIGCPU/SIGWALL.
--clock SOURCE clock=SOURCE Clock source for JFR timestamps: tsc (default) or monotonic (equivalent for CLOCK_MONOTONIC).
--begin function begin=FUNCTION Automatically start profiling when the specified native function is executed.
--end function end=FUNCTION Automatically stop profiling when the specified native function is executed.
--ttsp ttsp Time-to-safepoint profiling. An alias for --begin SafepointSynchronize::begin --end RuntimeService::record_safepoint_synchronized.
It is not a separate event type, but rather a constraint. Whatever event type you choose (e.g. cpu or wall), the profiler will work as usual, except that only events between the safepoint request and the start of the VM operation will be recorded.
--nostop nostop Record profiling window between --begin and --end, but do not stop profiling outside window.
--libpath PATH libpath=PATH Full path to libasyncProfiler.so (useful when profiling a container from the host).
--filter FILTER filter=FILTER In the wall-clock profiling mode, profile only threads with the specified ids.
Example: asprof -e wall -d 30 --filter 120-127,132,134 Computey
--fdtransfer fdtransfer Run a background process that provides access to perf_events to an unprivileged process. --fdtransfer is useful for profiling a process in a container (which lacks access to perf_events) from the host.
See Profiling Java in a container.
--target-cpu target-cpu In perf_events profiling mode, instruct the profiler to only sample threads running on the specified CPU, defaults to -1.
Example: asprof --target-cpu 3.
-v --version version Prints the version of profiler library. If PID is specified, gets the version of the library loaded into the given process.

Options applicable to JFR output only

asprof Launch as agent Description
--chunksize N chunksize=N Approximate size for a single JFR chunk. A new chunk will be started whenever specified size is reached. The default chunksize is 100MB.
Example: asprof -f profile.jfr --chunksize 100m 8983
--chunktime N chunktime=N Approximate time limit for a single JFR chunk. A new chunk will be started whenever specified time limit is reached. The default chunktime is 1 hour.
Example: asprof -f profile.jfr --chunktime 1h 8983
--jfropts OPTIONS jfropts=OPTIONS Comma separated list of JFR recording options. Currently, the only available option is mem supported on Linux 3.17+. mem enables accumulating events in memory instead of flushing synchronously to a file.
--jfrsync CONFIG jfrsync[=CONFIG] Start Java Flight Recording with the given configuration synchronously with the profiler. The output .jfr file will include all regular JFR events, except that execution samples will be obtained from async-profiler. This option implies -o jfr.
CONFIG is a predefined JFR profile or a JFR configuration file (.jfc) or a list of JFR events started with +.

Example: asprof -e cpu --jfrsync profile -f combined.jfr 8983

Options applicable to FlameGraph and Tree view outputs only

asprof Launch as agent Description
--title TITLE title=TITLE Custom title of a FlameGraph.
Example: asprof -f profile.html --title "Sample CPU profile" 8983
--minwidth PERCENT minwidth=PERCENT Minimum frame width as a percentage. Smaller frames will not be visible.
Example: asprof -f profile.html --minwidth 0.5 8983
--reverse reverse Reverse stack traces (defaults to icicle graph).
Example: asprof -f profile.html --reverse 8983
--inverted inverted Toggles the layout for reversed stacktraces from icicle to flamegraph and for default stacktraces from flamegraph to icicle.
Example: asprof -f profile.html --inverted 8983

Notice that --reverse and --inverted are orthogonal settings. By default, flamegraphs grow from bottom to top (because flames grow from bottom to top). The outermost frames (e.g. the main() function) are shown at the bottom while the innermost, leaf frames are shown at the top. If such a flame graph is mirrored on the y-axis, it becomes an icicle graph (icicles grow top-down). The default setting for this layout can be toggled with the --inverted option when the graph is created or changed later with the Invert button which is located in the upper-left corner of the generated HTML page, when the graph is displayed.

By default, async-profiler merges stack traces starting from the outermost (e.g. main()) frames and displays them from bottom to top in a flamegraph. The --reverse option can be used to create reverse stack traces, i.e. merge them starting with the innermost, leaf frames. By default, reversed stack traces are displayed from top to bottom as icicle graphs. The default layout setting for both, normal and reversed stack traces can be changed with the --inverted option.

Options applicable to any output format except JFR

asprof Launch as agent Description
-t --threads threads Profile threads separately. Each stack trace will end with a frame that denotes a single thread.
Example: asprof -t 8983
-s --simple simple Print simple class names instead of fully qualified names.
-n --norm norm Normalize names of hidden classes / lambdas.
-g --sig sig Print method signatures.
-l --lib lib Prepend library names to symbols, e.g. libjvm.so`JVM_DefineClassWithSource.
--total total Count the total value of the collected metric instead of the number of samples, e.g. total allocation size.
-a --ann ann Annotate JIT compiled methods with _[j], inlined methods with _[i], interpreted methods with _[0] and C1 compiled methods with _[1]. FlameGraph and Tree view will color frames depending on their type regardless of this option.

Appendix

Dump Option

-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 JDK Flight Recorder format readable by JDK Mission Control.
  • 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.

It is possible to specify multiple dump options at the same time.