APMInsight - NET Agent Onboarding - KB
Overview
This document provides a step-by-step guide to onboard and troubleshoot the APM Insight .NET Agent. It includes environment verification, permission checks, network connectivity validation, and solutions for common installation and configuration issues.
Prerequisites
Please note that restart of your application is necessary (i.e. IISRESET cmd execution for IIS sites, restart for windows service & desktop apps) to start monitoring after agent installationPrerequisites 1. Environment should aligns with our agent's supported components
To verify the environment, Run following cmd using windows powershell administrator mode
Get-ChildItem 'HKLM:\SOFTWARE\Microsoft\NET Framework Setup\NDP' -Recurse | Get-ItemProperty -Name Version, Release, SP -ErrorAction SilentlyContinue | Where-Object { $_.PSChildName -match '^(?!S)\p{L}'} | Select-Object PSChildName, Version, SP, Release- Confirm that .NET Framework v3.0 listed and has SP ≥ 1
- Confirm .NET Framework v4 (Full) listed and has Release ≥ 378389
If the prerequisites are met but the agent (.msi) installation still fails:
- Recheck prerequisites and try the `Installation via command line`.
- If issue still persists, locate the `apm_install.log` file in the installation directory & send the log file to appmanager-support@manageengine.com for further assistance.
Prerequisites 2. Network and Firewall
Outbound communication from the agent-installed machine to the Applications Manager (Host and Port) should be allowed — either directly or via a proxy.
To verify connectivity:
1. Get the configured the "Apm Endpoint Urls" from APM Insight .NET Agent Configuration tool
2. Open the same URL in a browser on the agent-installed machine and confirm it loads.
3. Run the below PowerShell command (as Administrator) using the same “Apm Endpoint Url”
add-type 'using System.Net;using System.Security.Cryptography.X509Certificates;public class TrustAllCertsPolicy : ICertificatePolicy {public bool CheckValidationResult(ServicePoint a,X509Certificate b,WebRequest c,int d){return true;}}';[System.Net.ServicePointManager]::CertificatePolicy=New-Object TrustAllCertsPolicy;(Invoke-WebRequest -Uri '<Apm_EndPoint_Urls>/index.do').Content -split "`n" | Where-Object {$_ -match 'Applications Manager'}
and verify the output must contain the text "Applications Manager" as below screenshot:
4. If the output does NOT contain "Applications Manager", configured endpoint is incorrect or network/firewall is blocking communication.
- Ensure the correct endpoint is configured.
- Ensure the network and firewall configuration allows communication from this APM Insight .NET agent installed machine to the Application Manager
- If a proxy is used, specify the "Proxy Authentication" → Behind Proxy in the "Edit APM Insight .NET Agent Configuration" tool
5. After updating the settings, restart the application and the APM Insight .NET Agent service for the changes to take effect.
Prerequisites 3. Application user should have full permissions over the agent directory - C:\ProgramData\DotNetAgent & C:\ProgramData\DotNetCoreAgent
To verify the application user permission:
1. Open Task Manager → Details tab
2. Locate your target application process: w3wp.exe for IIS app, <service_name>.exe for services, or the main executable for desktop apps.
3. Note the "User name and Go to the above folder (C:\ProgramData\DotNetAgent & C:\ProgramData\DotNetCoreAgent) → Properties → Security.
4. Confirm the user/group (e.g., IIS_IUSRS, SYSTEM, or service account) has Read & Write permissions.
5. If missing permissions, click Edit → Add → [User Name] → Allow Read & Write permissions, then restart the application and check.
Prerequisites 4. Competitor agent of other tools like (E.g Dynatrace, AppDynamics, etc..) should be removed before installing our agent.
Follow this steps to identify and resolve conflicts between other APM products and the APM Insight .NET agent.
Prerequisites 5. SharePoint/Multi-Domain environment: Specific configuration changes required due to security concerns in these environments.
Follow this steps to identify the SharePoint/Multi-Domain environment and configure the "Support Multi-Domain Applications" checkbox
Misconfiguration Issues
Misconfiguration Issue 1. Incorrect "Apm Endpoint Urls" Configuration
"APM Endpoint Urls" configured with invalid Application Manager one's. i.e. Sometime port has configured with OpManager port instead of Applications Manager one's.
To ensure that:
1. From Application Manager server, Navigate to the Settings → Tools → Support → Installation Information, Can get the Web Server Port & SSL Port of the Applications Manager.
2. Ensure the same configured in the "Apm Endpoint Urls" from APM Insight .NET Agent Configuration tool
3. Open the same URL in a browser on the agent-installed machine and confirm it loads.
4. Run the below PowerShell command (as Administrator) using the same “Apm Endpoint Url”
add-type 'using System.Net;using System.Security.Cryptography.X509Certificates;public class TrustAllCertsPolicy : ICertificatePolicy {public bool CheckValidationResult(ServicePoint a,X509Certificate b,WebRequest c,int d){return true;}}';[System.Net.ServicePointManager]::CertificatePolicy=New-Object TrustAllCertsPolicy;(Invoke-WebRequest -Uri '<Apm_EndPoint_Urls>/index.do').Content -split "`n" | Where-Object {$_ -match 'Applications Manager'}
and verify the output must contain the text "Applications Manager" as below screenshot:
5. If the output does NOT contain "Applications Manager", configured endpoint is incorrect or network/firewall is blocking communication.
- Ensure the correct endpoint is configured.
- Ensure the network and firewall configuration allows communication from this APM Insight .NET agent installed machine to the Application Manager
- If a proxy is used, specify the "Proxy Authentication" → Behind Proxy in the "Edit APM Insight .NET Agent Configuration" tool
6. After updating the settings, restart the application and the APM Insight .NET Agent service for the changes to take effect.
Misconfiguration Issue 2. Incorrect "License Key" Configuration
Configured "License Key" on "Edit APM Insight .NET Agent Configuration" tool might not match with the Configured "Apm Endpoint Urls" - Applications Manager. i.e. Sometimes user configure the different Applications Manager license instead of the configured Configured "Apm Endpoint Urls" - Applications Manager one's
To ensure that:
1. Login into the Configured "Apm Endpoint Urls" - Applications Manager one's, Navigate to the APM → Add Monitor → .NET - Configure Now →APM Insight License Key, copy the license key and replace it in the "License Key" value on "Edit APM Insight .NET Agent Configuration" tool
2. Then, restart the agent service and application to reflect the changes.
Application not enabled/No Active Traffic
After agent installation, application might not enabled or not restarted or not having active traffic to initiate the monitoring.
To check and ensure that:
1. Ensure your application (IIS app, Windows service, desktop app) is enabled for monitoring within the "APM Insight .NET Agent Configuration" tool and your application is running & processing transactions or requests for the agent to monitor it.
2. Verify if the application process(IIS app, Windows service app, Desktop app) instrumented with agent profiler using Process Explorer:
- Download and unzip Process Explorer. Run the "procexp.exe" in administrator mode
- Locate the target application process (w3wp.exe for IIS app, <service_name>.exe for services, or the main executable for desktop apps).
- In the Process Properties (Right Click -> Properties), go to the Environment tab, and Confirm the presence of the COR_PROFILER & CORECLR_PROFILER variable with the value of `989D151B-3F31-482E-926F-2E95D274BD36` & `9D363A5F-ED5F-4AAC-B456-75AFFA6AA0C8`
3. Verify if the application process(IIS app, Windows service app, Desktop app) instrumented with agent profiler using Event Viewer:
- Open Event Viewer and navigate to Windows Logs > Application.
- Check for the event with the source .NET Runtime and verify that the `Process ID(decimal)` matches the one in Task Manager.
4. Verify if the agent created following log files under this path - "C:\ProgramData\DotNetAgent\AgentLogs" or "C:\ProgramData\DotNetCoreAgent\AgentLogs"
- For IIS app , ".NetAgentNative.w3wp.exe.<PID>.log" , "DotNetAgentManaged.ROOT.w3wp.<PID>-<dd-mm-yyyy>.log"
- For Windows service & Desktop app, ".NetAgentNative.<service_name>.exe.17348.log" , "DotNetAgentManaged.<service_name>.exe.<service_name>.<PID>-<dd-mm-yyyy>.log"
Note: This log file will be created only if the application having or performed with some transaction
License Expired
"APM Insight .Net Add-On" license might got expired or addon licensed not enabled on the Applications Manager.
To verify:
1. Open the "APM Insight .NET Agent Health monitor" tool
2. Navigate to the "IIS Applications" tab for IIS sites OR "Windows Service and Apps" for Windows Service & Desktop apps
3. Check the app monitoring status appears as "LicenseExpired" state.
To establish the Application monitoring:
1. Apply & Ensure the "APM Insight .Net Add-On" licensing enabled to allow .NET app monitoring on the Applications Manager.
2. From the "APM Insight .NET Agent Health monitor" tool, Click "Fix it" → Yes
Still Issues persists?
If still encounter with app onboarding failure, contact appmanager-support@manageengine.com (for existing customers) or eval-itom@manageengine.com (for trial users) along with updated Agent diagnostics for further assistance
New to ADSelfService Plus?
Related Articles
APMInsight - .NET Agent Data Collection - KB
Overview 📌 Note: For any onboarding or agent installation-related issues, please refer to the APM Insight .NET Agent Onboarding KB. This document provides a step-by-step guide to troubleshoot the data collection issue with the APM Insight .NET ...How to Install .NET agent on AWS Elastic Beanstalk?
One of the two options listed below can be used to install APM Insight agent onto a .NET web application hosted in Elastic Beanstalk environment via ebextensions. Deployment through AWS kit for Visual Studio. Deployment via uploading packages to AWS ...Troubleshoot - Duplicate APMInsight Monitors
Introduction: Duplicate monitors might be created in APMInsight due to various reasons. This article will help you identify and resolve the issue of duplicate monitors. The common causes include: - Changes in monitor configuration. (apminsight.conf ...How to install .NET agent on Azure app services?
You can track the performance of your .NET and .NET Core web app's key metrics like response time, throughput, and Apdex score via the APM Insight .NET agent hosted in Azure App Services. Installing APM Insight extension via Azure portal 1. Log in to ...How to add an APM Insight Node.js agent in Kubernetes via InitContainers?
To integrate the APM Insight Node.js agent into your Kubernetes applications using InitContainers, follow the steps given below: Step 1: Create an empty volume that will be used to copy the agent files during the initContainers process. Example: ...