AppDynamics Application Intelligence Platform

3.8.x Documentation



Release Notes

Child pages
  • Configure the App Agent for .NET

AppDynamics Inc.

Skip to end of metadata
Go to start of metadata

The App Agent for .NET requires information about your .NET applications: IIS applications, Windows services, or standalone applications. Configure the App Agent for .NET according to what kind of application you want to monitor:

Use the App Agent for .NET Configuration Utility to configure the agent just after installation, or to make changes to existing agent configurations.

Configuration Considerations

AppDynamics recommends that you install the Controller, or have access credentials to a SaaS Controller, before installing an agent.

Prior to configuration, run the .NET Agent Installer. See Install the App Agent for .NET.

The utility configures one agent at a time.

AppDynamics implements the profile API of the .NET CLR. Since a Windows machine only allows use of one profiler at a time, you must uninstall any pre-existing profiler, such as Ant, VS 2010 Performance Tools, or others. The utility alerts you if it finds a pre-existing profiler.

(warning) To apply configurations, the .NET Agent Configuration Utility must restart IIS. The utility offers you the option to restart IIS or not. If you choose not to restart, configurations apply the next time IIS restarts.

File System Security Settings

For the App Agent for .NET to instrument your application correctly, ensure the following Windows accounts have the required file system access permissions:

  • The account you use to run your web application as defined by its application pool or the Windows service account.
  • The account you use to run the AppDynamics Agent Coordinator, by default the Local System account.

The required permissions are as follows:

  • Write permission to the .NET App Agent logs directory:
         For agent version 3.7.8 or later, the default is as follows:
             Windows Server 2008 and later: %ProgramData%\AppDynamics\DotNetAgent\Logs
             Windows Server 2003: %AllUsersProfile%\Application Data\AppDynamics\DotNetAgent\Logs
         For agent version 3.7.7 or earlier, the default is C:\Appdynamics\Logs.
  • Read and Execute permissions to to the .NET App Agent install directory, by default C:\Program Files\AppDynamics\AppDynamics .NET Agent
  • Read and Execute permissions the web application installation directory, for example C:\inetpub\wwwroot\myapp

Configuring an App Agent for .NET

To access the .NET Agent Configuration Utility

1. In the Windows menu, click AppDynamics -> .NET Agent -> AppDynamics Agent Configuration.

2. If the "Warning: 3rd Party Profiler installed" message displays, it means that the configuration utility has discovered another profiler. Windows only allows one profiler per machine. Because AppDynamics uses a profiler you must uninstall any other profilers.

Click Yes to exit and uninstall any pre-existing profiler. Check the registry to make sure that the uninstall process cleaned up the registry entries. Use the warning message to identify any undeleted profiler environment variables.  

Video Tutorial: Manual Installation And Configuration


3. When the configuration utility detects legacy agent configurations from version 3.7.7 or earlier, it displays the Upgrade Configuration window.

(warning) Removing legacy configurations modifies web.config files causing IIS to restart affected applications.

  • Answer No to leave legacy configurations in place. You can remove them at a later time.

4. When the utility discovers no further profiler conflicts or after any configuration clean up, the welcome window displays.

Click Next to advance to Log directory permissions.

To set up the logs and account permissions

The first window helps you set up the location of the agent logs and provide the correct account access to the logs.

1. If you want to change the default location of the log directory, click Change and select a new location.

(info) The default logs directories are as follows:
Windows Server 2008 and later: %ProgramData%\AppDynamics\DotNetAgent\Logs
Windows Server 2003: %AllUsersProfile%\Application Data\AppDynamics\DotNetAgent\Logs

2. If needed, add accounts for log directory permissions.
Commonly-used accounts are provided. If your application uses another account, enter the Windows account you use to run your web application as defined by its application pool or the Windows service account. The account name must be valid on the operating system and have permission to write to the log files directory.

3. Click Add. If you get a warning message, make sure that the account is valid on the system.

4. Click Next and the wizard confirms the list of accounts.

5. Click Next to advance to Controller Configuration.

To provide Controller configuration information

1. Enter the Controller access information and credentials.

  • The App Agent for .NET configuration utility only supports configuration of one Controller and business application per server.
  • For a SaaS Controller, enter the server name or IP, port number, account name, and access key as provided to you by AppDynamics.
  • For an on-premise Controller, if you haven't already installed it, cancel this installation and see Install the Controller. Otherwise enter the server name and port number of an existing Controller.
  • For a secure connection, click  Enable SSL
    (info) The Controller must use a trusted certificate.
  • If needed, fill in the proxy information. Proxies that use authentication require additional configuration. 

2. Click Test Controller Connection to verify the connection.

3. Click Next to advance to the Application Configuration

AppDynamics retrieves existing business application information from the Controller and displays it in the left column. Controller connection status displays on the right.

4. Click Existing Applications from the Controller to select business applications from the Controller.

If you haven't defined business applications in the Controller, the utility displays an empty list.

    Click New Application to define a new business application. Be careful about spellings and capitalization and note down the exact name.

(info) Do not use ampersands in the business application name; they are not supported at this time.

5. Click Next to advance to Assign IIS applications to tiers.

To map business applications, tiers, and nodes to your application environment

1. Read about how AppDynamics uses business applications, tiers, and nodes to organize application performance monitoring. In summary:

  • A business application is a set of modules and distributed services that together provide business functionality.
  • A node is the basic unit of processing that AppDynamics monitors.
  • A tier represents a module in an application environment, such as an eCommerce website or Inventory application.

See Logical Model.

2. Decide how to identify and name the tiers. Either AppDynamics will automatically configure tier names, or you can manually configure them.

Use these guidelines for deciding whether to use automatic or manual naming:

  • To have AppDynamics instrument all IIS applications on a machine, choose automatic.
  • AppDynamics names tiers using this pattern:

  • To select the IIS applications on a machine to instrument with AppDynamics, choose manual.
  • Using manual naming, you supply the tier names and AppDynamics updates the configuration file.

To let AppDynamics automatically name the tiers

1. In the Assign IIS applications to tiers window click Automatic.

2. If prompted, click OK to confirm Automatic configuration.

The configuration utility summarizes the configuration settings.

3. By default when you click Next the configuration utility restarts IIS.
(warning) If you do not want to apply the configuration right away, uncheck the box. The Configuration Utility saves the information and applies it the next time you restart IIS.

4. If you proceed and click Next, the configuration utility logs its activities, including stopping and restarting IIS, and reports any problems. Review the summary for any issues in red font. Green font indicates the more interesting logged events. The summary shows any Warnings (W) or Errors (E). If you have errors, contact AppDynamics Support

5. When there are no errors, click Next.

6. Click Done to close the Configuration Utility. 

To manually name the tiers

1. In the Assign IIS applications to tiers window click Manual, then click Next.

2. Assign IIS Applications to AppDynamics tiers.

Select a tier on the right and click a business application on the left. The assigned tier will be highlighted in boldface.

(info) For large IIS installations, use the Max IIS tree depth pulldown to display all the projects. A large tree depth may take some time to view.

To create new tiers, enter a name and click Add Tier.

5. When you are done click Next. AppDynamics displays a configuration summary.

6. Review the configuration. If you need to make changes click Back.

7. On the Configuration Summary window, un-check Restart IIS if you don't want to immediately restart IIS.

You may restart later to apply your changes, or they will take effect after a reboot.

7. If you proceed and click Next, the Configuration Utility logs its activities, including stopping and restarting IIS, and reports any problems.

8. Review the configuration log summary.
As it applies the configuration, AppDynamics generates a log of the configuration activities and displays a summary. Review the summary for any issues in red font. Green font indicates the more interesting logged events.  The summary shows any Warnings (W) or Errors (E). If you have errors, contact AppDynamics Support.

9. Click Next. The wizard completes.

For troubleshooting information see Resolve App Agent for .NET Installation and Configuration Issues.

Using a Configuration File from the Command Line

You can set up a .NET Agent configuration file and run it from the command line. This is useful when you have multiple agents to configure.

To create a configuration file

1. From a command line, start the configuration utility:

AppDynamics.Agent.Winston.exe -s <SetupConfigurationFilePath>

For example:

c:\Program Files\AppDynamics\AppDynamics .NET Agent\AppDynamics.Agent.Winston.exe -s "c:\temp\configurationSavedSetupConfiguration.xml"

The utility starts.
2. Configure the agent as described in the previous sections. The configuration is applied.
In addition, when the configuration completes, AppDynamics creates a setup file.

Use this setup file as an argument to the command line utility.

(info) To perform an unattended installation, pass the configuration file directly to the MSI installer package. See Unattended Installation for .NET.

To run the configuration utility from the command line

1. Start the .NET Configuration Utility from the command line. Change the file path and setup file path as needed.

AppDynamics.Agent.Winston.exe -c <SetupConfigurationFilePath>

For example:

c:\Program Files\AppDynamics\AppDynamics .NET Agent\AppDynamics.Agent.Winston.exe -c "c:\temp\configurationSavedSetupConfiguration.xml"

The utility runs in command line mode; the user interface does not launch.

When it finishes, the utility exits the process with status 0 for success or any other number for failure.

2. Review the Winston.txt log file in the default logs directory for details.

Learn More