.NET Agent troubleshooting

This page explains how the Microsoft .NET CLR loads the AppMon .NET Agent and lists problems which may occur at each step, and suggests solutions them. It also contains info about special IIS behavior. For information about the Agent configuration causing high runtime overhead, see Agent Group - Agent Mapping > Advanced Settings.

.NET CLR load

The CLR checks whether COR_ENABLE_PROFILING is set to 0x1. If yes, it does a lookup into the registry:

  • x64 CLR on x64 OS or x86 CLR on x86 OS
  • x86 CLR on x64 OS

The CLR tries to load the DLL under the sub-key \InprocServer32.

The dtagent.dll tries to determine whether the process that it is loaded into should be instrumented. It first checks the optional environment variables. If they are not set, then it checks the whitelist (created and managed by the .NET Agent Configuration tool) in the registry:

  • x86 (32-bit)
  • x64 (64-bit)

The bootstrap agent goes through the whitelist entries, compares the executable name and path for equality, and checks the command-line parameters if they contain the related whitelist setting.

If no configuration or an inactive configuration is found for that process (no whitelist entry or no DT_ environment variables), no instrumentation is done.

If a configuration is found, the Agent tries to connect to the given Collector (Server setting) and creates a new dt_<agentname> bootstrap <pid>.log file in the <DT_HOME>\log folder. If connection problems occur, the Agent tries to connect for 60 seconds (default timeout setting) and blocks the process from executing. When the Agent times out, no instrumentation is done (the same as when no configuration for this process exists).

If the agent is successfully connected to the Collector, it checks whether a newer Agent version is available and tries to download it.

The main Agent is loaded (a new log dt_<agentname>_<pid>.log is created) and tries to instrument the application according to the settings. The assemblies are sent to the Collector, instrumented, and sent back to the Agent, where the code is executed.

Special behavior of IIS worker processes

IIS may sometimes start a worker process, but not load or only partly load the CLR with the web application if there are no requests on the web server or only requests to static resources. If you see that a monitored w3wp.exe instance is loaded but no Agent is connected, no bootstrap log is written (even if dtagent.dll is loaded inside), and the memory usage of the w3wp.exe process is quite low compared to other started worker processes), then it is most likely the case that you need to give some load to the web server that needs the web application being loaded.

For IIS 7 and later, by default the user ApplicationPoolIdentity is set to be used for the application pool worker processes. This causes the worker process (including the Agent) to run under restricted permissions that might not contain the rights to fetch the Windows performance monitor measures for the process health of its own CLR. This results in not seeing all process health metrics (for example, garbage collection values), and seeing messages in the Agent log like the following:

warning [native] Unable to get Performance Counter Value

The resolution is to add the user ApplicationPoolIdentity to the local application server user group called Performance Monitor Users. Because the GUI to add users to this group may also be restricted, use command prompt:

net localgroup "Performance Monitor Users" /add "IIS APPPOOL\<AppPool Name>"

To use AppMon User Experience Management (UEM) for .NET applications, you must use the Web Server Agent for IIS. There is no option that would allow you to use UEM without a Web Server Agent.