Export (0) Print
Expand All
6 out of 9 rated this helpful - Rate this topic

Collect IntelliTrace Data Outside Visual Studio with the Standalone Collector

To debug apps in production or other environments, use the IntelliTrace collector to save diagnostic data to an IntelliTrace log file (.iTrace file). This lets you record what happened in your app without installing Visual Studio or changing your app’s environment. When you're done collecting data, just delete the collector to uninstall it.

Watch IntelliTrace in action: Collecting and analyzing IntelliTrace data in production for debugging (Channel 9 video)

Requirements

  • .NET Framework 3.5, 4, or 4.5

  • Visual Studio Ultimate on a development computer or other computer to open .iTrace files

    NoteNote

    Make sure to save your symbol (.pdb) files. To debug with IntelliTrace and step through code, you must have the matching source files and symbol files. See Specify Symbol (.pdb) and Source Files in the Visual Studio Debugger.

FAQ

  • ASP.NET Web apps hosted on Internet Information Services (IIS) version 7.0, 7.5, and 8.0

  • SharePoint 2010 and SharePoint 2013 applications

  • Managed desktop apps (.exe files)

  1. On your app’s server, create the collector directory, for example: C:\IntelliTraceCollector

  2. Get the collector from the Microsoft Download Center or from the Visual Studio installation folder:

    • Microsoft Download Center:

      1. On your app’s server, go to IntelliTrace Collector for Visual Studio.

      2. Next to IntelliTraceCollector.exe, choose Download.

      3. Save IntelliTraceCollector.exe to the collector directory, for example: C:\IntelliTraceCollector

      4. Run IntelliTraceCollector.exe. This extracts the IntelliTraceCollection.cab file.

      - or -

    • Visual Studio installation folder:

      NoteNote

      To get the collector that supports diagnostic events for SharePoint 2010 and SharePoint 2013 applications, download IntelliTrace Collector for Visual Studio or make sure you have Visual Studio 2012 Update 2 installed.

      1. Copy IntelliTraceCollection.cab from the following folder:

        ..\Microsoft Visual Studio 11.0\Common7\IDE\CommonExtensions\Microsoft\IntelliTrace\11.0.0

      2. Put IntelliTraceCollection.cab in the collector directory, for example: C:\IntelliTraceCollector

  3. Expand IntelliTraceCollection.cab:

    1. On your app’s server, open a command prompt window as an administrator.

    2. Browse to the collector directory, for example: C:\IntelliTraceCollector

    3. Use the expand command, including the period (.) at the end, to expand IntelliTraceCollection.cab:

      expand /f:* IntelliTraceCollection.cab .

      NoteNote

      The period (.) preserves the subfolders that contain localized collection plans.

  1. On your app’s server, open a command prompt window as an administrator.

  2. Use the Windows icacls command to give the server administrator full permissions to the collector directory. For example:

    icacls "C:\IntelliTraceCollector" /grant "<Domain\AdministratorID>":F

  3. To collect data for a Web app or SharePoint application:

    1. Give the person who will run the IntelliTrace PowerShell cmdlets full permissions to the collector directory.

      For example:

      icacls "C:\IntelliTraceCollector" /grant "<Domain\UserID>":F

    2. Give the application pool for the Web app or SharePoint application read and execute permissions to the collector directory.

      For example:

      • For a Web app in the DefaultAppPool application pool:

        icacls "C:\IntelliTraceCollector" /grant "IIS APPPOOL\DefaultAppPool":RX

      • For a SharePoint application in the SharePoint - 80 application pool:

        icacls "C:\IntelliTraceCollector" /grant "IIS APPPOOL\SharePoint - 80":RX

  1. On your app’s server, make sure that PowerShell is enabled. On most versions of Windows Server, you can add this feature in the Server Manager administrative tool.

    Adding PowerShell by using Server Manager

  2. Install the IntelliTrace PowerShell cmdlets.

    1. Open a PowerShell command window as an administrator.

      1. Choose Start, All Programs, Accessories, Windows PowerShell.

      2. Choose one of the following steps:

        • On 64-bit operating systems, open the shortcut menu for Windows PowerShell. Choose Run as administrator.

        • On 32-bit operating systems, open the shortcut menu for Windows PowerShell (x86). Choose Run as administrator.

    2. In the PowerShell command window, use the Import-Module command to import Microsoft.VisualStudio.IntelliTrace.PowerShell.dll.

      For example:

      Import-Module "C:\IntelliTraceCollector\Microsoft.VisualStudio.IntelliTrace.PowerShell.dll"

  1. On your app’s server, create the .iTrace file directory, for example: C:\IntelliTraceLogFiles

    NoteNote
    • To avoid slowing down your app, choose a location on a local high-speed disk that’s not very active.

    • You can put .iTrace files and the collector files in the same place. However, if you have a Web app or SharePoint application, make sure this place is outside the directory that hosts the application.

    Security noteSecurity Note
    • Restrict the .iTrace file directory only to those identities that must work with the collector. An .iTrace file might contain sensitive information, such as data from users, databases, other source locations, and connection strings because IntelliTrace can record any data that passes into method parameters or as return values.

    • Make sure those who can open .iTrace files have the authority to view sensitive data. Use caution when sharing .iTrace files. If other people must have access, copy the files to a secure shared location.

  2. For a Web app or SharePoint application, give its application pool full permissions to the .iTrace file directory. You can use the Windows icacls command or use Windows Explorer (or File Explorer).

    For example:

    • To set up permissions with the Windows icacls command:

      • For a Web app in the DefaultAppPool application pool:

        icacls "C:\IntelliTraceLogFiles" /grant "IIS APPPOOL\DefaultAppPool":F

      • For a SharePoint application in the SharePoint - 80 application pool:

        icacls "C:\IntelliTraceLogFiles" /grant "IIS APPPOOL\SharePoint - 80":F

      -or-

    • To set up permissions with Windows Explorer (or File Explorer):

      1. Open Properties for the .iTrace file directory.

      2. On the Security tab, choose Edit, Add.

      3. Make sure Built-in security principals appears in the Select this object type box. If it’s not there, choose Object Types to add it.

      4. Make sure your local computer appears in the From this location box. If it’s not there, choose Locations to change it.

      5. In the Enter the object names to select box, add the application pool for the Web app or SharePoint application.

      6. Choose Check Names to resolve the name. Choose OK.

      7. Make sure the application pool has Full control.

  1. To start collecting data, open a PowerShell command window as an administrator, then run this command:

    Start-IntelliTraceCollection "<ApplicationPool>" <PathToCollectionPlan> <FullPathToITraceFileDirectory>

    Important noteImportant

    After you run this command, type Y to confirm that you want to start collecting data.

    For example, to collect data from a SharePoint application in the SharePoint - 80 application pool:

    Start-IntelliTraceCollection "SharePoint - 80" "C:\IntelliTraceCollector\collection_plan.ASP.NET.default.xml" "C:\IntelliTraceLogFiles"

    ApplicationPool

    The name of the application pool where your application runs

    PathToCollectionPlan

    The path to a collection plan, an .xml file that configures settings for the collector.

    You can specify a plan that comes with the collector. The following plans work for Web apps and SharePoint applications:

    • collection_plan.ASP.NET.default.xml

      Collects only IntelliTrace events and SharePoint events, including exceptions, database calls, and Web server requests.

    • collection_plan.ASP.NET.trace.xml

      Collects function calls and all the data in collection_plan.ASP.NET.default.xml. This plan is good for detailed analysis, but it might slow down your app more than collection_plan.ASP.NET.default.xml.

    To avoid slowing down your app, customize these plans or create your own plan. For security, put any custom plans in the same secure location as the collector files. See Creating and Customizing IntelliTrace Collection Plans and How can I get the most data without slowing down my app?

    NoteNote

    By default, the max size of the .iTrace file is 100 MB. When the .iTrace file reaches this limit, the collector deletes the file’s earliest entries to make space for newer entries. To change this limit, edit the collection plan’s MaximumLogFileSize attribute.

    Where can I find localized versions of these collection plans?

    You can find localized plans in the collector's subfolders.

    FullPathToITraceFileDirectory

    The full path to the .iTrace file directory.

    Security noteSecurity Note

    Provide the full path, not a relative path.

    The collector attaches to the application pool and starts collecting data.

    Can I open the .iTrace file at this time? No, the file is locked during data collection.

  2. Reproduce the problem.

  3. To take a snapshot of the .iTrace file, use this syntax:

    Checkpoint-IntelliTraceCollection "<ApplicationPool>"

  4. To check collection status, use this syntax:

    Get-IntelliTraceCollectionStatus

  5. To stop collecting data, use this syntax:

    Stop-IntelliTraceCollection "<ApplicationPool>"

    Important noteImportant

    After you run this command, type Y to confirm that you want to stop collecting data. Otherwise, the collector might continue collecting data, the iTrace file will remain locked, or the file might not contain any useful data.

  6. Open the .iTrace file in Visual Studio Ultimate.

  1. To start your app and collect data at the same time, use this syntax:

    <FullPathToIntelliTraceCollectorExecutable>\IntellitraceSC.exe launch /cp:<PathToCollectionPlan> /f:<FullPathToITraceFileDirectoryAndFileName> <PathToAppExecutableFileAndFileName>

    For example, to collect data from an app named MyApp:

    C:\IntelliTraceCollector\IntelliTraceSC.exe launch /cp:"C:\IntelliTraceCollector\collection_plan.ASP.NET.default.xml" /f:"C:\IntelliTraceLogFiles\MyApp.itrace" "C:\MyApp\MyApp.exe"

    FullPathToIntelliTraceCollectorExecutable

    The full path to the collector executable, IntelliTraceSC.exe

    PathToCollectionPlan

    The path to a collection plan, an .xml file that configures settings for the collector.

    You can specify a plan that comes with the collector. The following plans work for managed apps:

    • collection_plan.ASP.NET.default.xml

      Collects IntelliTrace events only, including exceptions, database calls, and Web server requests.

    • collection_plan.ASP.NET.trace.xml

      Collects function calls and all the data in collection_plan.ASP.NET.default.xml. This plan is good for detailed analysis, but it might slow down your app more than collection_plan.ASP.NET.default.xml.

    To avoid slowing down your app, customize these plans or create your own plan. For security, put any custom plans in the same secure location as the collector files. See Creating and Customizing IntelliTrace Collection Plans and How can I get the most data without slowing down my app?

    NoteNote

    By default, the max size of the .iTrace file is 100 MB. When the .iTrace file reaches this limit, the collector deletes the file’s earliest entries to make space for newer entries. To change this limit, edit the collection plan’s MaximumLogFileSize attribute.

    Where can I find localized versions of these collection plans?

    You can find localized plans in the collector's subfolders.

    FullPathToITraceFileDirectoryAndFileName

    The full path to the .iTrace file directory and the .iTrace file name with the .itrace extension.

    Security noteSecurity Note

    Provide the full path, not a relative path.

    PathToAppExecutableFileAndFileName

    The path and file name of your managed app

  2. Stop data collection by exiting the app.

  3. Open the .iTrace file in Visual Studio Ultimate.

  1. Move the .iTrace file or copy it to a computer with Visual Studio Ultimate.

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

    Visual Studio shows the IntelliTrace Summary page. In most sections, you can review events or other items, choose an item, and start debugging with IntelliTrace at the point where and when an event happened. See Debug Your App with IntelliTrace Log (.iTrace) Files.

    NoteNote

    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.

IntelliTrace can collect lots of data, so the impact on your app's performance depends on the data that IntelliTrace collects and the kind of code it analyzes. See Optimizing IntelliTrace Collection on Production Servers.

Here are some ways to get the most data without slowing down your app:

  • Run the collector only when you think there’s a problem, or when you can reproduce the problem.

    Start collection, reproduce the problem, and then stop collection. Open the .iTrace file in Visual Studio Ultimate and examine the data. See Open the IntelliTrace log file in Visual Studio Ultimate..

  • For Web apps and SharePoint applications, the collector records data for every app that shares the specified application pool. This might slow down any app that shares the same application pool, even though you can only specify modules for a single app in a collection plan.

    To prevent the collector from slowing down other apps, host each app in its own application pool.

  • Review the events in the collection plan for which IntelliTrace collects data. Edit the collection plan to disable events that aren't relevant or don't interest you.

    To disable an event, set the enabled attribute for the <DiagnosticEventSpecification> element to false:

    <DiagnosticEventSpecification enabled="false">

    If the enabled attribute doesn't exist, the event is enabled.

    How does this improve performance?

    • You can reduce startup time by disabling events that aren't relevant to the app. For example, disable Windows Workflow events for apps that don't use Windows Workflow.

    • You can improve both startup and runtime performance by disabling registry events for apps that access the registry but don't show problems with registry settings.

  • Review the modules in the collection plan for which IntelliTrace collects data. Edit the collection plan to include only the modules that interest you:

    1. Open the collection plan. Find the <ModuleList> element.

    2. In <ModuleList>, set the isExclusionList attribute to false.

    3. Use the <Name> element to specify each module with one of the following: file name, string value to include any module whose name contains that string, or public key.

    For example, to collect data from just the main Web module of the Fabrikam Fiber Web app, create a list like this one:

    <ModuleList isExclusionList="false">
       <Name>FabrikamFiber.Web.dll</Name>
    </ModuleList>
    

    To collect data from any module whose name includes "Fabrikam", create a list like this one:

    <ModuleList isExclusionList="false">
       <Name>Fabrikam</Name>
    </ModuleList>
    

    To collect data from modules by specifying their public key tokens, create a list like this one:

    <ModuleList isExclusionList="false">
       <Name>PublicKeyToken:B77A5C561934E089</Name>
       <Name>PublicKeyToken:B03F5F7F11D50A3A</Name>
       <Name>PublicKeyToken:31BF3856AD364E35</Name>
       <Name>PublicKeyToken:89845DCD8080CC91</Name>
       <Name>PublicKeyToken:71E9BCE111E9429C</Name>
    </ModuleList>
    

    How does this improve performance?

    This reduces the amount of method call information and other instrumentation data that IntelliTrace collects when the app starts and runs. This data lets you:

    • Step through code after collecting the data.

    • Examine values passed to and returned from function calls.

    Why not exclude modules instead?

    By default, collection plans exclude modules by setting the isExclusionList attribute to true. However, excluding modules might still result in collecting data from modules that don't meet the list's criteria and might not interest you, such as third-party or open-source modules.

  • Is there any data that IntelliTrace doesn't collect?

    Yes, to reduce performance impact, IntelliTrace restricts data collection to values of primitive data types passed to and returned from methods and to values of primitive data types in fields on top-level objects passed to and returned from methods.

    For example, suppose you have an AlterEmployee method signature that accepts an integer id and an Employee object oldemployee:

    public Employee AlterEmployee(int id, Employee oldemployee)

    The Employee type has the following attributes: Id, Name, and HomeAddress. An association relationship exists between Employee and the Address type.

    Relationship between Employee and Address

    The collector records values for id, Employee.Id, Employee.Name and the Employee object returned from the AlterEmployee method. However, the collector doesn't record information about the Address object other than whether it was null or not. The collector also doesn't record data about local variables in the AlterEmployee method unless other methods use those local variables as parameters at which point they are recorded as method parameters.

Did you find this helpful?
(1500 characters remaining)
Thank you for your feedback
Show:
© 2014 Microsoft. All rights reserved.