APM Insight using .NET Agent

APM Insight provides you with unique visibility, ability to analyze user-satisfaction and faster troubleshooting of .NET Web Transactions. It is a comprehensive solution to monitor the performance of complex .NET applications from end user to database perspective.

Monitor .NET Web Transactions

To configure APM Insight for .NET transactions you must deploy the APM Insight agent in your Application Server. The agent, instrumented into your .NET application collects the data (Metric/traces) and sends it to the APM Insight server which generates performance charts. This information is assembled and presented in detail in the APM Insight dashboard.

Installation Requirements

1. Applications running Microsoft .NET Framework Version 3.0 and above.
2. IIS 6.0 and above.

Install APM Agent using .NET Agent 

1. Select APM > APM Insight.
2. Click on .NET tab and follow the instructions to download the agent.
   
    
3. Click download to get agent .msi file.
4. Run the .msi file. This opens a select installation folder window.
5. Click on Browse and select the folder path to install the .NET Agent. Click Next.
6. In the next window, under the Startup Options, check the Start the Agent after installation check-box if you wish to start the agent. Click Next to start installation of the agent.
7. A .NET Agent Configuration window appears before the installation is completed. 
8. Copy and Paste the license key value from the Site24x7 APM Insight home page, after login.
9. Click the Save button to complete installation. 
10. The .NET agent is ready and all the ASP.NET applications running on the server will be monitored. The collected data should be available in the Site24x7 APM Insight Edition page within a few minutes. All .NET web applications hosted on the IIS will be monitored. 
    

Managing the Agent

After installation,the operations that you can perform on the agent are start .NET Agent, stop .NET Agent and edit .NET Agent Configuration.

Starting the .NET Agent

1. If you have not checked the Start the Agent after installation check-box, during installation, manually start the agent service from Windows Service Manager. The service name is APM Insight .NET Agent.
2. Starting the agent service resets the IIS and sets the environment variables of the profiler.

Editing the .NET Agent Configuration

1. Click on Edit Configuration from the APM Insight .NET Agent folder in the Start Menu to edit the agent configuration.
2. This opens the .NET agent configuration dialog box. After making the required changes, click Save to update the configuration file.

Stopping the .NET Agent

1. You can stop the agent service manually from the Windows Service Manager. This will close the IPC connection between the application and the service; removing the profiler variable from system environment variables and disabling the profiler. It also resets the IIS.
2. You can manually re-start the agent as mentioned above in Starting the .NET Agent.
3. You can uninstall the agent from the Start menu. Click on Uninstall .NET Agent from the APM Insight .NET Agent folder in the Start Menu to uninstall the agent.

APM Insight Configuration

1. This helps you fine tune the configuration for tracking web based transactions. These settings can be configured in apminsight.conf file.
2. Refer here to know about APM Insight configuration options.

Configure AppFilter

Application Filters helps you decide which applications you want to monitor from your IIS server.

Filtering Web Applications in settings dialog

Agent version 2.0 and above

1. Stop the .NET Agent windows service.
2. Launch Edit Configuration window (Start Menu > Edit Configuration). This dialog is launched automatically during installation.
   
   Agent below v2.3; Launch by (Start Menu > Edit Configuration (x64 or x86)).
3. If apminsight.appname key is present in any of the web applications in IIS, the dialog will give an option to remove them. From v2.0, this dependency has been removed.
4. Go to AppFilters tab.
5. Select Use App Filters.
6. Select applications to be monitored. By default, all applications will be selected for monitoring.
7. Provide applications a unique name in the text box under column Apm Insight key. This will not affect the IIS.
8. Click Save.

   

9. Start the .NET Agent windows service.

Agent below v2.0

1. Launch Edit Configuration window (Start Menu > Edit Configuration (x64 or x86)). This dialog is launched automatically during installation.
2. Go to AppFilters tab.
3. Select Use App Filters.
4. Select Use ApmInsight keys. This will add a key apminsight.appname to the selected applications in their respective web.config file, under section appSettings.
5. Select applications to be monitored. By default, all applications will be selected for monitoring.
6. Provide applications a unique name in the text box under column Apm Insight key. Column will be hidden if Use ApmInsight keys in step 4 is not selected.
7. Click Save.
8. Restart .NET Agent windows service to effect changes.

Filtering Web Applications Manually

.NET Agent v2.0 and above - Changes in agent configuration

1. Go to the APM Insight .NET Agent installation folder.
2. Open DotNetAgent folder.
3. Open appfilter.conf file and edit the following keys,
   
   use.app.filters=true (default)
   use.apminsight.appnames=true (default is false)
   include.app.names={json formatted appnames}
   Example:
   include.app.names = { "Default Web Site/" : "ServerRoot", "Default Web Site/Services/wcf1" : "Service1", ... }
4. Copy this appfilter.conf file and paste it in the following location
   
   1. • Agent v2.3 and above
        • Agent data path,
          
          %WINDIR%\\ProgramData\\DotnetAgent
        • Agent data path for Windows server 2003,
          %WINDIR%\\Documents and Settings\\All Users\\Application Data\\DotNetAgent

   • Agent below v2.3

     • For 64-bit agent
       %WINDIR%\\ProgramData\\DotnetAgent\\x64 
     • For Windows server 2003, the corresponding path will be in
       %WINDIR%\\Documents and Settings\\All Users\\Application Data\\DotNetAgent\\x64
     • For 32-bit agent
       %WINDIR%\\ProgramData\\DotnetAgent\\x86
     • For Windows server 2003, the corresponding path will be in
       %WINDIR%\\Documents and Settings\\All Users\\Application Data\\DotNetAgent\\x86
   • In case of multimonitors, all sub folders in the above locations.
5. Restart the .NET Agent windows service to effect changes

Agents below v2.0-Changes in IIS Manager

1. Launch IIS Manager.
2. Select web application
3. For IIS 7.0 and above, Go to Application Settings section & add the following key value pair. This is required to avoid conflicts in application names.
   
   key = apminsight.appname
   value = <custom application name> (Use this name in configuration file)
4. For IIS version 6.0, open the web.Config file and edit <appSettings> section as follows.
   
   <appSettings>
   <add key="apminsight.appname" value="<custom application name>"/>
   ...
   </appSettings>
5. Save the web.Config
6. Repeat the steps for all applications to be monitored.

Agents below v2.0-Changes in Agent configuration

1. Go to the APM Insight .NET Agent installation folder.
2. Open DotNetAgent folder.
3. Open apminsight.conf file and edit the following keys,
   
   use.app.filters=true (default)
   use.apminsight.appnames=true (default is false)
   include.app.names=<comma seperated appnames>
4. Provide the app names exactly as given in the appSettings section
5. Copy this apminsight.conf file and paste it in the following location:
   • For 64-bit agent
     %WINDIR%\\ProgramData\\DotnetAgent\\x64
     For Windows server 2003, the corresponding path will be in
     %WINDIR%\Documents and Settings\All Users\Application Data\DotNetAgent\x64\
   • For 32-bit agent
     %WINDIR%\\ProgramData\\DotnetAgent\\x86
     For Windows server 2003, the corresponding path will be in
     %WINDIR%\Documents and Settings\All Users\Application Data\DotNetAgent\x86\
     †In case of multimonitors, all sub folders in the above locations.
6. Restart the .NET Agent windows service to effect changes.

Tracking Background Transaction

1. To configure settings for background transaction, refer here.

Grouping Similar Transaction

Dynamic Transaction names are becoming more familiar with lots of applications, making it difficult to actually track the performance of the application. Dynamic transactions are web transactions within an application having single URL but get appended with unique alpha numeric identifiers every time they are invoked, making the web transaction name itself look different. Tracking such individual URLs is a herculean task. Here, this feature of grouping similar transactions, will help to group these dynamic transactions into the actual URL that needs to be monitored.

Configuration Steps for .NET Agent:

1. Open Edit configuration window, select Transactions Merge tab. Add transaction patterns you want to merge.
   
    
2. See grouping transaction with pattern sample here.
3. Steps to do transaction merge pattern configurations manually:
4. Go to the APM Insight .NET Agent installation folder after installing the agent.
5. Open DotNetAgent folder.
6. Open transaction_merge_patterns.conf and add the patterns as mentioned here.
7. Copy this transaction_merge_patterns.conf file and paste it in the following location.
   • Agent v2.3 and above
     • Agent data path,
       
       %WINDIR%\\ProgramData\\DotnetAgent
     • Agent data path for Windows server 2003,
       %WINDIR%\\Documents and Settings\\All Users\\Application Data\\DotNetAgent
   • Agent below v2.3
   • • For 64-bit agent
       
       %WINDIR%\\ProgramData\\DotnetAgent\\x64
     • For Windows server 2003, the corresponding path will be in
       
       %WINDIR%\\Documents and Settings\\All Users\\Application Data\\DotNetAgent\\x64
     • For 32-bit agent
       
       %WINDIR%\\ProgramData\\DotnetAgent†\\x86
     • For Windows server 2003, the corresponding path will be in
       
       %WINDIR%\\Documents and Settings\\All Users\\Application Data\\DotNetAgent\\x86
8. †In case of multi-monitors, all sub folders for every application in the above locations.
9. We can add, remove or comment the patterns at any point of time in the configuration file.

Transaction Merge Pattern Samples

1. The below pattern will match with all transactions which start with aspsite/account/ and it will be renamed as account.
   
   aspsite/account/*=account
2. The below pattern will match with all transactions which start with aspsite/ and end with /basicdetails. They will be renamed as basicdetails.
   
   aspsite/*/basicdetails=basicdetails
3. The above pattern will match with all transactions which end with /educationdetails and it will be renamed as educationdetails.
   
   */educationdetails=educationdetails

.NET Agent API for Custom Instrumentation

APM Insight .NET Agent API helps to track the user defined methods in a web application. It helps instrument specified methods in the web application DLLs for monitoring its performance. It can also be used to track specific parts of code.

Steps to Add the API

1. Add a reference to the library DotNetAgent.Api.dll to your web application project.
2. The API dll is available in the API Manager Tool installed location (C:\Program Files (x86)\APM Insight\APM Insight.NET Agent\AgentApi\DotNetAgent.Api.dll)
   
   For Agent below v2.3, locate the API dll from,(C:\Program Files\APM Insight\APM Insight .NET Agent (<x64 or x86>)\AgentApi\DotNetAgent.Api.dll)
3. The API contains a class named CustomTracker to track the performance of a method.

   CustomTracker Class and its Methods

   Constructors

   CustomTracker(Type thisType)

   • thisType - The type of current class or base class.

             eg: CustomTracker dotNetAgentCustomTracker = new CustomTracker(this.GetType());>

   CustomTracker(Type thisType, string methodName)

   • thisType - The type of current class or base class.
   • methodName - The name of the method to be monitored.

             eg: CustomTracker dotNetAgentCustomTracker = new CustomTracker(this.GetType(),"BasicDetails");

   CustomTracker(Type thisType, string className, string methodName)

   • thisType - The type of current class or base class.
   • className - The name of the class to be monitored.
   • methodName - The name of the method to be monitored.

             eg: CustomTracker dotNetAgentCustomTracker = new CustomTracker(this.GetType(), "EmpController", "BasicDetails");

   CustomTracker.StartTracker (Type thisType, string className, string methodName)

   • This method is used to start the metric collection for the custom method.
   • It is not required as it is called in constructor itself.

   CustomTracker.StopTracker()

   • The metric collection will be stopped on calling this method.
   • Always call it in a finally block.
4. Create an instance of CustomTracker class at the beginning of a method and invoke StopTracker() at the end of the method.
5. We can create CustomTracker instance with using{} block. The StopTracker() method will be called when disposing object automatically.

The following examples show the usage of this CustomTracker:

Example 1: Using the "using" statement:

Example 2: Using StartTracker and StopTracker within a try finally block:

Example 3: Using CustomTracker to Instrument part of a code.

Steps for Deploying the Agent in Azure Environment

Agent v2.3 and above

1. Add the following to the WebRole project and set their "Copy to Output" property to "Copy Always".
   a. .NET agent Installer (apminsight­-dotnetagent­.msi),
   b. The "apminsight.conf" file, containing license key and other configuration options, and,
   c. The batch file, "deploy­-apminsight.cmd".

2. Add a startup task in the service definition (.csdef) file as follows :
    <ServiceDefinition>
      <WebRole>
         <Startup>
           <Task commandLine="deploy­-apminsight.cmd configfile=apminsight.conf
   appfilterconfigfile=appfilter.conf multimonitor=true/false"
   executionContext="elevated" taskType="background"/>
         </Startup>
      </WebRole>
   </ServiceDefinition>

Agent below v2.3

1. Add the following to the WebRole project and set their "Copy to Output" property to "Copy Always".
   a. .NET agent Installer (apminsight­-dotnetagent­-x64.msi or apminsight­-dotnetagent­-x86.msi),
   b. The "apminsight.conf" file, containing license key and other configuration options, and,
   c. The batch file, "deploy­-apminsight-­x64.cmd" (or deploy­-apminsight-­x86.cmd).

2. Add a startup task in the service definition (.csdef) file as follows :
    <ServiceDefinition>
      <WebRole>
         <Startup>
           <Task commandLine="deploy­-apminsight-x64.cmd configfile=apminsight.conf
   appfilterconfigfile=appfilter.conf multimonitor=true/false"
   executionContext="elevated" taskType="background"/>
         </Startup>
      </WebRole>
   </ServiceDefinition>

Monitor Select Applications Using Application Filters

Add the parameter appfilterconfigfile=appfilter.conf to monitor only select applications (as mentioned in the commandline task). This should contain the App Filter related configurations (include.app.names and use.appfilter). Follow the steps here to configure app filters manually. It is recommended to do this configuration via UI in an identical setup and copy the config file if possible.

To deploy:

1. You can publish the cloud service from Visual Studio itself or
2. Bundle it into a package and upload the package in your Azure Portal from your CloudService (Update). 

Known Issues and Workarounds

In Azure machines, the "W3SVC" service (World Wide Web Publishing Service) has its startup type as "Manual" by default. This might cause a "Service Unavailable" issue when visiting websites after .NET agent is installed (IIS reset happens during installation). Set this startup type to "Automatic" to workaround this issue. This can be achieved by adding the following line in the batch file before the installation command, sc config w3svc start= auto.

Agent v2.3 and above

Copy and paste the below script in a new text file and name it as deploy­-apminsight.cmd.

deploy­-apminsight.cmd

Agent below v2.3

Copy and paste the below script in a new text file and name it as deploy­-apminsight-x64.cmd. For an x86 agent create a similar script with the x86 msi file name.

deploy­-apminsight-x64.cmd

Use Health Monitor

1. The Health monitor is a self diagnostic tool, intended to provide a snapshot of the agent settings, for identifying and troubleshooting frequently encountered configuration issues in the agent. It is available, as a feature, from APM Insight .NET agent version 1.8 and above.
2. It can be found in the start menu under "APM Insight .NET Agent" folder.
3. With the HealthMonitor, you can
   • Create Diagnostic zip file - The HealthMonitor captures all agent logs, and other system information, necessary to analyze the issue by the support team. Optionally, event log information could also be appended.[ii] Include this zip file in support cases.
     
   • View Service settings - Agent service mode (i.e., single/multi- instance), APM agent service status (running/stopped) and log level.
   • Check Network connectivity- For successful communication, the APM Insight agent must be able to connect to site24x7.com's servers, under ports 80 and 443. Please verify if these ports are not blocked by firewall or anti-virus software.
   • Check Application filters - If application filters are applied, verify if the applications running are monitored. Please refer AppFilters. 
   • Monitor worker processes - If no worker processes are shown as running, perform some transactions and retry.
     
     In Agent below v2.3, If worker processes are still not counted, then it could be due to the bitness of the agent. APM Insight agent and the worker processes should have the same bit. (i.e., 32-bit agent for 32-bit applications, and 64-bit agent for 64-bit applications)
   • Verify monitor status - The status of the monitor (i.e., Managed/UnManaged/Deleted etc) will be displayed, under the monitor name,.For single instance, only one monitor will be listed. For multi instance, all the monitors created by the agent would be listed.
   • Verify profiler status - In order to successfully instrument the IIS applications, the profiler has to be loaded into the worker process. If the profiler loading failed, an IIS Reset must be performed to re-load the profiler. Also, ensure that some other profiling agents are not installed in the same machine (i.e. there can be only one active profiler in a machine).