Your data. Anywhere you go.

New Relic for iOS or Android


Download on the App Store    Android App on Google play


New Relic Insights App for iOS


Download on the App Store


Learn more

Close icon

Relic Solution: .NET Framework Agent Installation Issues - A Troubleshooting Guide


#1

Before you begin, issue an iisreset (or restart your application, if it is a non-IIS app), then check your system for current agent log files. In a standard installation they should be located in C:\ProgramData\New Relic\.NET Agent\Logs. If you see current log files being generated after your application restart, then the agent is already installed correctly and you head over to <Troubleshooting With .NET Agent Log Files> to start digging in to the logs themselves. If you do not see current logs being generated, follow the directions below.

The point of this post is to provide troubleshooting steps for common installation issues with the .NET Framework agent in Windows environments. It is intended to make sure the agent is correctly configured to profile .NET Framework applications on your system. At the end of this post you should see a logs folder with logs in it inside the directory at C:\ProgramData\New Relic\.NET Agent\Logs, and new log files should be generated when you restart your application. The presence of these logs indicates that the agent is correctly installed on your system. There may be additional configuration required to get data reporting to your New Relic account, but that configuration is outside the scope of this post.

There are five main areas of consideration when diagnosing installation issues in the .NET Framework agent:

  1. Is the application supported by the .NET Framework agent?
  2. Choosing the correct version of the Framework agent for your needs.
  3. Installing the correct agent features.
  4. Are the required environment variables and assemblies loaded into the process?
  5. Does the application have the correct permissions to access the agent folders and/or registry keys?

Is the application supported by the .NET Framework agent?

Please ensure that your application and environment meet the compatibility requirements for monitoring by the .NET Framework agent.

Choosing the correct version of the Framework agent for your needs.

Whichever version of the agent you need, make sure you download the correct “bitness” for your host (x64 = 64-bit host, x86 = 32 bit host).

  • If you are installing the agent on Windows Server 2003, the most recent version of the agent you’ll be able to use is version 6.11

  • If you need to monitor applications which target .NET Framework versions lower than 4.5, you will need to use the latest 6.x version of the agent (Agent versions 7.0 and above only support .NET Framework 4.5 or higher).

  • If you’re only monitoring .NET applications that target Framework versions 4.5 or higher and are using Windows Server 2008 or higher, use the latest release of the agent.

Official documentation on installing the .NET Framework agent can be found at this link.

Installing the correct agent features.

  • If you’re only monitoring IIS-hosted web applications and will not be making in-code calls to the .NET Agent API, you can use the default installer options and just “click through”.

  • If you need to monitor non-IIS .NET applications (such as service/console apps), make sure to enable the Instrument All .NET Applications option on the installer’s Custom Setup screen.

  • If you’ll be making in-code calls to the .NET Agent API, enable the API Assembly option on the installer’s Custom Setup screen.

If the installer does not prompt you to enter your license key, it means that the .NET Framework agent has been previously installed on this host. After the installation is complete, check the newrelic.config file located in C:\ProgramData\New Relic\.NET Agent and ensure that it contains the correct license key for your account.

Are the required environment variables and assemblies loaded into the process?

The environment variables are automatically created by the agent installer. There should be no need to manually adjust them. We just want to make sure they are present in the application process and that no other profiler applications are over-writing them.

There are three environment variables that must be loaded into your application process at startup in order for the .NET Framework agent to successfully profile/monitor your application. For the vast majority of .NET Framework installation, the variables and their associated values will be:

COR_ENABLE_PROFILING = 1
COR_PROFILER = {71DA0A04-7777-4EC6-9643-7D28B46A8A41}
NEWRELIC_INSTALL_PATH = C:\Program Files\New Relic\.NET Agent

COR_ENABLE_PROFILING - The value of this variable must be set to 1. If it is set to 0 the .NET Agent will not be able to monitor your application.

COR_PROFILER - There are two possible valid values for this variable:

  • {71DA0A04-7777-4EC6-9643-7D28B46A8A41} - This is the correct value if you are using agent version 2.9 or newer (the vast majority of installations).

  • {FF68FEB9-E58A-4B75-A2B8-90CE7D915A26} - This is the correct value if you are using agent version 2.8 or older (very uncommon).

NEWRELIC_INSTALL_PATH - This should be set to the installation path of the agent. In a standard installation, that value is C:\Program Files\New Relic\.NET Agent.

Verifying that the correct variables are loaded into your application process

To check your application process and ensure that the correct variables are being loaded, use a process inspection tool, such as Microsoft Process Explorer. Instructions on using Process Explorer to inspect your application process can be found in this forum post.

While you’re there, be sure to check your process for the presence of the required assemblies, NewRelicProfiler.dll and mscorlib.dll, as described in the final section of that post.

Does the application have the correct permissions to access the agent folders and/or registry keys?

When I talk about user permissions in this section, I’m referring to the permissions of the user account that the application process is running under, not the user account that you’re logged into Windows as.

Now that you’ve inspected your application process, it’s very likely that your situation falls into one of the following four scenarios.

  • The required environment variables are not present in the application’s process.
  • The environment variables are present in the application process, but their values are wrong.
  • The environment variables are present and their values are correct, but the required .dlls are not present in the process.
  • Everything looks fine in Process Explorer (variables are set with the correct values and the required assemblies are present), but log files are still not being generated when the application is restarted (iisreset).

The required environment variables are not present in the application’s process.

  • IIS applications - make sure that the application process has the correct permissions to access the registry keys created by the.NET agent. This documentation should help.

  • Non-IIS applications - Double-check that you selected the Instrument All .NET Applications option when you installed the agent. If you did, the environment variables will be present as system-wide environment variables on your host machine. Check the system environment variables for the correct variables and values. If they aren’t present, you can re-run the installer and select the appropriate install feature, or you can add them manually if you want.

The environment variables are present in the application process, but their values are wrong.

This is a telltale sign that you have a profiler conflict on your system. You’ll need to uninstall any other .NET profilers currently present on your host machine. The .NET Framework only allows one profiler to attach to any given process.

The environment variables are present and their values are correct, but the required .dlls are not present in the process.

  • mscorlib.dll is missing - mscorlib.dll is required to be present. It’s presence is how the .NET Framework agent identifies your application as a .NET app. If it is missing, please double-check to make sure your application meets the compatibility requirements for monitoring by the .NET Framework agent.
    If you don’t see mscorlib.dll, but you do see mscorlib.ni.dll, then check to see if you’re using a native image module (such as NGEN). The .NET agent can not monitor applications that use a native image mscorlib.ni.dll assembly.

  • NewRelicProfiler.dll is missing - Ensure that the application process has read permissions to the agent folder and its contents. This is usually C:\Program Files\New Relic\.NET Agent.

Everything looks fine in Process Explorer, but log files are still not being generated when the application is restarted.

This scenario is rare, but when it does happen it usually comes down to the application process not having the correct permissions to read and write to the agent’s logs folder (C:\ProgramData\New Relic\.NET Agent\Logs). Please make sure that the process can read from and write to that path.

What now?

If you’ve followed along and corrected some issues you should now be able to restart your application (or issue an iisreset) and see current logs being generated in the logs folder.

If you have logs, but still no data in the UI, head over to <Troubleshooting With .NET Agent Log Files> to start digging in to the logs themselves.

If you don’t see logs being generated, feel free to create a new post and let us know what you’ve tried so far and where you got stuck. We’ll do our best to help you get it up and running.

Hope this has helped!

Don


Relic Solution: Monitoring Non-IIS applications with the .NET Framework Agent
Relic Solution: Troubleshooting With .NET Agent Log Files
Relic Solution: Monitoring an ASP.NET CORE application targeting the .NET Framework
No data from non-IIS application
Newrelic agent error