Getting Started with Shark

Starting to use Shark is a relatively simple process. You only need to choose one or two items from menus and press a big “Start” button in order to start sampling your applications. This chapter describes these basic steps and a few other general Shark features, such as its preferences.

Main Window

Figure 1-1  Main Window
Main Window

After launching Shark, you will be presented with Shark’s main window, as illustrated in Figure 1-1. The default sampling configuration is timer-based sampling (Time Profile) of everything running on the system. By default, the Time Profile configuration uses a 1 ms timer as the trigger for sampling and will record for 30 seconds (30,000 samples per processor). Opening the Sampling Configuration menu (#1) allows you to select from various built-in profiling configurations. Here is a list:

These built-in configurations are adequate for sampling most applications. After you have used Shark for awhile, however, you may decide that you would like to sample something in your application that is not covered by the built-in collection of options. In particular, you may want to perform hardware measurements using counters that are not used by the default hardware measurement configurations. The process for building your own configurations is described in Custom Configurations. This process is complex enough that you should probably familiarize yourself with Shark before attempting the creation of configurations.

By default, Shark samples your entire system, as indicated by the “Everything” item selected for you in the Target pop-up menu (#2). Popping open this menu allows you to select a specific process or file (Figure 1-2). You may also choose different targets using the keyboard: Command-1 for everything, Command-2 for an executing process, and Command-3 for a file. For a Time Profile, it is unnecessary to select a specific target, but others like Malloc Trace and Static Analysis require you to target a specific process or file. If you select the “Process” target, you can also choose to launch a new process. See Process Attach and Process Launch for full instructions on the process attaching and launching target selection techniques.

Figure 1-2  Process Target
Process TargetProcess Target

Mini Configuration Editors

Each configuration typically has a few parameters that are frequently modified. Shark allows you to edit these easily using the mini configuration editors associated with each configuration. You can enable mini configuration editors by selecting the ConfigShow Mini Config Editor menu item (Command-Shift-C). Most mini configuration editors are similar to the one depicted in Shark Preferences, but all have small configuration-specific variations. The selection of controls available in each min configuration editor are described in the chapters associated with each type of configuration.

Figure 1-3  Mini Configuration Editor
Mini Configuration Editor

Perform Sampling

After you choose what you would like to sample (or trace, with some configurations) and how, then actually using Shark to sample your program is extremely simple. There are two main ways to start sampling:

  1. Click the Start button (#3 in Main Window).

  2. Press the current “Hot Key” (Option-Esc, by default).

Shark will emit a brief tone and the Shark icon in the dock will turn bright red to let you know that Shark is now actively sampling. At this point, you should exercise your program appropriately to trigger the execution of code that you want to measure. Sometimes this may require no active input on your part, but if you are measuring something like user interface performance then you may need to manually perform several steps while Shark samples.

After you have finished sampling the interesting portion of your program, you will need to stop Shark’s sampling. Again, this is a simple process. You will typically use one of the following three options:

  1. Click the Stop button, which is what the “Start” button becomes once sampling has started.

  2. Press the current “Hot Key” (Option-Esc, by default).

  3. Wait for the maximum profiling time or number of samples specified by the configuration to pass. When either of these conditions is met, Shark will automatically stop.

After Shark stops sampling, you will see a progress bar appear at the bottom of the main Shark window as samples are processed and symbols are gathered. During processing, Shark sorts samples both by process and by thread. Shark also looks up the symbols corresponding to each sampled address and caches any other information that may be needed for later browsing of your program. All of this work is done only after sampling is complete, in order to minimize the system overhead of Shark during sampling.

If you would like to use the “Hot Key” technique, but your application already uses Option-Esc for another purpose, then you should reassign Shark’s “Hot Key” to another key combination. See Shark Preferences for information on how to do this.

In addition to the basic timing options shown here, Shark also offers many other techniques for very fine selection of the time used for Shark’s sampling, should you need more control. See Advanced Profiling Control if you find that the basic start/stop operation described here is not enough to focus Shark’s sampling on the parts of your application that you would like to measure.

Session Windows and Files

Once you’ve recorded samples or a trace, Shark will open up a new session window to display the results. Depending upon the configuration you chose, the appearance of this window will vary. See the chapter on the particular configuration that you chose for more information (in Time Profiling, System Tracing, and Other Profiling and Tracing Techniques). Nevertheless, all session windows have some basic features in common.

Shark allows you to work with multiple sampling sessions at a time, displaying a separate window for each session. This is useful for comparing two or more sampling sessions side-by-side. The currently displayed session can be changed using the Window menu. By default, sessions are listed in the order they are loaded or created. In addition, each new session is given a unique name, in the format of “Session # - Configuration.”

Session Files

Shark makes it easy to save any sessions to .mshark “session” files at any time. There are several reasons why you might want to do this: for later analysis, to keep as archives to track performance regressions, or to share your results. These files are particularly convenient when attached to performance bug reports, as a session file that records samples of slow code offers a simple and effective way to document the performance problem. Each session file contains all of the necessary data (symbols, source, and — optionally — even program text, see Shark Preferences) needed to display and explore the session on any computer running Mac OS X, independent of that system’s hardware or software configuration. Because of this, you can freely share your session files with any other coworkers using Shark, without regard to what type of Mac they might have.

A session is saved to disk as a single, compressed file when you use the FileSave menu item (Command-S). The first time you save a session, you will need to name the new session. This name will be used to name the new session file and to replace the “Session #” part of the original window name. If you want to save the session again at any point in time using a new name, then just choose the FileSave as... menu item (Command-Shift-S).

You may even choose to have Shark email your session file to someone else at any time, using the FileMail This Session menu item. When chosen, this will send your default email program a remote message asking it to start up a new email message for sending. Subsequently, Shark will automatically attach a session file of the current session (saving it first, if necessary). You may then finish composing your message and send it using the normal procedures for your email program.

Session Information Sheet

You can see many underlying details about the session by using FileGet Info (Command-I). This will drop down the sheet shown in Session Report over the top of your session window.

Figure 1-4  Session Inspector Panel
Session Inspector Panel

This panel contains four tabbed panes:

  • Summary— Because Shark records samples at a very low level, the configuration of the sampled system can often be critical when interpreting results. This pane, shown in Session Report, displays many facts about the system setup when the session was originally recorded. This is very useful if you send a session file to another person, as they can call up your system’s configuration with a single key combination. Four different types of information are presented in the four quadrants of the view:

    1. Basic Statistics— This section of the pane contains basic information about the system at the time the session was recorded. The system’s name, the current user, date, and time are available here.

    2. Software Configuration— This shows version information about Shark and the underlying Mac OS X and frameworks.

    3. Sampling Configuration— This shows a text description of the configuration used for recording the session. This is the same sort of summary description that you can see in the upper right corner of the custom configuration window (as shown in The Config Editor).

    4. Hardware Configuration— This shows key characteristics about the machine used for sampling and its underlying hardware components: processor, main memory, memory controller, I/O subsystem controller, and such.

  • Notes— This pane is just a text box. You can type any notes and messages that you want here, and they will be saved with the session file. This is helpful when you would like to record some additional information about how the session was recorded, making notes about insights gained by you during analysis, and the like.

  • Symbols— Here you can see a list of all binaries (application binaries, dynamic libraries, and the like) that were sampled during the session. It also provides controls for selecting and “symbolicating” (adding symbols to) samples taken from those binaries. See Manual Session Symbolication for instructions on how to do this.

  • Plug Ins— This pane displays a list of the Shark PlugIns that were used to record, analyze, and view the session. See Custom Configurations for more information on these.

Session Report

At any time, you may open a window containing a brief text summary of your session’s findings by using the FileGenerate Report... menu item (Command-J). This report includes some information about what the configuration was, the underlying system configuration, and a brief summary of the recorded samples. If you need to give a quick overview of a session to someone who does not have Shark on their computer, then this can be a useful command. Otherwise, it is probably easier just to send them your entire session file.

Advanced Settings Drawer

Most session windows in Shark have a variety of settings that can modify how the information in that window is presented. For consistency, the controls for these settings are always presented in the Advanced Settings Drawer, a drawer that can slide in and out of the right side of the session window by choosing the WindowShow Advanced Settings menu item (Command-Shift-M). An example is depicted below in Main Window. The controls presented will vary depending upon the current session viewer visible in the window, and so instructions on how to use these controls are provided in sections following the descriptions of the session viewers themselves.

Figure 1-5  Sample Window with Advanced Settings Drawer visible at right
Sample Window with Advanced Settings Drawer visible at rightSample Window with Advanced Settings Drawer visible at right

Shark Preferences

Shark’s global preferences are accessed from the SharkPreferences... menu item. This window allows you to set some global options that Shark uses while recording and displaying all of your sessions. Shark’s preference panel is divided into four tabbed panes: