Debug Your App with IntelliTrace Log (.iTrace) Files

Article
03/18/2014

You can start an IntelliTrace debugging session directly from an IntelliTrace log (.iTrace) file. This file contains exceptions, web requests, threads, test steps, modules, and other system info that IntelliTrace records while your app runs.

Watch IntelliTrace in action:

Collecting and analyzing IntelliTrace data in production for debugging (Channel 9 video)
Developing, testing, and production debugging for SharePoint (Channel 9 video)

Requirements

An .iTrace file from one of the following sources:
- An IntelliTrace session in Visual Studio Ultimate. See Record Code Execution with IntelliTrace for Debugging in Visual Studio.
- A test session in Microsoft Test Manager. This attaches an .iTrace file to a Team Foundation Server work item. See How to: Collect IntelliTrace Data to Help Debug Difficult Issues.
- The standalone collector for apps running outside Visual Studio. See Collect IntelliTrace Data Outside Visual Studio with the Standalone Collector.
- Apps monitored by System Center 2012 Service Pack 1 (SP1) - Operations Manager with the IntelliTrace Profiling Management Pack.
  
  Requires Visual Studio 2012 Update 1 or Update 2. See How to Configure Integration with IntelliTrace in System Center 2012.
Visual Studio Ultimate on a development computer or other computer to open .iTrace files

Note

To debug with IntelliTrace and step through code, you must have the matching source files and symbol files. Make sure the symbol files are in the Visual Studio symbol path. Otherwise, Visual Studio can't resolve the source locations and shows the message "Symbols not found." See Specify Symbol (.pdb) and Source Files in the Visual Studio Debugger.

What do you want to do?

Open an IntelliTrace log file
Read the IntelliTrace log file
Start debugging from an IntelliTrace log file

Open an IntelliTrace log file

On a computer with Visual Studio Ultimate, open the .iTrace file.

Double-click the .iTrace file outside Visual Studio, or open the file from inside Visual Studio.

- or -
If the .iTrace file is attached to a Team Foundation Server work item, follow these steps in the work item:
- Under All Links, find the .iTrace file. Open it.
  
  - or -
- Under Repro Steps, choose the IntelliTrace link.

Tip

If you closed the .iTrace file during debugging, you can reopen it easily. Go to the Debug menu, choose IntelliTrace, Show Log Summary. You can also choose Show Log Summary in the IntelliTrace window. This is available only while debugging with IntelliTrace.

Read the IntelliTrace log file

Some of the following sections in the .iTrace file appear only if you collected data from a particular source, for example, Test Manager or SharePoint applications with the standalone collector.

Section	Contains	Collection Source (Visual Studio Ultimate, Test Manager, standalone collector)
Analysis	For SharePoint 2010 and SharePoint 2013 applications only. This section lets you examine IntelliTrace and SharePoint events, such as debugger events, ULS events, exceptions, and other data that the collector recorded.	Standalone collector for Visual Studio 2012 Update 2
Threads List	Threads that ran during collection	All sources
Web Requests	Web requests that were submitted to an IIS application pool. This data is similar to data collected in IIS W3c log files.	Standalone collector: IIS-hosted Web apps only
Exception Data	Exceptions that were thrown by the app during collection, including the full call stack for each exception	All sources
Test Data	Test steps and their results from a test session	Test Manager
System Info	Settings and specifications of the host system	All sources
Modules	Modules that loaded during collection	All sources

Start debugging from an IntelliTrace log file

In most sections, you can review events or other items, choose an item, and then choose Start Debugging. This starts an IntelliTrace debugging session at the point where and when an event happened.

Tip

To sort data, choose the column headers. To filter data, use the search box. Plain text search works across all columns except the time columns. In the Web Requests section, you can also filter searches to a specific column.

Analysis

This section appears for SharePoint 2010 and SharePoint 2013 applications only if you recorded data with the collector in Visual Studio 2012 Update 2 or IntelliTrace Collector for Visual Studio. See Collect IntelliTrace Data Outside Visual Studio with the Standalone Collector.

This section lets you perform these tasks:

Use a SharePoint correlation ID to find its matching web request and events. You can choose an event and then start debugging at the point where and when the event happened.
Examine any unhandled exceptions that the collector found. You can choose an exception and then start debugging at the point where and when the exception happened.

Note

If you see the message "Symbols not found", Visual Studio can't resolve the source locations. Make sure the application’s symbol (.pdb) files are in the Visual Studio symbol path. See Specify Symbol (.pdb) and Source Files in the Visual Studio Debugger.

Start debugging with a SharePoint correlation ID

Copy the SharePoint correlation ID from its source.

For example:
In the .iTrace file, under Analysis, you can enter the SharePoint correlation ID. This lets you find the matching request and see its recorded events.
Under Request Events, examine the events. Starting from the top, events appear in the order they happened.
1. Choose an event to see its details.
2. Choose Start Debugging to start debugging at the point where the event happened.

You can see these kinds of SharePoint events along with IntelliTrace events:

User profile events

These events happen when SharePoint loads a user profile and when user profile properties are read or changed.
Unified Logging System (ULS) events

The standalone collector records a subset of SharePoint ULS events and these fields:

IntelliTrace field

SharePoint ULS field

Id

EventID

Level

Level

Category Id

Category Id

Category

Category

Area

Product

Output

Message

Correlation Id

Correlation Id

IntelliTrace field	SharePoint ULS field
Id	EventID
Level	Level
Category Id	Category Id
Category	Category
Area	Product
Output	Message
Correlation Id	Correlation Id

Start debugging from an unhandled exception

Choose a SharePoint correlation ID for an exception. Exceptions are grouped by type and call stack.
(Optional) Expand Call Stack to see the call stack for a group of exceptions.
Choose Debug Exception to start debugging at the point where and when the exception happened.

For a walkthrough, see Walkthrough: Debugging a SharePoint Solution by Using IntelliTrace. For the kinds of data that the collector records, see Record Code Execution with IntelliTrace for Debugging in Visual Studio.

Threads List

This section shows you recorded threads that ran in the target process. You can start debugging from the first valid IntelliTrace event in a selected thread.

To start debugging from a specific thread

Under Threads List, choose a thread.
At the bottom of Threads List, choose Start Debugging. You can also double-click a thread.

To start debugging from where the app begins, double-click Main Thread. See Record Code Execution with IntelliTrace for Debugging in Visual Studio.

Thread data that the user creates might be more useful than threads that a server creates and manages for IIS-hosted Web apps.

Column	Shows the
ID	Thread ID number
Name	Thread name. Unnamed threads appear as "<No Name>".
Start Time	Time the thread was created
End Time	Time the thread was completed

Web Requests

This section shows recorded web requests that were submitted to an IIS application pool. You can choose a web request to examine the events recorded for that request. You can then start debugging from a specific event.

By default, web requests appear from top to bottom in the order they arrive at the server.

To see events recorded for a specific web request

Under Web Requests, choose a web request.
At the bottom of Web Requests, choose Request Details. You can also double-click the web request.

The Request Details page opens for the selected web request and shows the IntelliTrace events recorded for that request. Starting from the top, events appear in the order that they happened. Filter events by choosing from the category list or by using the search box. See Record Code Execution with IntelliTrace for Debugging in Visual Studio.

Tip

The Request Details page opens in a preview tab. This tab is replaced with a new Request Details page when you choose another web request. To preserve the preview tab, choose Promote on the tab. The next web request will open in a new preview tab.

To start debugging from a specific event
1. Under Request Events, choose an event.
2. At the bottom of Request Events, choose Start Debugging. You can also double-click an event.
  Tip
  
  If the .iTrace file includes function call information, you can step through the code starting from the event location. You can also see parameter and return values.
  
  To collect call information:
  - In Visual Studio Ultimate, configure IntelliTrace to collect call information. See Record Code Execution with IntelliTrace for Debugging in Visual Studio.
  - For the IntelliTrace standalone collector, use either the collection_plan.ASP.NET.trace.xml collection plan or a custom collection plan. See Collect IntelliTrace Data Outside Visual Studio with the Standalone Collector.
  If you see the message "Symbols not found", Visual Studio can't resolve the source locations. Make sure the Web app's symbol (.pdb) files are in the Visual Studio symbol path. See Specify Symbol (.pdb) and Source Files in the Visual Studio Debugger.

Column	Shows the
Method	HTTP method submitted with the request
Target URL	Target URL submitted with the request
Time Taken (ms)	Time in milliseconds between the server receiving the request and the result leaving the server
Status	HTTP status code returned in the result
Session Id	Session ID used by IIS to differentiate users. The Session Id value is only an increasing integer used to differentiate between session users and is not related to the ASP.NET concept of SessionID. So, web requests that have the same Session Id belong to the same user session.
Client IP	IP address recorded by IIS for the submitted request
User Agent	Value of the user agent string submitted with the HTTP request
Start Time	Time that the server received the request
End Time	Time that the server responded to the client

To see the data from a user perspective, filter and group the web requests. For example:
- To find failures, filter requests by Status.
- To see trends or user behavior, group failures by Target URL or Session Id.
You can also filter searches to a specific column. Type the column name with no spaces, a colon, and the search value.

For example, to find web requests that used the GET method with a specific Session ID, type:

Method:GET;SessionId:2

You can use one filter per column. To see which columns you can filter, look at the Web Requests search box's tooltip.

Exception Data

This section lets you examine recorded exceptions that were thrown by your app. By default, the most recent exceptions appear at the top because exceptions are sorted by Event Time in descending order.

To start debugging from a specific exception

Under Exception Data, choose an exception.
At the bottom of Exception Data, choose Start Debugging. You can also double-click an exception.

This starts debugging at the time when the exception was thrown.

Tip

Look for multiple exceptions that have the same Type and Thread ID and appear sequentially. This is often caused by one exception that was thrown, caught, and then thrown again.

To see if this is the case, choose each of these exceptions, and look at the call stack. See whether the call stack increases or decreases. If the shorter stack is the same as the start of the longer call stack, and the Thread ID is the same, then it's possible the same exception was rethrown. The exception with the longest call stack might be closest to the source of the problem.

Column	Shows the
Type	.NET type of the exception
Message	Message provided by the exception
Thread Id	ID of the thread that threw the exception
HResult	The error code specified in the exception. Available if this value was set in the exception.
Event Time	Time stamp recorded when the exception was thrown
Call Stack	Call stack for an exception. To see the call stack, choose an exception in the list. The call stack appears below the exception list.

Test Data

This section lets you examine the data that Test Manager collected while testing your app.

To start debugging from a specific test step

Expand Test Steps Grid. Choose a test step.
At the bottom of Test Steps Grid, choose Start Debugging. You can also double-click a test step.

This starts debugging from the first valid IntelliTrace event after the selected test step.

When test data exists, IntelliTrace tries to resolve the associated Team Foundation Server build that was used to perform the test run. If the build is found, the associated symbols for the app are resolved automatically.

Field	Shows the
Test Session	Test sessions that were recorded. Typically, there is only one. This list is empty if test data was created using a manual exploratory test.
Test Case	Test cases from the selected test session. This list is empty if test data was created using a manual exploratory test.
Test Steps Grid	Test steps that were recorded with the test result of pass or fail

System Info

This section shows you details about the system that hosted the app, for example, hardware, operating system, environmental and process-specific information.

Modules

This section shows you the modules that the target process loaded. Modules appear in the order that they loaded.

Column	Shows the
Module Name	Module file name
Module Path	Disk location where the module was loaded
Module ID	Unique identifier of the module that is version-specific and contributes to the matching symbol (PDB) files. See [OBSOLETE] How to: Specify Symbol Locations and Loading Behavior.