SHARK4(1) BSD General Commands Manual SHARK4(1)
NAME
shark -- creates *.mshark profiles of system or process behavior for viewing with Shark.app.
SYNOPSIS
shark [-1] [-a process] [-b] [-c index] [-d path] [-e] [-f file] [-G] [-g] [-i] [-I interval] [-l] [-L]
[-m file] [-N] [-o basename] [-q] [-r] [-S limit] [-t] [-T limit] [-u] [-x] [executable
[args...]]
DESCRIPTION
shark helps you tune and understand your code for optimal performance. At the simplest level, shark
profiles the system to see how time is being spent. It can also produce profiles of hardware and soft-ware software
ware performance events such as cache misses, virtual memory activity, instruction dependency stalls,
system traces, and other types of profiles. Using these profiles, you can focus your optimization
efforts on performance-critical code.
shark creates a profile of execution behavior by periodically interrupting each processor in the system
and sampling the currently running process, thread and instruction address. Along with this contextual
information, shark records the values of the available hardware and software performance counters.
Each performance counter is capable of counting a wide variety of performance events. In the case of
processor and memory controller counters, these include detailed, low-level information that is other-wise otherwise
wise impossible to know without a simulator.
The profiles generated by shark are statistical in nature; they give a representative view of what was
running on the system during a sampling session. Samples can include all of the processes running on
the system from both user and supervisor code.
Sampling is controlled by:
Immediately (-i option) - sampling begins immediately and ends when either the current max sample limit
is reached or the launched/attached target process exits
Hotkey - option-esc to start/stop sampling, ctrl-esc to quit (available only to the currently logged in
user)
Remote - (-r option) - There are several ways to toggle profiling when shark is in 'remote' mode. 1: A
CHUD remote client program can be instrumented with calls to: chudStartRemotePerfMonitor()/chudStopRe-motePerfMonitor() chudStartRemotePerfMonitor()/chudStopRemotePerfMonitor()
motePerfMonitor() to start/stop sampling. 2: The utility chudRemoteCtrl(1) can be used on the command
line of a terminal to start or stop the collection of performance monitor samples. 3: The UNIX signals
SIGUSR1 and SIGUSR2 can be sent to shark via its process id (pid) number, to start or stop performance
monitoring. Sending the SIGUSR1 signal toggles the start and stop of sampling. Sending a SIGUSR2 stops
sampling and causes a session file to be generated if need be. When you are using shark over a remote
shell (rlogin, telnet, ssh, etc.) connection, you will need to run shark and the chudRemoteCtrl(1)
utility in the same session (remote shell). The UNIX signal method is the most reliable. And it works
from a separate shell logged into the same account as the shell running shark In fact the chudRemoteC-trl(1) chudRemoteCtrl(1)
trl(1) utility can send the appropriate UNIX signals to shark from a separate shell. But the most
direct way to send UNIX signals is by using the kill(1) utility:
for example: % kill -s USR1 <pid>
% chudRemoteCtrl -s <session_name> -k<pid>
will start sampling using SIGUSR1; and
% chudRemoteCtrl -e -k<pid>
will stop sampling using SIGUSR2, which also creates the session file (if any).
Profiling over a remote shell works very well if you have shark launch an executable that has been
instrumented with the CHUD functions. Typical instrumentation might look like:
//add the header file
#include <CHUD/CHUD.h>
//then in the main...
chudInitialize();
chudAcquireRemoteAccess();
//just before the code to be profiled
chudStartRemotePerfMonitor("some run label");
//just after the code to be profiled
chudStopRemotePerfMonitor();
//before the program exits:
chudReleaseRemoteAccess();
Network Sharing (-N option) - a message is sent to the shark program, from another computer on the net-work, network,
work, to toggle profiling. Typically, one system, on the network, is running Shark.app. The Shark.app
program will have been configured to manage other profiling "service" programs. shark is a profiling
service program when the '-N' option is given on the command line. In network sharing mode shark can
still be triggered by signals and by hotkeys on the local host. The sessions generated by shark will
be cached and delivered to the controlling Shark application when the Shark application requests the
session file, or as soon as it is available, if the Shark application requests automatic delivery of
sessions from the profiling services. One shark program can be run on each of many systems on the net-work. network.
work. One system running Shark.app can control profiling on all of the systems running shark simulta-neously. simultaneously.
neously.
OPTIONS
-a process Attach to a currently running process with the specified name or PID. If a process is not
given, shark can also optionally launch a new process from a specified executable. If nei-ther neither
ther -a process or an executable is specified, shark will wait for further input (either a
the start/stop hotkey, option-esc, or a CHUD remote monitoring start message if remote mon-itoring monitoring
itoring is enabled).
-r Enable remote monitoring mode. In this mode shark waits for a CHUD remote client program to
call chudStartRemotePerfMonitor()/chudStopRemotePerfMonitor() to start and stop sampling.
(see above for more details on this option)
-i Begin sampling immediately, exiting after a session has been taken.
-I interval
Change the per-sample time interval to this value. Enter the value as a number followed by
a suffix: for example 5m would set the per-sample time interval to 5 milliseconds. 50u
would change the per-sample time limit to 50 microseconds. 5s would change the per-sample
time limit to 5 seconds.
-S limit Change the sample limit to this <limit> number of samples.
-T limit Change the maximum time limit to this value. Enter the value as a number followed by a suf-fix: suffix:
fix: for example 500m would set the time limit to 500 milliseconds. 500000u would change
the time limit to 500000 microseconds. 22s would change the sampling time limit to 22 sec-onds. seconds.
onds.
-1 Sample only the target process (specified through -a process or the launched executable).
-x Ignore task will exit notifications. Normally shark will be notified whenever a process
(task) exits while it is sampling. This allows for all relevant symbol and other informa-tion information
tion required for later analysis to be gathered before allowing the exiting task to com-plete complete
plete exiting. The processing that occurs during a task exit notification can cause gaps
in the resulting profile.
-b Enable batch mode. By default, shark will exit after recording a single *.mshark session
file. This option allows you to record multiple sessions without exiting shark.
-q Quiet mode. Runs silently (no output to terminal) unless an error is encountered.
-o basename
Sets the basic file name used for *.mshark session files. By default this is "session",
which generates session files named session_{x}.mshark in the current working directory.
The 'basename' can contain relative path information, or absolute path information if the
'-d' option is not specified on the command line. shark will honor the file path specified
before the basename, provided ALL the directories in the path exist already. No directories
are created by shark.
-d path Sets the directory file path name used for *.mshark session files. By default this is not
set to anything. So shark generates session files in the current working directory. No
directories are created by shark. NOTE: If a directory path is set with this option, then
including a slash (/) as the first component of the basename argument (to the '-o' option,
above) will generate a fatal error.
-G Create a brief textual report from each analysis module that is active in the profiling
config. If an analysis module does not support plain text reporting a "<NO REPORT AVAIL-
ABLE>" message is printed. The text report will have the same name as the session except
the extension will be "...-report.txt" instead of ".mshark"
-g session file name(s)
Create a brief textual report from any analysis modules that are active in each session
file named on the command line. If an analysis module does not support plain text report-ing reporting
ing a "<NO REPORT AVAILABLE>" message is put in the report. The text report will have the
same name as the related session file except the extension will be "...-report.txt" instead
of ".mshark"
-t [session file name(s)]
Create a text output file representing the complete analysis from the session for each
analysis module active in the session. Note that not every analysis module supports full-text fulltext
text output. If a module does not support full-text output, the phrase:
<FULL-TEXT FORMAT NOT AVAILABLE> appears in the text file for that module. The full-text
output file will have the same name as the session except the extension will be
"...-full.txt" instead of ".mshark".
Session file names are optional; if omitted, full text reports will be generated for each
session you take. If included, no session will be taken - instead, text reports will be
generated from the given session file names.
The '-t' option and the '-G' option can both be used at the same time, since they create
different filenames.
-u Identify processes by name (the default behavior is to identify processes by PID).
-l Lists the available sampling configurations and exits. New sampling configurations can be
created with Shark.app (the GUI version of shark ). shark looks for user configurations in
~/Library/Application Support/Shark/Configs.
-L Similar to -l option, but adds detailed description of each configuration.
-c index Specifies the index of the sampling configuration to be used.
-m file Specifies the path to a shark sampling config (*.cfg) file to be used.
-f file Specifies the path to an executable, or (MachO) object file to be statically analyzed. This
file is used in conjunction with a shark -Static Analysis- config file. The config file
must be specified with the '-c' or '-m' options.
-N Enables Network Sharing mode in the shark program. Enabling network sharing does not dis-able disable
able any of the other methods for starting and stopping profiling.
-e List the current settings of search-path environment variables used by shark to locate var-ious various
ious types of files during session processing. There are currently three environment vari-ables: variables:
ables: SHARK_SEARCH_PATH_KEXT_FILES, SHARK_SEARCH_PATH_PATCH_FILES, and
SHARK_SEARCH_PATH_SOURCE_FILES. shark will search the colon delimited lists of file paths
for Kernel Extensions, Patch Files, and Source Files, respectively. NOTE: Even if no
search paths are specified for Kernel Extensions (SHARK_SEARCH_PATH_KEXT_FILES) some paths
will be listed; shark adds to these paths automatically.
BUGS
Please send your comments, suggestions and bug reports to: perftools-feedback@group.apple.com
SEE ALSO
chudRemoteCtrl(1), kill(1), /Library/Documentation/Applications/Shark/SharkUserGuide.pdf
April 2, 2008
|