As I've said in other blog posts, it is possible to use IntelliTrace outside of the IDE.  The key to having any process using the CLR monitored by IntelliTrace are 3 environment variables:

• COR_ENABLE_PROFILING
• COR_PROFILER
• VSLOGGER_CPLAN

The first two environment variables, COR_ENABLE_PROFILING and COR_PROFILER are respected by the CLR.  When a process calls CLRCreateInstance (for clr versions >=4) or CorBindToRuntime/CorBindToRuntimeEx, the CLR checks the environment for these environment variables.  If COR_ENABLE_PROFILING is set to 0x1 or 1, the CLR will then read the value of the environment variable COR_PROFILER for a CLSID value, and attempt to instantiate a COM object for CLR profiling.

The third environment variable specifies the location for IntelliTrace to pick up its' settings, reffered to as the Collection Plan.  You can find a default Collection Plan (with all diagnostics turned off) in %PROGRAMFILES%\Microsoft Visual Studio 10.0\Team Tools\TraceDebugger Tools\en\CollectionPlan.xml (for non EN-US users, look under TraceDebugger Tools\LANG\CollectionPlan.xml.)

The values to set for the process are:

COR_ENABLE_PROFILING=1

COR_PROFILER={301EC75B-AD5A-459C-A4C4-911C878FA196}

VSLOGGERCPLAN=<Path-to-the-CollectionPlan.xml> (you need to fill this one in :)

It is important to keep in mind that the process being launched must have Read permissions for the Collection Plan.

Additionally, one must also fill in a value for the <LogFileDirectory> element in the <StartupInfo> element of the collection plan. If it is not filled in, the IntelliTrace.exe logger will attempt to write the .iTrace file next to the executable being used.  In the case of a service, this is not a writeable location (svchost.exe is located in a system directory.)

So how do we make this work for Services?  We have to set up the service's environment so that it may inherit these environment variables, then when the process starts, IntelliTrace will start collecting. When the process shuts down, the .iTrace file will be readable. Now we have to get the environment set up.  We can do this via the registry.

Let's say that our service is called MyAwesomeService.  Then you would want to open RegEdit and navigate to the key:

HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\services\MyAwesomeService.  Under this key, it is possible to set the environment by creating (or modifying if it already exists) a "Multi-String Value" or REG_MULTI_SZ key with the name "Environment". 

 Create a Multi-String Value

With the name "Environment"

And populate it with your settings

Once you have inserted the aforementoned environment variables into this Environment key, and restart the service using "net stop MyAwesomeService" followed by "net start MyAwesomeService".  At this point, an IntelliTrace.exe process should have launched (assuming managed code has run in the process).  Simply "net stop MyAwesomeService" and open the iTrace file to view what happened.

Hopefully this has been a useful and easy-to-follow blog post. If you have any questions or trouble following these steps, let me know so I can help out and also fix my instructions.

--Matthew

Since IntelliTrace can collect data and report it back via .iTrace files, this workflow is invaluable to users deploying Azure services in diagnosing issues like infinite reboots during the "Starting role" step, or determining what is causing a TypeLoadException to bring down your service.

The instructions Grant lays out are easy to understand and follow. Check it out over at his blog.

Right now, if you are an MSDN subscriber, you can download the SP1 Beta for Visual Studio 2010 Ultimate.

Otherwise, on Thursday there will be a general availability release of Visual Studio 2010 SP1 Beta here.

Once you install SP1 Beta, you will be able to hit F5 and start debugging 64-bit applications and Sharepoint applications with IntelliTrace!

64-bit F5 debugging with IntelliTrace is a feature that the entire team has heard customers pine for - so download the beta, use IntelliTrace F5 to find your 64-bit and Sharepoint bugs; and please, provide feedback!  We would love to hear about your troubles, tribulations, and successes with IntelliTrace.

There are some neat things that I've done using IntelliTrace without the IDE at all, such as collecting from 64-bit applications, monitoring test runs that I can't use Microsoft Test Manager to test, and much more.

I'm going to show you how to use the command line to collect and IntelliTrace log from a 32-bit or 64-bit process. 

Locating the Collection Plan

Inside of the "Team Tools\TraceDebugger Tools" directory beneath the Visual Studio 2010 installation, you will find two files:

• IntelliTrace.exe

• en\CollectionPlan.xml

If you are using a version of VS 2010 that is not English, you will find the CollectionPlan.xml file under a directory named after your localized language name.

These two files allow us to use IntelliTrace without the IDE at all.  The easiest way to launch an application with IntelliTrace is to use the launch command:

IntelliTrace.exe launch /collectionplan:CollectionPlan.xml /file:out.iTrace MyAwesomeExecutable.exe

When you use the launch command you will see something similar to this:

And you will have a newly created file out.iTrace. Let's take a look at the iTrace file:

That's a bit strange - where is all of my IntelliTrace data?

The data you normally would expect to be in an iTrace file won't be present because the right options were not turned on for the collection session.

The default collection plan does not have any sort of collection enabled, and as such will not collect any data when used. Once we fix this, we can start collecting the data we need.

Getting Collection Options Set Up 

The first step should be turning on the correct type of instrumentation. When modifying the collection plan, the first thing you should do is to turn on "DiagnosticEventInstrumentation" -- you can enable it by changing the following line (line 44 in the default Dev10 english collection plan)

  <DiagnosticEventInstrumentation enabled="false">

change this to

  <DiagnosticEventInstrumentation enabled="true">

This should always be turned on if you are going to be using IntelliTrace in the scenarios I'm going to describe, or you will be missing key information important for the log.

Note:  For those of you curious as to what you will be missing, exception tracing and other features rely on having DiagnosticEventInstrumentation enabled, even if no events are turned on.

Now that DiagnosticEventInstrumentation is enabled, you have a multitude of collection options that are applicable. 

To turn the dial up you can turn on TraceInstrumentation which will turn on tracing for function enters and exits, as well as parameter capturing.  This is the setting that corresponds to “Methods and Parameters” in the IntelliTrace Tools->Options window.

Collect Your Data!

By turning on these types of Instrumentation, it is possible to now re-run our scenario (IntelliTrace.exe launch /cp:CollectionPlan.xml /f:out.iTrace MyAwesomeExecutable.exe) and we will get the data we expect, loadable by any Dev10 Ultimate installation.

Here Be Dragons!

The information below is not to be depended upon.

There are other ways to get IntelliTrace to collect information from a process.  One way is to:

1. Start a logger with a specific name

2. Start a process with COR_PROFILER, COR_ENABLE_PROFILING, and VSLOGGERNAME/VSLOGGER_CPLAN set.

3. Stop the logger when you are done with your collection.

The way that the IntelliTrace profiler gets set up is the same as any other .NET profiler:

1. The environment variable COR_ENABLE_PROFILING has to be set to 0x1 or 1

2. The environment variable COR_PROFILER has to be set to the CLSID of a profiler that has been registered with the system.

For our scenario to work, the environment variable VSLOGGERNAME has to be set to the name of the logger, in lowercase-only letters, or the environment variable VSLOGGER_CPLAN has to point to a Collection Plan that is readable by the process being launched.

Since this is all quite tedious, we provide IntelliTrace Launch to make this whole process work. But if you are feeling on the wild side:

1. Start a logger – run “IntelliTrace.exe start /cp:PathToCollectionPlan.xml /f:iTraceLogFileLocation.iTrace /name:session1” – where:

   • PathToCollectionPlan.xml is the path to the collection plan

   • iTraceLogFileLocation.iTrace is where you want the IntelliTrace log file to be placed

   • session1 is a unique name for the logger.

    

   You should get output similar to this:

    

2. Set COR_PROFILER, COR_ENABLE_PROFILING, and VSLOGGERNAME to the correct values for the environment.  Then launch your application. If you are using the windows command prompt (cmd.exe):
   • set COR_PROFILER={301EC75B-AD5A-459C-A4C4-911C878FA196}
   • set COR_ENABLE_PROFILING=0x1
   • set VSLOGGERNAME=session1

                                         Note that the logger name is all lowercase.

3. When you are done (your process has exited,) the logger should have stopped on its’ own. If not, you can stop the logger using the following command: “IntelliTrace .exe stop /n:session1”
4. Finally you are done - you can now open your iTrace file and inspect the collected data.

If you do not want to start a logger manually, you may:

1. Place the Collection Plan in a directory that is readable by the process you want to instrument
2. Set the elements <LogFileDirectory> and <LogFileName> in the <StartupInfo> element to a valid location and name.
3. Set COR_PROFILER, COR_ENABLE_PROFILING, and VSLOGGER_CPLAN to the correct values for the environment.  Then launch your application. If you are using the windows command prompt (cmd.exe):

   • set COR_PROFILER={301EC75B-AD5A-459C-A4C4-911C878FA196}
   • set COR_ENABLE_PROFILING=0x1
   • set VSLOGGER_CPLAN=c:\temp\collectionplan.xml
4. Start your process.
5. Once your process has exited you are done - you may now open your iTrace file an inspect the collected data.

I hope this has been a useful blog post for getting IntelliTrace collection working outside of the IDE.  For questions or other queries please contact me using the "E-mail The Author" link on the right. 

Here’s a little background on me:

Who is this guy?

I grew up in New Jersey (Only the strong survive there!)

I went to Carnegie-Mellon University for my BS in Computer Science

I have been, and continue to be an avid cyclist, but only when the sun is out J

I enjoy working with all sorts of technology, but mostly software: arduinos, creating programming languages, web technologies and networking are currently piquing my interest.

What do you do?

After working with a web startup, and interning with Sony's Tools and Technology Group, I interned on the IntelliTrace team, and had such a great experience that I came back and have been working with IntelliTrace for the last 2+ years.

I work on a few different parts of the IntelliTrace end-to-end scenarios:

1)      I am responsible for the IntelliTrace Events implementation in the IntelliTrace .NET profiler (including the IL Interpreter that IntelliTrace uses to speculatively execute methods and properties.)

2)      The Microsoft Test Manager / IntelliTrace integration is owned by me.

3)      All of the IIS and IntelliTrace interactions are owned by me as well (this stuff is tricky!)

4)      I have aided in the creation and maintenance of IntelliTrace’s serialization mechanisms.

 So to sum it up, I’m a low-level plumbing type of guy.

In the coming posts I will explain what kind of challenges these features presented, and the neat uses and options you can tweak.

What’s this IntelliTrace thing?

My colleague Ian Huff has a great introduction about IntelliTrace. If you are not inclined to read his description here’s a short one I whipped up:

IntelliTrace is a diagnostics tool for assessing program flow and tracing specific events throughout a programs’ execution, it aims to reduce the Mean Time to Bug Discovery (MTBD).

How do I get IntelliTrace?

IntelliTrace is included in the Visual Studio Ultimate SKU, the ability to collect IntelliTrace logs is also provided in the Test Elements SKU

So how do I use this thing?

You can use IntelliTrace through Visual Studio directly, or via the command line.  These will be subjects of my upcoming posts!