Manual Pages for UNIX Darwin command on man shark

SHARK4(1) BSD General Commands Manual SHARK4(1)

NAME

sshhaarrkk - creates *.mshark profiles of system or process behavior for

viewing with Shark.app.

SYNOPSIS

sshhaarrkk [-11] [-aa process] [-bb] [-cc index] [-dd path] [-ee] [-ff file] [-GG]

[-gg] [-ii] [-II interval] [-ll] [-LL] [-mm file] [-NN] [-oo basename] [-qq]

[-rr] [-SS limit] [-tt] [-TT limit] [-uu] [-vv] [-xx] [executable

[args...]]

DESCRIPTION

sshhaarrkk helps you tune and understand your code for optimal performance. At the simplest level, sshhaarrkk profiles the system to see how time is being spent. It can also produce profiles of hardware and software performance

events such as cache misses, virtual memory activity, instruction depen-

dency stalls, system traces, and other types of profiles. Using these

profiles, you can focus your optimization efforts on performance-critical

code.

sshhaarrkk creates a profile of execution behavior by periodically interrupt-

ing each processor in the system and sampling the currently running process, thread and instruction address. Along with this contextual

information, sshhaarrkk records the values of the available hardware and soft-

ware performance counters. Each performance counter is capable of count-

ing a wide variety of performance events. In the case of processor and

memory controller counters, these include detailed, low-level information

that is otherwise impossible to know without a simulator. The profiles generated by sshhaarrkk 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

sshhaarrkk is in 'remote' mode. 1: A CHUD remote client program can be instru-

mented with calls to: chudStartRemotePerfMonitor()/chudStopRemotePerfMon-

itor() 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 sshhaarrkk via its process id (pid) number, to start or stop per-

formance 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 sshhaarrkk over a remote shell (rlogin, telnet, ssh, etc.) connection, you will need to run sshhaarrkk 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 sshhaarrkk In fact the chudRemoteCtrl(1) utility can send the appropriate UNIX signals to sshhaarrkk 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

% chudRemoteCtrl -s -k

will start sampling using SIGUSR1; and

% chudRemoteCtrl -e -k

will stop sampling using SIGUSR2, which also creates the session file (if any). Profiling over a remote shell works very well if you have sshhaarrkk launch an executable that has been instrumented with the CHUD functions. Typical instrumentation might look like: //add the header file

#include

//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 sshhaarrkk program,

from another computer on the network, 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. sshhaarrkk

is a profiling service program when the '-N' option is given on the com-

mand line. In network sharing mode sshhaarrkk can still be triggered by sig-

nals and by hotkeys on the local host. The sessions generated by sshhaarrkk 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 ses-

sions from the profiling services. One sshhaarrkk program can be run on each of many systems on the network. One system running Shark.app can control profiling on all of the systems running sshhaarrkk simultaneously. OOPPTTIIOONNSS

-11 Sample only the target process (specified through -a process

or the launched executable).

-aa process Attach to a currently running process with the specified name

or PID. If a process is not given, sshhaarrkk can also optionally launch a new process from a specified executable. If neither

-a process or an executable is specified, sshhaarrkk will wait for

further input (either a the start/stop hotkey, option-esc, or

a CHUD remote monitoring start message if remote monitoring is enabled).

-bb Enable batch mode. By default, sshhaarrkk will exit after record-

ing a single *.mshark session file. This option allows you

to record multiple sessions without exiting sshhaarrkk.

-cc index Specifies the index of the sampling configuration to be used.

-dd path Sets the directory file path name used for *.mshark session

files. By default this is not set to anything. So sshhaarrkk gen-

erates session files in the current working directory. No

directories are created by sshhaarrkk. 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.

-ee List the current settings of search-path environment vari-

ables used by sshhaarrkk to locate various types of files during session processing. There are currently three environment variables: SHARKSEARCHPATHKEXTFILES, SHARKSEARCHPATHPATCHFILES, and SHARKSEARCHPATHSOURCEFILES. sshhaarrkk 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 (SHARKSEARCHPATHKEXTFILES) some paths will be listed; sshhaarrkk adds to these paths automatically.

-ff file Specifies the path to an executable, or (MachO) object file

to be statically analyzed. This file is used in conjunction

with a sshhaarrkk -Static Analysis- config file. The config file

must be specified with the '-c' or '-m' options.

-GG 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 " 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"

-gg 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 reporting a "" 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"

-ii Begin sampling immediately, exiting after a session has been

taken.

-II 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.

-ll Lists the available sampling configurations and exits. New

sampling configurations can be created with Shark.app (the GUI version of sshhaarrkk ). sshhaarrkk looks for user configurations in ~/Library/Application Support/Shark/Configs.

-LL Similar to -l option, but adds detailed description of each

configuration.

-mm file Specifies the path to a sshhaarrkk sampling config (*.cfg) file to

be used.

-NN Enables Network Sharing mode in the sshhaarrkk program. Enabling

network sharing does not disable any of the other methods for starting and stopping profiling.

-oo 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. sshhaarrkk will honor the file path speci-

fied before the basename, provided ALL the directories in the path exist already. No directories are created by sshhaarrkk.

-qq Quiet mode. Runs silently (no output to terminal) unless an

error is encountered.

-rr Enable remote monitoring mode. In this mode sshhaarrkk waits for a

CHUD remote client program to call chudStartRemotePerfMoni-

tor()/chudStopRemotePerfMonitor() to start and stop sampling. (see above for more details on this option)

-SS limit Change the sample limit to this number of samples.

-tt [session file name(s)]

Create a text output file representing the complete analysis

from the session for each analysis module active in the ses-

sion. Note that not every analysis module supports full-text

output. If a module does not support full-text output, the

phrase:

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.

-TT limit Change the maximum time limit to this value. Enter the value

as a number followed by a suffix: for example 500m would set the time limit to 500 milliseconds. 500000u would change the

time limit to 500000 microseconds. 22s would change the sam-

pling time limit to 22 seconds.

-uu Identify processes by name (the default behavior is to iden-

tify processes by PID).

-vv Prints the Shark version and exits.

-ww After stopping sampling, wait until the user presses Return

before creating the session file.

-xx Ignore task will exit notifications. Normally sshhaarrkk will be

notified whenever a process (task) exits while it is sam-

pling. This allows for all relevant symbol and other infor-

mation required for later analysis to be gathered before

allowing the exiting task to complete exiting. The process-

ing that occurs during a task exit notification can cause gaps in the resulting profile.

BUGS

Please send your comments, suggestions and bug reports to: perftools-

feedback@group.apple.com