Call Graph Profiling in Four Easy Steps

This page describes how to instrument and profile an application program using CGProfile. We will use notepad.exe as an example.

Step 1. Setup

An experiment folder has been created for you during the installation. You can double-click the Etch Call Graph Profiler icon in the Etch Tools folder, and a new shell will open up in that directory. Alternatively, you can make your own project directory and CD to it:

	mkdir myexperiment
	cd myexperiment

All instrumented code goes here. Your original program and system DLLs will be left alone.

Step 2. DLLWatch

Identify the modules used during a run of your application. CGInstrument implements a /dllwatch option that sets up a list of the modules used during a run the application:

	cginstrument /dllwatch notepad.exe

This step is optional; if you don't discover all the modules ahead of time, Etch will detect and instrument them during the profiled run of the application. This is called on-the-fly instrumentation.

Step 3. Instrumentation

Use CGInstrument to create an instrumented version of the application.

	cginstrument notepad.exe

CGInstrument will process each module used by the application and generate a new profiled version of the module. In addition to instrumenting the procedures, CGInstrument will also update the program's import tables so that profiled versions of the application modules will be used at run-time.

Step 4. Profile Generation

Run the instrumented executable to generate raw profile information.

	notepad-etch.exe

When the run of application completes, you can use CGProfile to process the raw profile samples.

	cgprofile /html > cgprof.html

Now open cgprof.html in a web browser. Step 4 can be repeated to generate profiles for multiple application inputs.

Notes:

Be aware that on-the-fly instrumentation can introduce distortion into cycle-time profiles. You can avoid this overhead by using dllwatch or by simply running the profiled application twice (using exactly the same inputs) and using the profile data from the second run.
When using cginstrument /dllwatch, make sure you can run the application from the command line using exactly the command line you give to cginstrument.
CGInstrument will find applications on your search path without requiring a full path name. If the application to be instrumented is not on your search path, you should give the full path name to cginstrument:
```
	cginstrument c:\winnt\system32\notepad.exe
```
Use quotes for command line arguments that include spaces:
```
	cginstrument "c:\Program Files\Plus!\Microsoft Internet\IExplore.exe"
```
If you don't use quotes, the Windows command interpreter will use spaces to break the command line into arguments.