"Instruments" is an application provided by Apple that provides a graphical user interface for the DTrace command-line tool. DTrace is a troubleshooting tool available on several Unix-like operating systems, including Mac OS X. It can log and provide statistics for many application and kernel-level operations.
NOTE: Instruments and the required Xcode installation can be unwieldy. Also, the newer SEP client for Macintosh (as of SEP 12.1 RU4) and SymDaemon process are not visible to Instruments tracing. Use the fs_usage command line to trace SymDaemon file activity instead.
How to Install
To install Instruments, you must install Xcode, the Macintosh development tools. Xcode is free and can be obtained via the following means:
- The Mac App store (in Mac OS X 10.6.8 and later - requires registration with the App Store).
- The Apple Developer site (developer.apple.com - requires registration of a developer account).
- On older versions of Mac OS X distributed on physical media, Xcode will be located in the "Optional Installs" folder to install from. Double-click "Xcode.mpkg" and choose the default install.
Please note: Xcode is a very large download and depending on network speeds may take some time to fully download. Please use the most up to date version of Xcode for your environment to ensure compatibility.
How to use Instruments
This procedure can easily be adjusted to trace only specific processes and executables, but for our purposes here you will be shown how to monitor CPU and file activity for all processes.
- Instruments will be installed to your system drive, in /Developer/Applications/ -- run it from there, or from the Xcode application menu item select Open Developer Tool->Instruments (in newer versions of Xcode).
When Instruments first starts, you must make a template choice. You can start right away by choosing "Open an Existing File..." and using the pre-constructed template available in "dtrace_all.zip" -- see attachments section at bottom of this article. Or,the following steps and images will tell you how this template is constructed, and give you ideas on how it can be customized.
- To begin your own template, select "File System" from the Mac OS X list, then choose "Activity Monitor".
- "Activity Monitor" will start you with a template that monitors CPU usage for all processes. Next, we want to add an instrument that will monitor file "open" operations: Choose "Build New Instrument" from the Instrument menu.
Don't be intimidated by the choices that appear. For our purposes, choose "System Call", "open*", "arg0", and "path". Click the plus (+) button to the right of "arg0/path", to add another data item to record: executable name. See image below for these highlighted items.
If desired, you can also click the plus (+) button to the right of "System Call/open*" and add further logging conditions.
For example, you could add Executable=="navx" to log only those file activities related to the navx process. Normally, we will not add any conditions, and log all activity.
Click "Save" in the custom instrument dialog when you are done.
- Choose from the dropdown menu as shown below to attach your instrument to the target of our investigation: All Processes.
- Before proceeding, you can choose "Save as Template..." from the File menu, to save this for later use. See "dtrace_all.zip" in attachments section at bottom of article.
- Then, click "Record". Your Instruments set will start monitoring all file open operations and CPU usage for all processes. While the trace is running, reproduce the issue you are troubleshooting. When ready, click "Stop". You click start and stop as many times as you choose, and each logging session will be saved separately under the same file. You can then click "Save" in the File menu to save all runs as a .trace file that can be sent to Symantec technical support for later viewing.
- When viewing the trace file, it is useful to select "Activity Monitor" and "Track inspection head"--see image below.
You can then select your custom "DTrace Instrument" which will display and highlight file activity that occured during the time selected, as you drag the position indicator (the upside-down triangle in the time scale at top):
You can also export the file activity to a CSV text file for grepping and other filtering you might want to do: while your "DTrace Instrument" is selected, choose "Export track..." from the Instrument menu.
Several Xcode versions are available at http://connect.apple.com. An AppleID is required (is available upon free registration). Look for Xcode under "Developer Tools". Xcode 3.2.5 is a 3.5GB download.
Macintosh Xcode "Instruments" trace logging template
dtrace_all.zip (237.6 KB)