|
ManageEngine® Applications Manager APM Insight .NET Agent | ||
Applications Manager's .NET agent gives you insight into the way your .NET web-transactions work; helping you quickly drill-down to the root cause of issues. Now you can resolve performance degradation of .NET applications, no matter where they originate. Just download the latest .NET Agent and deploy it in your application server.
Click on the links below to learn more about the working of .NET agent and its usage:
The .NET Agent, instrumented into the application using .NET profiling API, collects the data (Metric/traces) and sends it to the Agent service through the Inter Process Communication (IPC). The Agent service, in turn, receives the data from the .NET agent and sends it to Applications Manager through a scheduler.
Installation Requirements
Applications running Microsoft .NET Framework Version 3.0 and above.
IIS 6.0 and above.
Installation Instructions
Click APM Insight tab.
Click on .NET tab to download the file.
Click Download to deploy the agent in your application server.
Run the .msi file . This opens a "select installation folder" window.
Click on Browse and select the folder path to install the .NET Agent. Click Next.
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.
A .NET Agent Configuration window appears before the installation is completed. Configure Applications Manager's host and port and other apdex settings.
Click the Save button to complete installation.
Now 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 apm-insight tab of Applications Manager's web client within a few minutes.
If you have not checked the Start the Agent after installation check-box in the Startup Options dialog box during installation, manually start the agent service from Windows Service Manager. The service name is ManageEngine .NET Agent. Starting the agent service resets the IIS and sets the environment variables of the profiler.
Editing the .NET Agent Configuration
Click on Edit Configuration from the ManageEngine .NET Agent folder in the Start Menu to edit the agent configuration. This opens the .NET agent configuration dialog box. After making the required changes, click Save to update the configuration file.
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 variables from system environment variables and disabling the profiler. It also resets the IIS.
You can manually re-start the agent as mentioned above in Starting the .NET Agent.
APM Insight Configuration
This helps you fine-tune the configuration for tracking web based transactions. These settings can be configured in *.conf file.
Refer here to know about APM Insight configuration options.
You can uninstall the agent from the Start menu. Click on Uninstall .NET Agent from the ManageEngine .NET Agent folder in the Start Menu to uninstall the agent.
You can choose individual application that you would want to monitor in your IIS server and view individual application metrics on your console. With this new feature you get the flexibility to add or remove monitoring of applications hosted under an IIS server.
Filtering Web Applications in settings dialog
For Agent Version 2.3 and above
Stop the .NET Agent windows service (during installation, skip this step).
Launch Edit Configuration window (Start Menu > Edit Configuration). This dialog is launched automatically during installation.
If apminsight.appname key is present in any of the web applications in IIS, the dialog will give an option to remove them.
Go to AppFilters tab.
Select Use App Filters.
Select applications to be monitored. By default, all applications will be selected for monitoring.
Provide applications a unique name in the text box under column Apm Insight key. This will not affect the IIS.
Click Save.
Start the .NET Agent windows service.
1. Versions 2.0 to 2.3
Stop the .NET Agent windows service (during installation, skip this step).
Launch Edit Configuration window from (Start Menu > Edit Configuration (x64 or x86). This dialog is launched automatically during installation.
If apminsight.appname key is present in any of the web applications in IIS, the dialog will give an option to remove them. From Version 2.0, this dependency has been removed.
Go to AppFilters tab.
Select Use App Filters.
Select applications to be monitored. By default, all applications will be selected for monitoring.
Provide applications a unique name in the text box under column Apm Insight key. This will not affect the IIS.
Click Save.
Start the .NET Agent windows service.
2. Versions older than 2.0
Launch Edit Configuration window (Start Menu -> Edit Configuration (x64 or x86)). Note that, this dialog is launched automatically during installation.
Go to the AppFilters tab and select "Use App Filters".
Select multi-monitor checkbox in the general tab under application name group box if your applications have to be individually monitored
Select the Use ApmInsight keys option. This will add a key apminsight.appname to the selected applications in their respective web.config file, under the appSettings section.
Select applications to be monitored. By default, all applications will be selected for monitoring.
Provide applications a unique name in the text box under column Apm Insight key. (Column will be hidden if Use ApmInsight keys in step #3 is not selected)
Click Save.
Restart .NET Agent windows service to effect changes.
Filtering Web Applications Manually
For Agent Version 2.3 and above
Changes to be made in Agent configuration
Go to the APM Insight .NET Agent installation folder.
Open DotNetAgent folder.
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}
eg: include.app.names = { "Default Web Site/" : "ServerRoot", "Default Web Site/Services/wcf1" : "Service1", ... }
Copy this appfilter.conf file and paste it in the following location:
%WINDIR%\\ProgramData\\DotnetAgent
For Windows server 2003, the corresponding path will be in
%WINDIR%\\Documents and Settings\\All Users\\Application Data\\DotNetAgent\\
In case of multimonitors, all sub folders in the above locations.
Restart the .NET Agent windows service to effect changes.
1. Versions 2.0 to 2.3
Changes to be made in Agent configuration
Go to the APM Insight .NET Agent installation folder.
Open DotNetAgent folder.
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}
eg: include.app.names = { "Default Web Site/" : "ServerRoot", "Default Web Site/Services/wcf1" : "Service1", ... }
Copy this appfilter.conf file and paste it in the following location:
%WINDIR%\\ProgramData\\DotnetAgent\\x64 (for 64-bit agent)
%WINDIR%\\ProgramData\\DotnetAgent\\x86 (for 32-bit agent)
For Windows server 2003, the corresponding path will be in
%WINDIR%\\Documents and Settings\\All Users\\Application Data\\DotNetAgent\\x64 (for 64-bit agent)
%WINDIR%\\Documents and Settings\\All Users\\Application Data\\DotNetAgent\\x86 (for 32-bit agent)
In case of multimonitors, all sub folders in the above locations.
Restart the .NET Agent windows service to effect change.
To filter Web Applications you must make configuration changes in the following:
IIS Manager
Agent configuration
Changes to be made in IIS Manager
Launch IIS Manager.
Select web application.
For IIS 7.0 and newer versions- Go to Applications Settings section and add the following key value pair, to avoid conflicts in application names:
- key = apminsight.appname
- value = <custom application name> (Use this name in configuration file).
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>
Save the web.Config
Repeat the steps for all applications to be monitored.
Changes to be made in Agent configuration
Go to the APM Insight .NET Agent installation folder.
Open DotNetAgent folder.
Open apminsight.conf file and edit the following keys:
- use.apminsight.appnames=true (default is false)
- use.app.filters=true (default)
- include.app.names=<comma seperated appnames>
(NOTE: provide the app names exactly as given in the appSettings section)
Copy this apminsight.conf file and paste it in the following locations :
%WINDIR%\\ProgramData\\DotnetAgent\\x64 (for 64-bit agent)
%WINDIR%\\ProgramData\\DotnetAgent\\x86 (for 32-bit agent)
For Windows server 2003, the corresponding path will be in
%WINDIR%\Documents and Settings\All Users\Application Data\DotNetAgent\x64\ (for 64-bit agent)
%WINDIR%\\ProgramData\\DotnetAgent\\x86 (for 32-bit agent)
In case of multimonitors, all sub folders in the above locations.
Restart the .NET Agent windows service to effect changes.
Transaction Grouping
Configuration Steps for .NET Agent:
Open Edit configuration window, select Transactions Merge tab. Add transaction patterns you want to merge.
See grouping transaction with pattern sample here (refer #tm_samples).
Steps to perform transaction merge pattern configurations manually:
Go to the APM Insight .NET Agent installation folder after installing the agent.
Open DotNetAgent folder.
Open transaction_merge_patterns.conf and add the patterns as mentioned here (refer samples here).
Copy this transaction_merge_patterns.conf file and paste it in the location mentioned below.
%WINDIR%//ProgramData//DotnetAgent//
For Windows server 2003, the corresponding path will be in,
%WINDIR%//Documents and Settings//All Users//Application Data//DotNetAgent//
For 64-bit agent
%WINDIR%//ProgramData//DotnetAgent//
For Windows server 2003, the corresponding path will be in
%WINDIR%//Documents and Settings//All Users//Application Data//DotNetAgent//
For 32-bit agent
%WINDIR%//ProgramData//DotnetAgent//
For Windows server 2003, the corresponding path will be in
%WINDIR%//Documents and Settings//All Users//Application Data//DotNetAgent//
In case of multi-monitors, all sub folders for every application in the above locations.
We can add, remove or comment the patterns at any point of time in the configuration file.
Transaction Merge Pattern Samples
The below pattern will match with all transactions which start with aspsite/account/ and it will be renamed as account.
aspsite/account/*=account
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
The above pattern will match with all transactions which end with /educationdetails and it will be renamed as educationdetails.
*/educationdetails=educationdetails
Background Transactions
Applications Manager allows users the ability to monitor background processes and other jobs running within the web application.
Background trace threshold - You can enable the APM Insight agent to track the background transactions happening in the application server. It will collect traces of slow background transactions. Background transactions are considered to be slow, if it crosses the configured Background trace threshold.
Sampling counter - For example, if you specify the Sampling Factor value as 5, the agent will track one in 5 background transactions.
Use .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).
Note: 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:
public ActionResult BasicDetails(int id = 0)
{AdminBL objadmin = new AdminBL();
using(CustomTracker customTracker = new CustomTracker(base.GetType(),"BasicDetails"))
{ASPSite.BL.MYSQLReference.BasicDetails basicDetails = objadmin.getBasicDetails(id);
EmpApp.Models.BasicDetails basic = getBasicDetailsModel(basicDetails);
return View(basic);
}
}
Example 2: Using StartTracker and StopTracker within a try finally block:
public ActionResult BasicDetails(int id = 0)
{CustomTracker customTracker = null;
AdminBL adminBL = new AdminBL();
try
{
customTracker = new CustomTracker(base.GetType(),"BasicDetails");
ASPSite.BL.MYSQLReference.BasicDetails basicDetails = adminBL.getBasicDetails(id);
EmpApp.Models.BasicDetails basicDetailsModel = getBasicDetailsModel(basicDetails);
}
finally
{
customTracker.StopTracker();
}
return View(basicDetailsModel);
}
Example 3: Using CustomTracker to Instrument part of a code.
public ActionResult BasicDetails(int id = 0)
{AdminBL adminBL = new AdminBL();
using(CustomTracker customTracker = new CustomTracker(base.GetType(),"BasicDetails"))
{
//Instrumenting part of a code. To check the time taken by the function FetchAllEmployees and the SQL calls made from this function.
using(CustomTracker fetchAllEmpTracker = new CustomTracker(base.GetType(),"FetchAllEmployees"))
{
FetchAllEmployees();
}
ASPSite.BL.MYSQLReference.BasicDetails basicDetails = objadmin.getBasicDetails(id);EmpApp.Models.BasicDetails basic = getBasicDetailsModel(basicDetails);
}return View(basicDetailsModel);
}
Note:
- If the method name or class name is not given in the CustomTracker, it will attempt to get the current method name and class name by itself.
- The StartTracker() method will be called in constructor by default.
- If the agent not installed or the agent service stopped the invoked methods will have no effect.
Diagnostics tool
APM Insight .Net monitoring also features a diagnostics tool called HealthMonitor.exe. It monitors the health of the agent running in the server. 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. It can be found in the start menu under "APM Insight .NET Agent" folder. Click the button on the left bottom corner of the tool to collects logs and creates a zip file for better troubleshooting and support.
Troubleshooting with APM Insight .NET Agent HealthMonitor
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. You also have the option to append event log information. To include event logs, along with the diagnostic zip, run HealthMonitor.exe (found in Installation directory\HealthMonitor folder) via command prompt with "eventlogs" option. This requires administrative privileges.
View Service settings - The 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 server(s).
Check Application filters - If application filters are applied, verify if the applications running are monitored. Refer Application Filters guide.
Monitor worker processes - If no worker processes are shown as running, perform a transaction and retry.
Note : 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/LicenseExpired etc) will be displayed, under the monitor name. For a single instance, only one monitor will be listed. For multiple instances, all the monitors created by the agent would be listed.
Verify profiler status - In order to successfully instrument the IIS applications, the profiler must be loaded into the worker process. If the loading fails, 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).
Note:
In case of issues, please ensure that some transactions are done when the agent log level is "DEBUG" before creating the diagnostics zip. This would help us narrow down the issue quicker.
To include event logs, along with the diagnostic zip, select the 'Event logs' check box below 'Create Diagnotics zip file' button. This requires administrative privileges.
FAQ:
If you face problems during the installation or the .Net Agent, go to our .NET Agent FAQ page for troubleshooting tips.
APM Insight Ruby on Rails Agent
APM Insight Agent Configuration Options