Dynatrace 6.3 Documentation

Other Doc Versions & KB

Skip to end of metadata
Go to start of metadata

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

Agent Configuration Tool

Icon

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.

The main window of the .NET Agent Configuration tool is separated into two parts. The upper part shows a list of Agent configurations. They define in which .NET process a Dynatrace 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 checkbox 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.

(tick) (Bootstrap agent loaded)
(tick)  (.NET agent loaded)

(tick) (active)

Everything works as expected.

Agent is not activated (environment variables COR_PROFILER and COR_ENABLE_PROFILING are not set). Press 'Activate' button 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 the Active button 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)

(tick) (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 dtagent.dll or dtagentcore.dll is loaded by your process.

Bootstrap agent (dtagent.dll) is loaded, but .NET agent (dtagentcore.dll) is not. Process restart or system reboot is required. Please make sure that bootstrap agent can connect to collector and the environment variables COR_PROFILER_PATH and DT_AGENTACTIVE are NOT set.

(tick)   (Bootstrap agent loaded)  
(warning)   (.NET agent unloaded)

(tick)  (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. Please make sure that agent can connect to collector, and that agent settings system profile name is valid. (.NET agent version: 'v...', Bootstrap agent version: 'v...').

(tick)   (Bootstrap agent loaded)  
(tick)   (.NET agent loaded)

(tick)  (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, correct the Agent mapping and restart the process.

Disable profiling:

 

 

 

Profiling disabled.

(tick)   (Bootstrap agent unloaded)  
(tick)   (.NET agent unloaded)

(tick) (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)

(tick)  (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)

(tick)   (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 above.

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 Dynatrace 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

To create a new .NET Agent configuration:

Select Agent Configuration > New from the menu, or click the button to display the Create .NET Agent Configuration wizard.

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. 

Icon

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 screen.

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

The following table describes the settings.

SettingDescription

Agent Name

This mandatory setting assigns a descriptive name to the Dynatrace Agent. The name should reflect the tier or application that is observed by this Dynatrace Agent. The Agent name must be unique among deployed Dynatrace 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 Dynatrace 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 will be 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 Dynatrace releases, this setting applies to the Dynatrace 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.

Icon

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 will be 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 Dynatrace Agent configuration automatically appear in the bottom list. After these applications are restarted, they are ready to connect to the Dynatrace Server.

Icon

To place the Dynatrace Agent in an IIS worker process (w3wp.exe) after activating the Dynatrace 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.

Icon

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 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 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.

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 via the -ap command line option. To distinguish the different application pools, Dynatrace 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.

Enable or Disable the .NET Agent

Click the Active button at the top right corner of the window to activate the .NET Agent.

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

To deactivate the .NET Agent, click the Inactive button.

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.

Environment Variables

Most of the settings for the .NET Agent can be configured via 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 VariableDescription

COR_ENABLE_PROFILING

0x1: Enable profiling for your .NET process.

COR_PROFILER

Specify the Dynatrace .NET Agent DLL that will be 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 Dynatrace Agent. For details, see the Agent Name setting above.

DT_SERVER

[hostport] Specify the Dynatrace 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 will insert 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 (10*1024*1024). Reaching the maximum will trigger 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] Since 3.5 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 a Dynatrace Collector1). If the connection cannot be established within this time-frame, the application continues uninstrumented.

Icon

 1) The Collector is  often referred to as "Server" (not only in configuration strings and files, but also in Client dialogs), because the Collector used to be integrated in the Dynatrace Server. You can still use the Server-embedded Collector when you test Dynatrace, 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_IDIdentify the test to be run with a <testRunId> obtained from a REST call for test automation.

Upgrade 

For Dynatrace 4.1 and later, you do not have to upgrade certain Agents (6.3: Java, .NET, Web Server, PHP, Native ADK, z/OS, and Host Agent). A bootstrap part checks for the correct Dynatrace Agent library when your application starts. For more information on the Bootstrap Agent, see dynaTrace 4.1 Release Notes > Bootstrap Agents.

For information on upgrades and migration, see Upgrade and Migration Guide.

Configuration Changes on Install or Uninstall Concerning .NET Agent Activation and Registration

The .NET Agent GUID {DA7CFC47-3E35-4c4e-B495-534F93B28683} has not changed since version 4.1. 

The following table indicates how installing and uninstalling Dynatrace affects the .NET Agent registration and activation. See notes (1) and (2) below for further details.

If .Net Activation (1) check box is marked in the installer:

 

Install

Uninstall

Uninstall

Installer Version

.NET registration (2)
GUID overwritten?

.NET De-activation

.NET Un-registration

5.0, 5.5, 5.6

Yes

No

Yes, if wasn't overwritten by another installer

4.1, 4.2

Yes

Yes

Yes, if wasn't overwritten by another installer

4.0

No

Yes

Yes

(1) .NET activation means setting environment variables COR_ENABLE_PROFILING=0x01 and COR_PROFILER=<.NET Agent GUID>.
(2) .NET registration means adding the Agent path in the registry, as shown below for the 64-bit and 32-bit operating systems.

64-bit Windows:

32-bit Windows:

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 Dynatrace Native Agent.

Troubleshooting

This section explains how the Microsoft .NET CLR loads the Dynatrace .NET Agent, and suggests solutions for problems that might occur.

Step & Possible Problems

Solution

Step

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

Possible Problems

  • No registry key exists.
  • The user under which the process is running does not have registry read access rights.
  • The profiler GUID is wrong.

 

  • Reinstall the Dynatrace Agent with the installer, or use the following to register the DLL in a command prompt with administrator rights:


  • Give the user read permissions to that registry key, subkeys, and values (possible with regedit executed with administrator rights).
  • Check that a correct Dynatrace .NET Agent GUID is used for COR_PROFILER (see KB-256).
  • For instrumenting IIS application pools, you normally need to run iisreset from a command prompt as administrator to get the COR_* environment variables passed to the worker processes, because restarting or recycling the application pool is not sufficient. But this is sometimes not enough to get all current environment variable changes into the worker process (for example, removal of DT_AGENTACTIVE), because these are inherited from the parent process (for IIS application pool worker processes, the parent process is svchost.exe). Killing the parent process might work, but the only safe way is a server restart.
    You can verify which environment variables are currently seen by a process/CLR by using Sysinternals Process Explorer (right-click the process and select Properties, then select the Environment tab).

Step

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

Possible Problems

  • The user under which the process is running has no file system permission to read and execute the referenced dtagent.dll.
  • The bitness (32-bit or 64-bit) of the referenced dtagent.dll does not match with the bitness of the process or CLR.


  • Give the user read and execute rights in the file system to the referenced dtagent.dll.
  • Check that the correct bitness versions are referenced in the registry keys mentioned above
    (for both cases, see KB-420).

Step

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)

Possible Problems

  • The user under which the process is running does not have registry read access rights.
  • The whitelist is ignored because of the presence of the DT_AGENTACTIVE environment variable.

 

  • Give the user read permissions to that registry key, subkeys, and values.
  • If this cannot be accomplished (because of security guidelines, for example), a workaround is to use of the optional Dynatrace environment variables (including Microsoft COR_ENABLE_PROFILING and COR_PROFILER variables) with the possibility to set them only for the user, the process, or the IIS worker processes.
  • If DT_AGENTACTIVE is set to TRUE, all whitelist settings are ignored and all .NET processes are instrumented just by using the DT_SERVER and DT_AGENTNAME environment variables. If these variables are not set, the default values are used (localhost:9998 and the process name).

Step

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.

Possible Problems

No active configuration can be found for a configured process, so no Bootstrap Agent log is created.


  • Remove any inactive configuration entries that match this process (no parameter, same parameter), because the Agent quits checking after the first matching entry and the order in which the entries are checked (how Windows enumerates them) is random.
  • Check whether the executable path setting equals the whitelist entry. For example, when you change a w3wp worker process to use 32-bit instead of 64-bit, the path changes from C:\Windows\System32\inetsrv to C:\Windows\SysWOW64\inetsrv and the whitelist entry does not match anymore.

Step

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

Possible Problems

On unmonitored .NET command-line applications (for example, MS PowerShell), you can see the two messages:

info [native] No Registry-Settings exist for this process

info [native] Agent has no active settings - running normally


For debugging reasons, the Agent also writes the logs to the console until the log settings to that process are read from the whitelist. You can disable this by using the environment variable DT_DISABLEINITIALLOGGING, set to TRUE.

Step

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).

Possible Problems

  • Windows services that use a .NET CLR cannot be started if Dynatrace tries to monitor them with a wrong Collector setting.
  • The IIS worker process is not starting.


  • Check the Collector settings.
  • Increase the service start timeout for the service control manager.
  • Check the startup time limit in the advanced settings of the IIS application pool.

Step

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

Possible Problems

No write access is allowed for the user the process is running with under <DT_HOME>\agent\downloads.

Give the user modify, read, and execute rights in the file system to that folder (check the bootstrap log).

Step

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.

Possible Problems

The application takes a long time to come up.

Place a Collector near the Agent or directly on the machine where the Agent and application are running, to shorten the path and avoid network latency.

For information about the Agent configuration causing high runtime overhead, see Agent Group - Agent Mapping > Advanced Settings.

Special behavior of IIS worker processes

Icon
  • 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.
  • As of IIS 7, 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:

    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, a reliable way is to do this via command prompt: