Unix/Linux Go Back    


man page for shark (all section 1)

Linux & Unix Commands - Search Man Pages
Man Page or Keyword Search:   man
Select Man Page Set:       apropos Keyword Search (sections above)


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 pro-
     files of hardware and software 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 vari-
     ety 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 simu-
     lator.

     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 cur-
     rently 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: chudStartRemote-
     PerfMonitor()/chudStopRemotePerfMonitor() to start/stop sampling. 2: The utility chudRemo-
     teCtrl(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 chudRemo-
     teCtrl(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 run-
     ning 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 "ser-
     vice" 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
     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 recording a single *.mshark
		 session file.	This option allows you to record multiple sessions without exit-
		 ing 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 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.

     -e 	 List the current settings of search-path environment variables 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 AVAILABLE>" 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 configura-
		 tions 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 specified 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 encoun-
		 tered.

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

     -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 session.  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 exten-
		 sion 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 fol-
		 lowed by a suffix: for example 500m would set the time limit to 500 millisec-
		 onds.	500000u would change the time limit to 500000 microseconds. 22s would
		 change the sampling time limit to 22 seconds.

     -u 	 Identify processes by name (the default behavior is to identify 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 sampling.  This allows for all relevant symbol
		 and other information required for later analysis to be gathered before allowing
		 the exiting task to complete exiting.	The processing 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-feed-
     back@group.apple.com

SEE ALSO
     chudRemoteCtrl(1), kill(1), /Developer/Documentation/CHUD/Shark/SharkUserGuide.pdf

					February 20, 2018
Unix & Linux Commands & Man Pages : ©2000 - 2018 Unix and Linux Forums


All times are GMT -4. The time now is 01:23 AM.