Using the Microsoft Monitoring Agent (C#, Visual Basic)

Article
11/04/2016

Applies to: Visual Studio Visual Studio for Mac

Note

This article applies to Visual Studio 2017. If you're looking for the latest Visual Studio documentation, see Visual Studio documentation. We recommend upgrading to the latest version of Visual Studio. Download it here

You can locally monitor IIS-hosted ASP.NET web apps and SharePoint 2010 or 2013 applications for errors, performance issues, or other problems by using Microsoft Monitoring Agent. You can save diagnostic events from the agent to an IntelliTrace log (.iTrace) file. You can then open the log in Visual Studio Enterprise (but not Professional or Community editions) to debug problems with all the Visual Studio diagnostic tools. You can also collect IntelliTrace diagnostic data and method data by running the agent in Trace mode. Microsoft Monitoring Agent can be integrated with Application Insights and System Center Operation Manager. Microsoft Monitoring Agent does alter the target system's environment when it is installed.

Note

You can also collect IntelliTrace diagnostic and method data for web, SharePoint, WPF, and Windows Form apps on remote machines without changing the target environment by using the IntelliTrace stand-alone collector. The stand-alone collector has a greater performance impact than running the Microsoft Monitoring Agent in Monitor mode. See Using the IntelliTrace stand-alone collector.

If you use System Center 2012, use Microsoft Monitoring Agent with Operations Manager to get alerts about problems and create Team Foundation Server work items with links to the saved IntelliTrace logs. You can then assign these work items to others for further debugging. See Integrating Operations Manager with Development Processes and Monitoring with Microsoft Monitoring Agent.

Before you start, check that you have the matching source and symbols for the built and deployed code. This helps you go directly to the application code when you start debugging and browsing diagnostic events in the IntelliTrace log. Set up your builds so that Visual Studio can automatically find and open the matching source for your deployed code.

Step 1: Set up Microsoft Monitoring Agent
Step 2: Start monitoring your app
Step 3: Save recorded events

Step 1: Set up Microsoft Monitoring Agent

Set up the standalone agent on your web server to perform local monitoring without changing your application. If you use System Center 2012, see Installing Microsoft Monitoring Agent.

Set up the standalone agent

Make sure that:
- Your web server is running supported versions of Internet Information Services (IIS).
- Your web server has .NET Framework 3.5, 4, or 4.5.
- Your web server is running Windows PowerShell 3.0 or later. Q: What if I have Windows PowerShell 2.0?
- You have administrator permissions on your web server to run PowerShell commands and to recycle the application pool when you start monitoring.
- You've uninstalled any earlier versions of Microsoft Monitoring Agent.
Download the free Microsoft Monitoring Agent, either the 32-bit version MMASetup-i386.exe or 64-bit version MMASetup-AMD64.exe, from the Microsoft Download Center to your web server.
Run the downloaded executable to start the installation wizard.
Create a secure directory on your web server to store the IntelliTrace logs, for example, C:\IntelliTraceLogs.

Make sure that you create this directory before you start monitoring. To avoid slowing down your app, choose a location on a local high-speed disk that's not very active.

Important

IntelliTrace logs might contain personal and sensitive data. Restrict this directory to only those identities that must work with the files. Check your company's privacy policies.
To run detailed, function-level monitoring or to monitor SharePoint applications, give the application pool that hosts your web app or SharePoint application read and write permissions to the IntelliTrace log directory. Q: How do I set up permissions for the application pool?

Q & A

Q: What if I have Windows PowerShell 2.0?

A: We strongly recommend that you use PowerShell 3.0. Otherwise, you'll have to import the Microsoft Monitoring Agent PowerShell cmdlets each time you run PowerShell. You also won't have access to downloadable Help content.

Open a Windows PowerShell or Windows PowerShell ISE command prompt window as an administrator.
Import the Microsoft Monitoring Agent PowerShell module from the default installation location:

PS C:>Import-Module "C:\Program Files\Microsoft Monitoring Agent\Agent\PowerShell\Microsoft.MonitoringAgent.PowerShell\Microsoft.MonitoringAgent.PowerShell.dll"
Visit TechNet to get the most recent Help content.

Q: How do I set up permissions for the application pool?

A: 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:\IntelliTraceLogs" /grant "IIS APPPOOL\DefaultAppPool":RX
- For a SharePoint application in the SharePoint - 80 application pool:
  
  icacls "C:\IntelliTraceLogs" /grant "IIS APPPOOL\SharePoint - 80":RX
  
  -or-
To set up permissions with Windows Explorer (or File Explorer):
1. Open Properties for the IntelliTrace log directory.
2. On the Security tab, choose Edit, Add.
3. Make sure that 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 Read & execute permissions.

Step 2: Start monitoring your app

Use the Windows PowerShell Start-WebApplicationMonitoring command to start monitoring your app. If you use System Center 2012, see Monitoring Web Applications with Microsoft Monitoring Agent.

On your web server, open a Windows PowerShell or Windows PowerShell ISE command prompt window as an administrator.

Run the Start-WebApplicationMonitoring command to start monitoring your app. This will restart all the web apps on your web server.

Here's the short syntax:

Start-WebApplicationMonitoring "<appName>" <monitoringMode> "<outputPath>" <UInt32> "<collectionPlanPathAndFileName>"

Here's an example that uses just the web app name and lightweight Monitor mode:

PS C:>Start-WebApplicationMonitoring "FabrikamFabrikamFiber.Web" Monitor "C:IntelliTraceLogs"

Here's an example that uses the IIS path and lightweight Monitor mode:

PS C:>Start-WebApplicationMonitoring "IIS:sitesFabrikamFabrikamFiber.Web" Monitor "C:IntelliTraceLogs"

After you start monitoring, you might see the Microsoft Monitoring Agent pause while your apps restart.

Start monitoring with MMA confirmation

Name	Description
"<appName>"	Specify the path to the web site and web app name in IIS. You can also include the IIS path, if you prefer. "<IISWebsiteName>\<IISWebAppName>" -or- "IIS:\sites \<IISWebsiteName>\<IISWebAppName>" You can find this path in IIS Manager. For example: You can also use the Get-WebSite and Get WebApplication commands.
<monitoringMode>	Specify the monitoring mode: Monitor: Record minimal details about exception events and performance events. This mode uses the default collection plan. Trace: Record function-level details or monitor SharePoint 2010 and SharePoint 2013 applications by using the specified collection plan. This mode might make your app run more slowly. Q: How do I set up permissions for the application pool? Q: How do I get the most data without slowing down my app? This example records events for a SharePoint app hosted on a SharePoint site: Start-WebApplicationMonitoring "FabrikamSharePointSite\FabrikamSharePointApp" Trace "C:\Program Files\Microsoft Monitoring Agent\Agent\IntelliTraceCollector\collection_plan.ASP.NET.default.xml" "C:\IntelliTraceLogs" Custom: Record custom details by using specified custom collection plan. You'll have to restart monitoring if you edit the collection plan after monitoring has already started.
"<outputPath>"	Specify the full directory path to store the IntelliTrace logs. Make sure that you create this directory before you start monitoring.
<UInt32>	Specify the maximum size for the IntelliTrace log. The default maximum size of the IntelliTrace log is 250 MB. When the log reaches this limit, the agent overwrites the earliest entries to make space for more entries. To change this limit, use the -MaximumFileSizeInMegabytes option or edit the `MaximumLogFileSize` attribute in the collection plan.
"<collectionPlanPathAndFileName>"	Specify the full path or relative path and the file name of the collection plan. This plan is an .xml file that configures settings for the agent. These plans are included with the agent and work with web apps and SharePoint applications: - collection_plan.ASP.NET.default.xml Collects only events, such as exceptions, performance events, database calls, and Web server requests. - collection_plan.ASP.NET.trace.xml Collects function-level calls plus all the data in default collection plan. This plan is good for detailed analysis but might slow down your app. You can find localized versions of these plans in the agent's subfolders. You can also customize these plans or create your own plans to avoid slowing down your app. Put any custom plans in the same secure location as the agent. Q: How do I get the most data without slowing down my app?

For the more information about the full syntax and other examples, run the get-help Start-WebApplicationMonitoring -detailed command or the get-help Start-WebApplicationMonitoring -examples command.

To check the status of all monitored web apps, run the Get-WebApplicationMonitoringStatus command.

Q & A

Q: How do I get the most data without slowing down my app?

A: Microsoft Monitoring Agent can collect lots of data and affects your app's performance depending on the data that you choose to collect and how you collect it. Here are some ways to get the most data without slowing down your app:

For web apps and SharePoint applications, the agent 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 restrict collection to the modules for a single app. To avoid slowing down other apps, host each app in its own application pool.
Review the events for which the agent collects data in the collection plan. Edit the collection plan to disable events that aren't relevant or don't interest you. This can improve startup performance and run-time performance.

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.

For example:
- Disable Windows Workflow events for apps that don't use Windows Workflow.
- Disable registry events for apps that access the registry but don't show problems with registry settings.
Review the modules for which the agent collects data in the collection plan. Edit the collection plan to include only the modules that interest you.

This reduces how much method call information and other instrumentation data that the agent collects when the app starts and runs. This data helps you to step through code when you're debugging and reviewing values passed into and returned from function calls.
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.
  
  This example creates a list that collects data only from the main module of the Fabrikam Fiber web app:
```
<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>
```
Q: Why not just exclude modules instead?

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

Q: What values does the agent collect?

A: To reduce impact on performance, the agent collects only these values:

Primitive data types that are passed into and returned from methods
Primitive data types in fields for top-level objects passed into 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 agent records values for id, Employee.Id, Employee.Name and the Employee object returned from the AlterEmployee method. However, the agent doesn't record information about the Address object other than whether it was null or not. The agent 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.

Step 3: Save recorded events

When you find an error or a performance issue, save the recorded events to an IntelliTrace log. The agent creates the log only if it recorded events. If you use System Center 2012, see Monitoring Web Applications with Microsoft Monitoring Agent.

Save recorded events but continue monitoring

Follow these steps when you want to create the IntelliTrace log but don't want to restart your app or stop monitoring. The agent continues monitoring even if the server or application restarts.

On your web server, open a Windows PowerShell command prompt window as an administrator.
Run the Checkpoint-WebApplicationMonitoring command to save a snapshot of the IntelliTrace log:

Checkpoint-WebApplicationMonitoring "<IISWebsiteName>\<IISWebAppName>"

- or -

Checkpoint-WebApplicationMonitoring "IIS:\sites \<IISWebsiteName>\<IISWebAppName>"

For example:

PS C:\>Checkpoint-WebApplicationMonitoring "Fabrikam\FabrikamFiber.Web"

-or-

PS C:>Checkpoint-WebApplicationMonitoring "IIS:sitesFabrikamFabrikamFiber.Web"

For more information, run the get-help Checkpoint-WebApplicationMonitoring -detailed command or the get-help Checkpoint-WebApplicationMonitoring -examples command.
Copy the log to a secure shared folder, and then open the log from a computer that has Visual Studio Enterprise (but not Professional or Community editions).

Important

Be cautious when you share IntelliTrace logs because they might contain personal and sensitive data. Make sure that whoever can access these logs has permissions to look at that data. Check your company's privacy policies.

Next: Diagnose recorded events in Visual Studio Enterprise

Save recorded events and stop monitoring

Follow these steps when you just want to get diagnostic information while reproducing a specific problem. This will restart all the web apps on your web server.

On your web server, open a Windows PowerShell command prompt window as an administrator.
Run the Stop-WebApplicationMonitoring command to create the IntelliTrace log and stop monitoring a specific web app:

Stop-WebApplicationMonitoring "<IISWebsiteName>\<IISWebAppName>"

- or -

Stop-WebApplicationMonitoring "IIS:\sites \<IISWebsiteName>\<IISWebAppName>"

Or to stop monitoring all web apps:

Stop-WebApplicationMonitoring -All

For example:

PS C:\>Stop-WebApplicationMonitoring "Fabrikam\iFabrikamFiber.Web"

- or -

PS C:\>Stop-WebApplicationMonitoring "IIS:\sites\Fabrikam\FabrikamFiber.Web"

For more information, run the get-help Stop-WebApplicationMonitoring -detailed command or the get-help Stop-WebApplicationMonitoring -examples command.
Copy the log to a secure shared folder, and then open the log from a computer that has Visual Studio Enterprise.

Next: Diagnose recorded events in Visual Studio Enterprise

Q & A

Q: Where can I get more information?

Blogs

Introducing Microsoft Monitoring Agent

Optimizing IntelliTrace Collection on Production Servers

Forums

Visual Studio Diagnostics

Using the Microsoft Monitoring Agent (C#, Visual Basic)

Step 1: Set up Microsoft Monitoring Agent

Set up the standalone agent

Q & A

Q: What if I have Windows PowerShell 2.0?

Q: How do I set up permissions for the application pool?

Step 2: Start monitoring your app

Q & A

Q: How do I get the most data without slowing down my app?

Q: What values does the agent collect?

Step 3: Save recorded events

Save recorded events but continue monitoring

Save recorded events and stop monitoring

Q & A

Q: Where can I get more information?

Blogs

Forums

Ressources supplémentaires