These options control aspects of how the experiment data is collected.
Limit the amount of profiling data recorded to size megabytes. The limit applies to the sum of all profiling data and tracing data, but not to sample points. The limit is only approximate, and can be exceeded.
When the limit is reached, no more profiling and tracing data is recorded but the experiment remains open until the target process terminates. If periodic sampling is enabled, sample points continue to be written.
The allowed values of size are:
Do not impose a size limit on the experiment.
Impose a limit of n megabytes. The value of n must be positive and greater than zero.
By default, there is no limit on the amount of data recorded.
To impose a limit of approximately 2 Gbytes, for example, specify –L 2000.
Control whether descendant processes should have their data recorded. Data is always collected on the founder process independent of the –F setting. The allowed values of option are:
Record experiments on all descendant processes.
Same as on
Do not record experiments on any descendant processes.
Record experiments on those descendant processes whose executable name matches the regular expression. Only the basename of the executable is used, not the full path. If the regex that you use contains blanks or characters interpreted by your shell, be sure to enclose the full regex argument in single quotes.
The -F on option is set by default so that the Collector follows processes created by calls to the functions fork(2), fork1(2), fork(3F), vfork(2), and exec(2) and its variants. The call to vfork is replaced internally by a call to fork1.
Descendant processes created by calls to system(3C), system(3F), sh(3F), posix_spawn(3p), posix_spawnp(3p), and popen(3C), and similar functions, and their associated descendant processes are also followed.
On Linux, descendants created by clone(2) without the CLONE_VM flag are followed by default. Descendants created with the CLONE_VM flag are treated as threads rather than processes and are always followed, independent of the –F setting.
If you specify the –F '= regexp' option, the Collector follows all descendant processes. The Collector creates a subexperiment when the descendant name or subexperiment name matches the specified regular expression. See the regexp(5) man page for information about regular expressions.
Examples using regular expressions:
To capture data on the descendant process of the first exec from the first fork from the first call to system in the founder, use: collect -F '=_x1_f1_x1'
To capture data on all the variants of exec, but not fork, use: collect -F '=.*_x[0-9]/*'
To capture data from a call to system ("echo hello") but not system ("goodbye"), use: collect -F '=echo hello'
For more information about how experiments for descendant processes are created and named, see Subexperiments.
For MPI experiments, descendants are also followed by default.
Performance Analyzer and the er_print utility automatically read experiments for descendant processes when the founder experiment is read, and show descendants in the data display.
To select the data of a particular subexperiment for display from the command line, specify the subexperiment path name explicitly as an argument to the er_print or analyzer commands. The specified path must include the founder experiment name and the descendant experiment name inside the founder directory.
For example, to see the data for the third fork of the test.1.er experiment:
er_print test.1.er/_f3.er
analyzer test.1.er/_f3.er
Alternatively, you can prepare an experiment group file with the explicit names of the descendant experiments in which you are interested. See Experiment Groups for more information.
You can also collect data on scripts and follow descendant processes of scripts. See Collecting Data From Scripts for more information.
Enable Java profiling when the target program is a JVM. The allowed values of option are:
Record profiling data for the JVM machine, and recognize methods compiled by the Java HotSpot virtual machine, and also record Java call stacks. This is the default.
Disable recording of Java profiling data. Profiling data for native callstacks will still be recorded.
Record profiling data for the JVM, and use the JVM installed in the specified path.
Specify additional arguments to be passed to the JVM used for profiling. If you specify the -J option, Java profiling (–j on) will be enabled. The java-argument must be enclosed in quotation marks if it contains more than one argument. It must consist of a set of tokens separated by blanks or tabs. Each token is passed as a separate argument to the JVM. Most arguments to the JVM must begin with a dash character (-).
Record a sample packet when the signal named signal is delivered to the process.
You can specify the signal by the full signal name, by the signal name without the initial letters SIG, or by the signal number. Do not use a signal that is used by the program or that would terminate execution. Suggested signals are SIGUSR1 and SIGUSR2. SIGPROF can be used even when clock-profiling is specified. Signals can be delivered to a process by the kill command.
If you use both the –l (a lower case L) and the –y options, you must use different signals for each option.
If you use this option and your program has its own signal handler, you should make sure that the signal that you specify with -l is passed on to the Collector’s signal handler and is not intercepted or ignored.
See the signal(3HEAD) man page for more information about signals.
Specify a time range for data collection.
The duration can be specified as a single number, with an optional m or s suffix, to indicate the time in minutes or seconds at which the experiment should be terminated. By default, the duration is in seconds. The duration can also be specified as two such numbers separated by a hyphen, which causes data collection to pause until the first time elapses. At that time, data collection begins. When the second time is reached, data collection terminates. If the second number is a zero, data will be collected after the initial pause until the end of the program's run. Even if the experiment is terminated, the target process is allowed to run to completion.
Leave the target process stopped on exit from the exec system call in order to allow a debugger to attach to it. The collect command prints a message with the process ID.
To attach a debugger to the target once it is stopped by collect, you can follow the procedure below.
Obtain the PID of the process from the message printed by the collect -x command
Invoke the collect command with the –P PID option to collect data.
Alternatively, you could do it manually with the following steps:
Start the debugger
Configure the debugger to ignore SIGPROF and, if you chose to collect hardware counter data, SIGEMT on Oracle Solaris or SIGIO on Linux
Attach to the process using the dbx attach command.
Set the collector parameters for the experiment you wish to collect
Issue the collector enable command
Issue the cont command to allow the target process to run
As the process runs under the control of the debugger, the Collector records an experiment.
Alternatively, you can attach to the process and collect an experiment using the collect -P PID command.
Control recording of data with the signal named signal. Whenever the signal is delivered to the process, it switches between the paused state, in which no data is recorded, and the recording state, in which data is recorded.
By default data collection begins in the paused state. If you specify the optional ,r flag, data collection begins in the resumed state which means profiling occurs immediately. Sample points are always recorded, regardless of the state of the –y option.
One use of the pause-resume signal is to start a target without collecting data, allowing it to reach steady-state, and then enabling the data collection.
The signal can be specified by the full signal name, by the signal name without the initial letters SIG, or by the signal number. Do not use a signal that is used by the program or that would terminate execution. Suggested signals are SIGUSR1 and SIGUSR2. SIGPROF can be used, even when clock-profiling is specified. Signals can be delivered to a process by the kill command.
If you use both the -l and the -y options, you must use different signals for each option.
When the -y option is used, the Collector is started in the recording state if the optional r argument is given. Otherwise, it is started in the paused state. If the -y option is not used, the Collector is started in the recording state.
If you use this option and your program has its own signal handler, make sure that the signal that you specify with -y is passed on to the Collector’s signal handler, and is not intercepted or ignored.
See the signal(3HEAD) man page for more information about signals.