How to troubleshoot vFunction Agent not loading on .NET Applications running in a Windows environment
Overview of the Issue
This article is meant to help when the vFunction Agent is not loading in a .NET Application running in a Windows environment. The most common points of failure are:
- A permissions issue where the .NET Application is run by a user that cannot access the location where the vFunction Agent files are stored
- An issue with the Environment Variables added into the .NET Application, such as a typo or a mismatch between the Framework / Core Environment Variables used and the type of .NET Application
- An issue with the Folder Path to the vFunction Agent where Windows treats the single-backslash as an escape character
- A .NET Agent issue where another Agent is hooked into the .NET Application instead of vFunction and this third-party Agent needs to be disabled in order for the vFunction Agent to be added
Check %TEMP% Location for Logging
The vFunction Agent attempts to create a new file named vfagent.net.log to capture Standard Output and Standard Error in the instance-specific vFunction logging directory. For example, this may be in C:\home\vfunction\log\instances\default-dotnet\vfagent.net.log.
If an issue arises that prevents the Application from writing to this directory, the vFunction Agent will write the log file to the %TEMP% directory. Open Windows Explorer and input the string %TEMP% into the Search Bar to navigate to this location and search for this file. Note that this workflow is accessible the Environment Variable %TEMP% for the user that runs the Application. This may be a separate user from the one initiating the RDP Session.
The %TEMP%\vfagent.net.log may contain errors about accessing the vFunction Agent DLL that need to be corrected. Or, the log may show that the installation.yaml’s agent.application_name field needs to be adjusted to hook into the relevant .NET Process.
Add both the Framework and Core Environment Variables
In the same location where the original vFunction Environment Variables were added, e.g. the applicationHost.config or Registry, modify the Environment Variables list to add both the Framework and Core Environment Variables. Also confirm the values (such as the Profiler UUID and the BASE_DIR path) are accurate:
VF_AGENT_CONF_LOCATION='$BASE_DIR\vfunction\config\agent\instances\default-dotnet\conf.json'
COR_PROFILER_PATH_64 = '$BASE_DIR\vfunction\agent\vfagent.net.dll'
CORECLR_PROFILER_PATH_64 = '$BASE_DIR\vfunction\agent\vfagent.net.dll'
COR_PROFILER_PATH_32 = '$BASE_DIR\vfunction\agent\vfagent.net.x86.dll'
CORECLR_PROFILER_PATH_32 = '$BASE_DIR\vfunction\agent\vfagent.net.x86.dll'
COR_ENABLE_PROFILING = '1'
CORECLR_ENABLE_PROFILING = '1'
COR_PROFILER = '{cd7d4b53-96c8-4552-9c11-6e41df8eab8a}'
CORECLR_PROFILER = '{cd7d4b53-96c8-4552-9c11-6e41df8eab8a}'
COMPlus_TailCallOpt = 0
DOTNET_TailCallOpt = 0
Use Double-Backslashes for the Agent’s Folder Path in the Environment Variables
In some cases, Windows may treat the single backslash as an escape character in the File Path of the .NET Application’s Environment Variables. Try using double-backslashes for the Folder Path. For example, for a Framework .NET App:
VF_AGENT_CONF_LOCATION='$BASE_DIR\\vfunction\\config\\agent\\instances\\default-dotnet\conf.json'
COR_PROFILER_PATH_64 = '$BASE_DIR\\vfunction\\agent\\vfagent.net.dll'
COR_PROFILER_PATH_32 = '$BASE_DIR\\vfunction\\agent\\vfagent.net.x86.dll'
COR_ENABLE_PROFILING = '1'
COR_PROFILER = '{cd7d4b53-96c8-4552-9c11-6e41df8eab8a}'
COMPlus_TailCallOpt = 0
Gather Errors About Loading the vFunction Agent
Worker Processes and vFunction Agent Logging
The vFunction Agent will begin logging once the .NET Application begins to receive input. For IIS .NET Applications, the .NET Process will shutdown if no traffic is received and will not start until traffic is received. In the IIS Manager, confirm that a Worker Process is running by hitting an endpoint for the IIS Application Pool. At this point in time, the vfagent.log should be written.
Microsoft SysInternal’s DebugView
Take the following steps to run DebugView to get better insight into what is happening with the Application:
- On the Windows machine where the Application is running, download DebugView and unpack this Microsoft tool
- Right-click on dbgview64.exe and select Run as Administrator
- Select Capture from the Menu Bar
- Check the dropdown options to Capture Win32, Capture Global Win32, Pass-Through, and Capture Events
- Restart the Application. For example if an IIS Application, recycle the Application Pool, use an API and ensure there’s a new w3wp.exe Process ID.
- The Windows Error code may provide next steps about the source of the issue in order to resolve the problem, such as the wrong path to the vFunction Agent DLL or permissions issues or that another Agent is hooked into the Application which will need to be disabled.
- If there are no errors in the DebugView output, this is a good indicator that no errors are occurring
Microsoft Process Explorer
- On the Windows machine where the Application is running, download Process Explorer and unpack this Microsoft tool
- Launch Process Explorer and find the running .NET Process
- Navigate to the Environment tab
- Confirm that the vFunction Environment Variables are listed as expected in the running process. If, for example, the COR_PROFILER_PATH points to another or the COR_PROFILER is not the vFunction Agent’s UUID, investigate further why the third-party Agent is overriding the vFunction Environment Variables. The screenshot below shows, for example, a functional IIS-based .NET Framework Application with the vFunction Agent hooked
Microsoft Process Monitor
- On the Windows machine where the Application is running, download Process Monitor and unpack this Microsoft tool
- Launch Process Monitor and find the running .NET Process
- Use the Filter to focus on activities only from the relevant .NET Process
- Confirm that the vFunction Agent DLL(s) are accessed by the running .NET Process. The screenshot below shows, for example, a functional IIS-based .NET Framework Application with the vFunction Agent hooked
