Profiling FAQ #3: How do -exclude and -include on vsinstr differ from -start / -suspend / -resume, etc.

  • Article

VSinstr has two different categories of switches.  The first category of switches control which methods get instrumented.  The second category of switches control whether or not profiling collection is enabled or not.  They are completely orthogonal. 

Collection control:  Richard gives details of the profiler collection routines at the API level here.  However, you can also use VSInstr to control when we are actively collecting data. 

Here's the relevant stuff from VSInstr /?

/START:inside|outside,funcname
        Start/Stop pair inserted at location in funcname
/SUSPEND:inside|outside,funcname
        Suspend/Resume pair inserted at location in funcname
/STARTONLY:before|after|top|bottom,funcname
        Start inserted at location in funcname
/STOPONLY:before|after|top|bottom,funcname
        Stop inserted at location in funcname
/SUSPENDONLY:before|after|top|bottom,funcname
        Suspend inserted at location in funcname
/RESUMEONLY:before|after|top|bottom,funcname
        Resume inserted at location in funcname
/MARK:before|after|top|bottom,funcname,markid
        Mark inserted at location in funcname with markid

Instrumentation Control:  These switches determine which functions get probes inserted in them.  I give a little bit of background on what the probes are in this post.

/EXCLUDE:funcspec[;funcspec]+
        Everything but funcname will be instrumented
/INCLUDE:funcspec[;funcspec]+
        only funcname will be instrumented

Using them together:  The reason we have these two separate categories is so that you can specify that you want to instrument only certain functions and you are only interested in collecting during certain phases of execution.  Another way of putting this is that Instrumentation Control determines WHICH data you can collect and Collection Control determines WHEN you collect it.

Why should I care about these switches?: In a word, overhead.  Every probe inserted modifies the behavior of the original program slightly.  We do subtract out an appoximation of this overhead at analysis time, but they still have subtle timing effects on multithreaded apps.  Also, as Richard says in his post that I linked to above, collection and instrumentation control really help control the potentially massive volume of data collected during a trace run.