manpagez: man pages & more
man shark(1)
Home | html | info | man
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] [-v] [-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 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.

     shark 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, shark 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 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 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 shark 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 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
     chudRemoteCtrl(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 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.  shark
     is a profiling service program when the '-N' option is given on the com-
     mand line.  In network sharing mode shark can still be triggered by sig-
     nals 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 ses-
     sions from the profiling services. One shark 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 shark simultaneously.


OPTIONS

     -1          Sample only the target process (specified through -a process
                 or the launched executable).

     -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 neither
                 -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 monitoring
                 is enabled).

     -b          Enable batch mode. By default, shark will exit after record-
                 ing a single *.mshark session file.  This option allows you
                 to record multiple sessions without exiting shark.

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

     -d path     Sets the directory file path name used for *.mshark session
                 files. By default this is not set to anything. So shark gen-
                 erates 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.

     -e          List the current settings of search-path environment vari-
                 ables used by shark to locate various types of files during
                 session processing.  There are currently two environment
                 variables: SHARK_SEARCH_PATH_KEXT_FILES and
                 SHARK_SEARCH_PATH_SOURCE_FILES.  shark will search the colon
                 delimited lists of file paths for Kernel Extensions 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.

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

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

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

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

     -m file     Specifies the path to a shark sampling config (*.cfg) file to
                 be used.

     -N          Enables Network Sharing mode in the shark program. Enabling
                 network sharing does not disable any of the other methods for
                 starting and stopping profiling.

     -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 speci-
                 fied before the basename, provided ALL the directories in the
                 path exist already. No directories are created by shark.

     -q          Quiet mode. Runs silently (no output to terminal) unless an
                 error is encountered.

     -r          Enable remote monitoring mode. In this mode shark 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)

     -S limit    Change the sample limit to this <limit> number of samples.

     -t [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:

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

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

     -u          Identify processes by name (the default behavior is to iden-
                 tify processes by PID).

     -v          Prints the Shark version and exits.

     -w          After stopping sampling, wait until the user presses Return
                 before creating the session file.

     -x          Ignore task will exit notifications. Normally shark 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


SEE ALSO

     chudRemoteCtrl(1), kill(1), /Developer/Documenta-
     tion/CHUD/Shark/SharkUserGuide.pdf

                              September 17, 2009

Mac OS X 10.6 - Generated Thu Sep 17 20:09:09 CDT 2009
© manpagez.com 2000-2021
Individual documents may contain additional copyright information.