.NET Agent configuration

Use the .NET Agent Configuration tool to create or edit .NET Agent configurations and to enable/disable the Agent.

.NET Agent configuration tool

Note

The .NET Agent Configuration tool can cause small CPU spikes every ten seconds when open.

You can start the .NET Agent Configuration tool by selecting All Programs > Dynatrace > Agent Configuration Tool for .NET in the Start menu, or by double-clicking the executable dtagentconf.exe in the <DTHOME> directory.

Main window
Main window

The .NET Agent Configuration tool main window has two parts. The upper part shows a list of Agent configurations. They define in which .NET process an Agent should be placed. The Application Type column displays the type of .NET process. ASP.NET Worker Processes are highlighted to distinguish them from other .NET processes.

The first time the .NET Agent Configuration tool starts, this list is empty because no agent configurations have been defined yet. See Creating a .NET Agent Configuration (below) for details on how to create an Agent configuration.

The bottom part of the window lists all currently running .NET processes that the active Agent configurations in the upper list. This list is updated automatically every 20 seconds and when an Agent configuration is activated/deactivated by clicking the check box next to it. You can manually refresh the processes list by clicking the refresh button.

Status messages

Status message Agent Loaded/Unloaded Successfully? Environment Set Correctly? Comments / Possible Solutions
The following should be loaded:
  • dtagent.dll (Bootstrap agent)
  • dtagentcore.dll (.NET agent)
The following variables should be set:
  • COR_ENABLE_PROFILING
  • COR_PROFILER
Enable profiling:
.NET agent successfully loaded. Check (Bootstrap agent loaded)
Check (.NET agent loaded)
Check (active) Everything works as expected.
Agent is not activated (environment variables COR_PROFILER and COR_ENABLE_PROFILING are not set). Press Active to set environment variables. Process restart or system reboot is required. Warning (Bootstrap agent not loaded)
Warning (.NET agent not loaded)
Warning (inactive)
  • Environment variables (COR_ENABLE_PROFILING and COR_PROFILER) are not active.
  • Click Active to set the environment variables. A reboot is necessary.
Bootstrap agent (dtagent.dll) is not loaded, but has been activated. Process restart or system reboot is required. Warning (Bootstrap agent not loaded)
Warning (.NET agent not loaded)
Check (active)
  • The dtagent.dll is only loaded after a restart of the process.
  • In some cases, the Agent Configuration Tool cannot detect dtagent.dll or dtagentcore.dll although it was loaded successfully. Use Process Explorer to check whether your processs loads dtagent.dll or dtagentcore.dll.
Bootstrap agent (dtagent.dll) is loaded, but .NET agent (dtagentcore.dll) is not. Process restart or system reboot is required. Make sure that bootstrap agent can connect to collector and the environment variables COR_PROFILER_PATH and DT_AGENTACTIVE are not set. Check (Bootstrap agent loaded)
Warning (.NET agent unloaded)
Check (active)
  • If an already running process has just been configured, a process restart is necessary.
  • Make sure the agent can connect to the Collector. Review the Bootstrap Agent log for more information.
  • Check whether the environment variables COR_PROFILER_PATH and DT_AGENTACTIVE are set, and unset them. A process restart or system reboot is necessary.
  • Make sure the process receives web requests. If it does not, CLR and the core agent are not loaded in the process.
Agent did not connect or did not find matching system profile. Make sure that agent can connect to collector, and that agent settings system profile name are valid. Check (Bootstrap agent loaded)
Check (.NET agent loaded)
Check (active)
  • No instrumentation was applied in that process.
  • Make sure the Agent can connect to the Collector. Review the Bootstrap Agent log for more information.
  • If the Agent was able to connect, you can check its status in the Agent Overview.
  • Make sure the agent matches with a System Profile. If it does not, adapt the Agent mapping and restart the process.
Disable profiling:
Profiling disabled. Check (Bootstrap agent unloaded)
Check (.NET agent unloaded)
Check (inactive) Everything works as expected.
Bootstrap agent (dtagent.dll) is still loaded, but has been deactivated. Process restart or system reboot is required. Warning (Bootstrap agent loaded) Check (inactive)
  • Although you have chosen to stop profiling, the Agent is still loaded in the process and the environment is set for profiling.
  • Restarting the process or rebooting the machine should resolve the issue.
.NET agent (dtagentcore.dll) is still loaded, but has been deactivated. Process restart or system reboot is required. Warning (Bootstrap agent loaded)
Warning (.NET agent loaded)
Check (inactive)
  • Although you have chosen to stop profiling, the Agent is still loaded in the process and the environment is set for profiling.
  • Restarting the process or rebooting the machine should help.

The following table lists possible resolutions for special cases.

Special Case Comments / possible solutions
Status of 64-bit processes can only be determined for Vista / Server 2008 and later. On x64 systems earlier than Windows Vista or Server 2008, modules of 64-bit processes cannot be enumerated. Therefore it is impossible to check whether the Agent (dtagent.dll) was loaded into a 64-bit process.
No status information available. No status could be determined for the process.

Check the agent status manually:
  • Open the Agent Overview in the AppMon Client and check whether the Agent is connected.
  • Use Process Explorer to check whether the environment is set correctly and dtagent.dll is loaded for the process.
Restart of IIS Services pending. For Restart, click Button 'Restart IIS-Services'. A restart of the IIS services is pending if you activated or deactivated the .NET Agent but clicked No in the confirmation prompt asking if the IIS services should be restarted by the Agent Configuration Tool). In this case, a button is displayed in the main window to allow restart of these services at a more suitable time (for example, at night).

Creating a .NET Agent configuration

Select Agent Configuration > New from the menu, or click the Add button to display the Create .NET Agent Configuration wizard and create a new .NET Agent configuration.

Select a process for .NET Agent configuration
Select a process for .NET Agent configuration

On the Select Process screen, all running processes that host the .NET runtime are shown by default. Select Include non-.NET Processes to show all currently running processes. If the desired process is not currently running, you can locate the executable by selecting Browse file system, clicking the browse button to the right of the text box, and navigating to the executable.

Note

In some environments, especially 64-bit environments, the list of .NET processes may not show all running .NET processes. In this case, use the Include non-.NET Processes option.

If an IIS worker process is not listed, set up a web request to the site. This starts the worker process for the application pool that hosts the site.

Select a process from the list and click Next to display the Edit .NET Agent Settings dialog box.

Adjust the settings of the Agent Configuration
Adjust the settings of the Agent Configuration

Use this page to set details of the Agent configuration. The Agent name and the host name or address for the AppMon Server or Collector are required. All other settings are optional.

The following table describes the settings.

Setting Description
Agent name This mandatory setting assigns a descriptive name to the Agent. The name should reflect the tier or application that is observed by this Agent. The Agent name must be unique among deployed Agents. It must not contain spaces, tabs, commas, or other special characters.
Process name This setting shows the name of the executable for the .NET process. It cannot be edited.
Command line If a command line is provided, the Agent only handles processes that match the executable and path and also contain the value specified in the command line. The check is case-insensitive (for example, WebService is the same as webservice ). If this field is blank, the process is handled regardless of the actual command-line arguments.
Path This setting specifies the location of the executable. You can use the list to select the path to either a specific executable or all executable files with the executable name.
Address
Port
Use these settings to configure the host and port for connection to the standalone or embedded Collector. In earlier AppMon releases, this setting applies to the AppMon Server. In the current release, an Agent must always connect to a Collector. The Address value can be a fully qualified host name or an IP Address. The default Address and Port values are set to localhost:9998.
Log file Specify the path and file name for writing the log files. If omitted, the file name defaults to <agentname>.log in the agent log directory.
Note The executable process must have the privilege to write into the specified log folder. This might be problematic for some processes, such as the ASP.NET worker process, which is started by default with restricted privileges. If the process is not allowed to access the specified log folder, no logs are generated.
File log level Specify the overall log level. The level can be one of the following: finest | finer | fine | config | info | warning | severe | off.
Console log level Specifies the log level for writing to the console. Setting this option to off suppresses all log output to the console while still writing to the log file. The level can be one of the following: finest | finer | fine | config | info | warning | severe | off.

Click Finish to create the Agent configuration with the current settings and return to the .NET Agent Configuration window. This new Agent configuration is now shown in the upper list and is activated by default. All currently running processes matching this Agent configuration automatically appear in the bottom list. After these applications are restarted, they are ready to connect to the AppMon Server.

Note

To place the Agent in an IIS worker process (w3wp.exe) after activating the Agent, restarting IIS is not enough because this does not restart svchost.exe, the parent process of w3wp.exe. You must restart all IIS services on activation or deactivation of the .NET Agent.

Choose Yes when prompted to restart the listed IIS services. Be aware that restarting affects all connected processes.

You can restart at a convenient time by clicking the Restart IIS-Services button that appears in the center of the main window if an IIS service restart is pending.

If restarting the IIS services does not resolve all issues, a system reboot is recommended.

If the Agent could not be placed in a process, a hint for solving the problem is shown in the Status column for the process.

Note

Certain Windows API calls are used to determine if the Agent was successfully injected. For 64-bit processes, these calls are available only in Windows Vista, Windows Server 2008, and later Windows versions. In earlier 64-bit environments, incorrect hint texts may appear in the processes list. In this case, these hints can be ignored.

Editing existing Agent configurations

To edit an existing Agent configuration, select the Agent in the upper list and click the Edit button, or simply double-click the Agent's row. The same wizard as described in Creating a .NET Agent Configuration is shown, but it displays the second page with the current settings. Click the Finish button saves your changes.

Delete one or more selected Agent configurations by clicking the Delete button or by pressing the Delete key. You can copy and paste an existing configuration, as in all Windows applications, then edit the new configuration to provide unique details. This is especially useful for creating several similar Agent configurations.

Enable/disable Agent Configurations

In the Agent Configuration list, the check box adjacent to the Agent Configuration name controls whether that Agent Configuration is enabled (checked) or disabled (unchecked) when the .NET Agent is active. Click the check box for an Agent Configuration to toggle it between enabled and disabled. Disabling an Agent Configuration does not delete it from the Agent Configuration list.

Other settings

Application pool handling for IIS 7.x and IIS 8.x

ASP.NET worker processes on IIS 7.x and IIS 8.x are handled differently from other .NET processes. IIS 7.x and IIS 8.x use application pools, which can host one or more ASP.NET web applications. An application pool is uniquely identified by its name. The name is passed to the ASP.NET worker process using the -ap command line option. To distinguish the different application pools, AppMon captures this part of the command line and creates a separate process entry. This facility allows easy configuration of the ASP.NET worker processes for each application pool.

Activate or Deactivate the .NET Agent

Click the Active button at the top right corner of the window to activate the .NET Agent and enable all checked Agent Configurations.

If the Agent is enabled successfully, the button changes to appear pressed.

Click the Inactive button at the top right corner of the window to deactivate the .NET Agent and disable all Agent Configurations.

Enable local profiling

When you don't have the required permissions to set system-wide environment variables, enable profiling in local files (for example, batch scripts) by setting the following environment variables.

@echo off
REM set environment variables necessary for loading the dynaTrace Agent
set COR_ENABLE_PROFILING=0x1
set COR_PROFILER={DA7CFC47-3E35-4C4E-B495-534F93B28683}
set DT_AGENTNAME=MyDotNetAgent

Environment variables

Most of the settings for the .NET Agent can be configured using environment variables. The values of the environment variables overwrite the values that you configured with the .NET Agent Configuration tool.

The following environment variables are recognized.

Environment variable Description
COR_ENABLE_PROFILING 0x1: Enable profiling for your .NET process.
COR_PROFILER Specify the AppMon .NET Agent DLL loaded by the .NET runtime.

Use the value {DA7CFC47-3E35-4C4E-B495-534F93B28683} to inject the .NET Agent.
DT_AGENTNAME Assign a descriptive name to your Agent. See the previous Agent Name setting.
DT_SERVER [hostport] Specify the AppMon Server host and port to connect to.
DT_SOCKTIMEOUT Specify the instrumentor channel send/receive (socket) timeout. The default is 120 seconds.
DT_AGENTACTIVE ["true"|"false"] Activate (true) or deactivate (false) the .NET Agent.
DT_LOGFILE [String] Override the log file path. Specify the full path where the Agent log file should be written to. The Agent inserts the PID before the last period ( . ) in the file name (registry key 'logfile').
DT_LOGLEVELCON [level] Override the log level for console logging (registry key 'loglevelcon').

Possible values for log levels are:
  • NONE / OFF
  • FINEST
  • FINER
  • FINE
  • INFO
  • WARNING
  • SEVERE
DT_LOGLEVELFILE [level] Override the log level for the log file (registry key 'loglevelfile').
DT_LOGFILESIZE [num] Sets the maximum size in bytes for a log file. Default is 10 MB (1010241024). Reaching the maximum triggers log file rotation (registry key 'logfilesize').
DT_MEASUREOVERHEADNATIVE ["true"|"false"] Enable overhead log functionality for the native Agent part (registry key 'measureoverheadnative').
DT_MEASUREOVERHEADNONNATIVE ["true"|"false"] Enable overhead log functionality for the managed Agent part (registry key 'measureoverheadnonnative').
DT_MEASUREOVERHEAD ["true"|"false"] Enable overhead log functionality (registry key 'measureoverhead').
DT_TRANSFORMATIONSAMPLES [num] Number of samples to take for determining slow transformation (modules) (registry key 'transformationsamples')
DT_TRANSFORMATIONMAXAVGWAIT [ms] The maximum average wait time in milliseconds for determining slow transformation (registry key 'transformationmaxavgwait').
DT_WAIT [num] This is the registry key 'wait'. It is the maximum time in seconds (default: 20; was 60 until 5.5) an Agent waits for a connection to an AppMon Collector1). If the connection cannot be established within this time-frame, the application continues uninstrumented.
Note 1The Collector is often referred to as Server (not only in configuration strings and files, but also in Client dialog boxes), because the Collector used to be integrated in the AppMon Server. You can still use the Server-embedded Collector when you test AppMon, but the standalone Collector is enforced (by the license) in real-world scenarios.
DT_HIRESTIMER [cpu|os|runtime|auto] Specify the timer the Agent should use (registry key 'hirestimer').
DT_DISABLEINITIALLOGGING ["true"|"false" (default)] Disable logging until the Agent gets valid settings (omit the startup banner for disabled Agents).
DT_TESTRUN_ID Identify the test to be run with a <testRunId> obtained from a REST call for test automation.
DT_USESSL Enables SSL encryption between the Agent and the Collector. Encrypted communication uses the same port as non-encrypted. To enable SSL you need to set this parameter as true before launching the Agent.

Upgrade

You do not have to upgrade certain Agents (7.0: Java, .NET, Web Server, PHP, Native ADK, z/OS, and Host Agent). A bootstrap part checks for the correct Agent library when your application starts.

See Upgrade and Migration Guide for information on upgrades and migration.

Command-line options

The .NET Agent Configuration tool provides the following command-line option that executes registration actions without launching the user interface. This option is helpful for automated scenarios.

Option Comment
/repairnative Re-registers the AppMon native Agent.

AppMon Agent usage

If you're using AppMon Agent, don't forget to configure ports for it.

This agent is available in both multiple agent platforms. Please check the release status of the agent before switching over as some agents are still in BETA.