docs/ProfilerOptions.md
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]
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. |
status | Print profiling status: whether profiler is active and for how long. |
metrics | Print profiler metrics in Prometheus format. |
list | Show the list of profiling events available for the target process specified with PID. |
| 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. |
-f FILENAME | file=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; | ||
%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 | ||
-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> | ||
--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 | ||
-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). |
--tlab | tlab | Use TLAB events for allocation profiling |
--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. |
--trace METHOD[:T] | trace=METHOD[:T] | Java method to be traced, optionally followed by a latency threshold. |
Example: --trace my.pkg.Class.Method:50ms. | ||
| Latency threshold defaults to 0 (all calls are profiled). Can be used multiple times. | ||
--lock TIME | lock=TIME | In lock profiling mode, sample contended locks whenever total lock wait time overflows the specified threshold. |
--nativelock TIME | nativelock=TIME | In native lock profiling mode, sample contended pthread locks (mutex/rwlock) whenever total lock wait time overflows the specified 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. | ||
--nobatch | nobatch | Disable wall clock profiling optimization. Async-profiler will emit one jdk.ExecutionSample event for each wall clock sample instead of batching them in a custom profiler.WallClockSample event. |
-j N | jstackdepth=N | Sets the maximum stack depth. The default is 2048. |
Example: asprof -j 30 8983 | ||
-F features | features=LIST | Comma separated (or + separated when launching as an agent) list of stack walking features. Supported features are:<ul><li>stats - log stack walking performance stats.</li><li>vtable - display targets of megamorphic virtual calls as an extra frame on top of vtable stub or itable stub.</li><li>comptask - display current compilation task (a Java method being compiled) in a JIT compiler stack trace.</li><li>pcaddr - display instruction addresses .</li></ul>More details here. |
-L level | loglevel=level | Log level: debug, info, warn, error or none. |
| N/A | log=FILENAME | Dedicated file for log messages. Used internally by asprof. |
| N/A | quiet | Do not log "Profiling started/stopped" message. Used internally by asprof. |
| N/A | server=ADDRESS | Start insecure HTTP server with the given IP address/port to control the profiler. This option can be specified as -agentpath argument only. Be careful not to expose async-profiler server in a public network. |
--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), 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 | N/A | 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. |
| --record-cpu | record-cpu | In perf_events profiling mode, instruct the profiler to capture which CPU a sample was taken on. |
| -v --version | version | Prints the version of profiler library. If PID is specified, gets the version of the library loaded into the given process. |
| 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 | ||
--proc INTERVAL | proc=INTERVAL | Collect statistics about other processes in the system. Default sampling interval is 30s. |
--all | all | Shorthand for enabling cpu, wall, alloc, live, lock, nativelock, nativemem, and proc profiling simultaneously. This can be combined with --alloc 2m --lock 10ms etc. to pass custom interval/threshold. It is also possible to combine it with -e argument to change the type of event being collected (default is cpu). This is not recommended for production, especially for continuous profiling. |
| 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.
| 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. |
-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. |
-l --lib | lib | Prepend library names to symbols, e.g. libjvm.so`JVM_DefineClassWithSource. |
--dot | dot | Dotted class names, e.g. java.lang.String instead of java/lang/String. |
--samples | samples | Count the number of samples. This is the default aggregation option. |
--total | total | Count the total value of the collected metric instead of the number of samples, e.g. total allocation size. |
-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 | ||
| N/A | mcache[=AGE] | Maximum age of the method name cache. Default is 0 (do not cache method names between profiling sessions). |
-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);
traces, e.g. traces=200,flat=200jfr - 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.otlp - dump events in OpenTelemetry format.It is possible to specify multiple dump options at the same time.