Configure the .NET Agent properties using a single configuration file. This topic describes the structure and content of the config.xml file to help you customize agent behavior. To use the .NET Agent Configuration Utility, see Configure the .NET Agent.

Overview

The .NET Agent uses a single configuration file to control agent behavior: Controller connectivity, machine agent operations, and app agent functionality for IIS applications, Windows services, and standalone applications such as console applications, WinForms, or WPF. Benefits of the unified configuration file include:

• Maintain agent configurations separately from web.config files.
• Enable instrumentation of Windows services and standalone applications without environment variables.
• Control agent behavior for specific applications with hierarchical configuration.

To configure connection to the Controller, See Controller Element.

To configure the .NET machine agent, See Machine Agent Element.

To configure app agents for IIS applications, see App Agents - IIS Element.

To configure an app agent for a Windows service or standalone application, see App Agents - Standalone Applications Element.

Where to Configure App Agent Properties

%ProgramData%\AppDynamics\DotNetAgent\Config\config.xml

%AllUsersProfile%\Application Data\AppDynamics\DotNetAgent\Config\config.xml

Sample config.xml files install to the following location:

%ProgramFiles%\AppDynamics\AppDynamics .NET Agent\SampleConfigurations

 After you edit the config.xml, you must restart the AppDynamics.Agent.Coordinator service. Then restart IIS, your Windows service, or standalone application for your instrumentation changes to take effect.

Minimal .NET App Agent config.xml File

The most basic configuration demonstrates the required sections for agent configuration. This sample instruments all IIS applications using the automatic element (<automatic />). No Windows services or standalone applications are instrumented.

<?xml version="1.0" encoding="utf-8"?>
<appdynamics-agent xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
  <controller host="mycontroller.mycompany.com" port="8090" ssl=false">
    <application name="MyDotNetApplication" />
  </controller>
  <machine-agent />
  <app-agents>
    <IIS>
      <automatic />
    </IIS>
  </app-agents>
</appdynamics-agent>

AppDynamics Agent Element

The Appdynamics Agent element is the root container element for configurations in the config.xml.

Required Element: <appdynamics-agent xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">

Controller Element

The Controller element is a child of the AppDynamics Agent element. It specifies the connection information for the AppDynamics Pro Controller.

The .NET Agent configuration utility only supports configuration of one Controller per server.

Required Element: <controller host="mycontroller.mycompany.com" port="8090" ssl="false" high_availability="false">

Controller host attribute

The Controller host attribute indicates the host name or the IP address of the AppDynamics Controller. For an on-premise Controller, use the value for Application Server Host Name you provided when you installed the Controller. If you use the AppDynamics SaaS Controller, see the Welcome email from AppDynamics.

Type: String
Default: None
Required: Yes

Controller port attribute

The Controller port attribute specifies the HTTP(S) port of the AppDynamics Controller. If the Controller ssl attribute is set to true, specify the HTTPS port of the Controller; otherwise specify the HTTP port.

Type: Positive Integer
Default: 8090

For On-premise installations, the defaults are port 8090 for HTTP and port 8181 for HTTPS.

For the SaaS Controller, use port 80 for HTTP or port 443 for HTTPS.

Required: Yes

Controller ssl attribute

To enable encryption over SSL between the agent and the Controller, set the Controller ssl attribute to "true".

Type: Boolean
Default: false
Required: No

Controller high availability attribute

If you have your controller set up for high availability, set the Controller high availability attribute to "true".

Type: Boolean
Default: false
Required: No

Controller Application Element

The Controller Application element is a child of the Controller element. It indicates the name of the logical business application you see in the Controller interface.

The .NET Agent configuration utility only supports one business application per server.

• Use tiers to organize different applications you instrument on a single server.
• Or manually configure support for multiple business applications, see Configure Multiple Business Application Support for .NET.

Required Element: <application name="MyDotNetApplication"/>

Application name attribute

Set the application name attribute to the business application you use in the controller. If the application name does not exist, the Controller will create it when the agent registers. All instrumented applications in the config.xml register with the same business application in the Controller. See Logical Model.

Type: String
Default: None
Required: Yes

You specify a Tier for individual applications in the App Agents Element.

Account Element

The Account element is a child of the Controller element. If the AppDynamics Controller runs in multi-tenant mode or if you use the AppDynamics SaaS Controller, specify the account name and account access key for the agent to authenticate with the Controller. If you are using the AppDynamics SaaS Controller, the account name is provided in the Welcome email from AppDynamics.

Optional Element: <account name="mycontroller.saas.appdynamics.com" password="myaccesskey"/>

Account name attribute

The account name attribute indicates to the account name for the SaaS or multi-tenant Controller.

Type: String
Default: None
Required: Only for SaaS or multi-tenant Controllers

Account password attribute

The account password attribute indicates the access key for the SaaS or multi-tenant Controller.

Type: String
Default: None
Required: Only for SaaS or multi-tenant Controllers

Proxy Element

The Proxy element is a child of the Controller element. Use it to configure connection to the Controller through a proxy server with no authentication.

Optional Element: <proxy host="proxy-name" port="3128" enabled="true"/>

Proxy host attribute

The proxy host attribute indicates the proxy server host name or IP address.

Type: String
Default: None
Required: host is required for the proxy element

Proxy port attribute

The proxy port attribute indicates the proxy server port.

Type: Positive Integer
Default: None
Required: port is required for the proxy element

Proxy enabled attribute

To enable Controller access through a proxy server, set the proxy enabled attribute to "true".

Type: Boolean
Default: false
Required: No

Machine Agent Element

The Machine Agent element is a child of the AppDynamics Agent element. An empty Machine Agent element enables the default instrumentation for the .NET machine agent (See Monitor CLRs and Monitor IIS). Enable optional additional Microsoft Performance Counters or .NET Agent instrumentors as children of the Machine Agent element.

Required Element: <machine-agent/>

Machine Snapshot Element

The Machine Snapshot element is a child of the Machine Agent element. Use it to tune the settings for machine snapshots in your environment. If you don't specify an attribute, the agent uses the default values for that attribute. See Machine Snapshots for .NET and Configure Machine Snapshots for .NET.

Optional Element: <machine-snapshot enabled="true" window-size="600" samples-per-window="60" violations-per-window="6" max-percent-cpu="80" max-percent-memory="80" max-queue-item-age="100" periodic-collection="600" />

Machine Snapshot enabled attribute

Set the Machine Snapshot enabled attribute to "false" to disable machine snapshots.

Type: Boolean
Default: true
Required: No

Performance Counters Element

The Performance Counters element is a child of the Machine Agent element. It is a container for all performance counters.

Optional Element: <perf-counters>

Performance Counter element

The Performance Counter element is a child of the Performance Counters element. For a list of performance counters to enable, see Performance Counters in the .NET Framework.

Optional Element: <perf-counter cat="category" name="name" instance="instance"/>

Performance Counter cat attribute

The performance counter cat attribute indicates the performance counter category.

Type: String
Default: None
Required: Category is required for the Performance Counter element.

Performance Counter name attribute

The performance counter name attribute indicates the performance counter name.

Type: String
Default: None
Required: Name is required for the Performance Counter element.

Performance Counter instance attribute

The performance counter instance attribute is the performance counter instance value.

Type: String
Default: None
Required: Instance is required for the Performance Counter element.

Sample Machine Agent Configuration with Performance Counters

  <machine-agent>
    <!-- Additional machine level Performance Counters -->
    <perf-counters>
      <perf-counter cat="Network Interface" name="Bytes Sent" instance="Local Area Connection"/>
    </perf-counters>
  </machine-agent>

Instrumentation Element

The Instrumentation element is a child of the Machine Agent element. It allows you to enable additional .NET Agent instrumetors such as thread correlation or correlation for .NET remoting.

Optional Element: <instrumentation>

Instrumentor element

The Instrumentor element is a child of the Instrumentation element. The instrumentor element specifies the .NET Agent instrumentor to implement.

Optional Element: <instrumentor name="instrumentor name" enabled="true"/>/>

Instrumentor name attribute

The instrumentor name attribute indicates the instrumentor name.

Type: String
Default: None
Required: Name is required for the Instrumentor element.

Instrumentor enabled attribute

Set the instrumentor enabled attribute to "true" to enable instrumentation.

Type: Boolean
Default: false
Required: No.

The current configuration syntax is enabled="true". Versions prior to 3.7.8 used disabled="false".

Sample Machine Agent Configuration with Thread Correlation Instrumentors

 <machine-agent>
    <!--Enable thread correlation-->
    <instrumentation>
       <instrumentor name="ThreadCorrelationThreadPoolCLR2Instrumentor" enabled="true"/>
       <instrumentor name="ThreadStartCLR2Instrumentor" enabled="true"/>
       <instrumentor name="ThreadStartCLR4Instrumentor" enabled="true"/>
    </instrumentation>
  </machine-agent>

Additional .NET Agent Instrumetors

• See Enable Thread Correlation for .NET.
• See Enable Correlation for .NET Remoting.
• See Enable Instrumentation for WCF Data Services.

App Agents Element

The App Agents element is a child of the AppDynamics Agent element. It is a container for app agent configurations for IIS applications, Windows services, and standalone applications.

Required Element: <app-agents enabled="true">

App agents enabled attribute

To disable application monitoring on the server, set the app agents enabled attribute to "false".

Type: Boolean
Default: true
Required: No

Default Profiler Element

The default Profiler element is a child of the App Agents element. It defines customizations to the default profiler behavior for all instrumented .NET applications on the machine: IIS applications, application pools, Windows services, and standalone applications.

Optional Element: <profiler>

Profiler - Disabled Features Element

New in 3.9.4,  The Disabled Features element is a child of the Profiler element. Use this property to disable data collection mechanisms at the agent level for security or privacy reasons. This configuration overrides any configuration set by the Controller.

Optional Element: <disabled-features value="NONE"/>

Disabled features value attribute

The disabled features value is a comma separated list of features to disable. The available values are as follows:

• LOG_PAYLOAD: Override the log-request-payload node property to suppress logging http request payloads
• RAW_SQL: Override the capture-raw-sql node property to suppress logging raw sql output
• CUSTOM_EXIT_SNAP_DATA: Suppress snapshot data from custom exits points
• METHOD_INV_DATA_COLLECTOR: Suppress method invocation data collector user data
• HTTP_DATA_COLLECTOR: Suppress HTTP request data collector user data
• INFO_POINT: Suppress information point metrics
• ALL: Disable all the available features
• NONE: Don't disable features

Type: String
Default: NONE
Required: No

Sample Default Profiler Configuration with Disabled Features

<app-agents>
    <profiler>
      <disabled-features value="LOG_PAYLOAD,RAW_SQL,CUSTOM_EXIT_SNAP_DATA"/>
    </profiler>
...
</app-agents>

App Agents - IIS Element

The IIS element is a child of the App Agents element. There are three options to configure IIS applications:

• Automatic configuration
• Application pool configuration
• Application configuration

The settings for any application pool apply to all applications within the app pool unless the individual application has a specific configuration.

Explicit child-level configurations override parent-level configurations. Otherwise, children inherit parent configurations.

Optional Element: <IIS>

IIS Automatic Instrumentation Element

The Automatic element is a child of the IIS element. Use the Automatic element to enable or disable automatic instrumentation for all IIS apps. You can configure automatic instrumentation and manual instrumentation both. Manual configurations override automatic ones.

Optional Element: <automatic enabled="false" />

Automatic enabled attribute

Set the automatic enabled attribute to "true" to enable instrumentation for all IIS applications. This is the default setting if you use the .NET Agent Configuration Utility automatic configuration option. To disable automatic instrumentation for all IIS applications, set the value to "false".

Type: Boolean
Default: true
Required: No

IIS Application Pools Element

The IIS Application Pools element is a child of the IIS element. It is a container element for all the IIS application pools you configure for instrumentation.
Optional Element: <application-pools>

IIS Application Pool Element

The Application Pool element is a child of the Application Pools element.. You may have multiple application pool elements distinguished by the name attribute. Use the application pool element to configure the app agent for all applications within an application pool. For more information on IIS application pools, see Managing Application Pools in IIS.

Application-specific configurations in the IIS Applications element override application pool configurations.

Optional Element: <application-pool name="DefaultAppPool" enabled="false">

Application pool name attribute

The application pool name attribute indicates the name of the IIS Application Pool.

Type: String
Default: None
Required: Name is required for the Application Pool element.

Application pool enabled attribute

Set the application pool enabled attribute to "false" to disable instrumentation for all applications in the application pool. Set the value to "true" to instrument all applications in the application pool.

Type: Boolean
Default: None. Defaults to true if not specified.
Required: No

Application Pool Tier Element

The Tier element is a child of the Application Pool element. If you enable instrumentation for an Application pool, you must use a Tier element to assign the pool's applications to a tier in the Controller. See Logical Model.

Required Element: <tier name="Inventory" />

Tier name attribute

Use the tier name attribute to specify the tier.

Type: String
Default: None
Required: Yes

IIS Applications Element

The IIS Applications element is a child of the IIS element. It is a container element for all the IIS applications you configure for instrumentation.
Optional Element: <applications>

Application Element

The Application element is a child of the Applications element. Use multiple application elements to instrument different sites and applications. To learn more about IIS sites and applications, see Understanding Sites, Applications, and Virtual Directories on IIS 7 and Above.

Optional Element: <application path="/" site="FirstSite" port="8008">

Application site attribute

The application site attribute indicates the root site in IIS for the application.

Type: String
Default: None
Required: Site is required for the Application element.

Application path attribute

The application path attribute indicates the application's path relative to the root site. Use the forward slash to indicate the root site and instrument all children applications. Use the path to an application to instrument the specific application and any children.

For example: Site1 hosts two applications AppX and AppY. To instrument Site 1, AppY and AppZ, set the path to "/". To instrument AppY, but not AppZ, set the path to "/AppY".

Type: String
Default: /
Required: Path is required for the Application element.

Application port attribute

For cases where two or more sites in IIS 6 have the same site name, set the site port attribute to differentiate between the sites.

Type: Positive Integer
Default: None
Required: No

Application enabled attribute

In certain cases you may want to enable instrumentation for a parent application, but disable it for a child application. In this case create an Application element for the child application to disable and set the application enabled attribute to to "false".

Type: Boolean
Default: true
Required: No

Application Tier Element

The Tier element is a child of the Application element. If you enable instrumentation for an application, your must use a Tier element to assign the application to a tier in the Controller. See Logical Model.

Required Element: <tier name="Consumer" />

Tier name attribute

The tier name attribute indicates the business application tier.

Type: String
Default: None
Required: Yes

Sample IIS Application Configuration

    <IIS>
      <!-- Automatic instruments all IIS applications when enabled -->
      <automatic enabled="false" />

      <!-- Application Pool agent configurations -->
      <application-pools>
        <!-- Do not instrument applications in DefaultAppPool when "enabled" attribute is set to false -->
        <application-pool name="DefaultAppPool" enabled="false">
          <tier name="Tier Name"/>
        </application-pool>

        <!-- Instrument applications in the OtherAppPpool and assign them to the Inventory tier -->
        <application-pool name="OtherAppPool">
          <tier name="Inventory"/>
        </application-pool>
      </application-pools>

      <applications>
        <!-- Instrument all applications in the First Site -->
        <application path="/" site="FirstSite">
          <tier name="Order"/>
        </application>
        <!-- Instrument the /app application and child apps in the Second Site -->
        <!-- but not the root Second Site application -->
        <application path="/app" site="SecondSite">
          <tier name="Consumer"/>
        </application>
      </applications>
    </IIS>

App Agents - Standalone Applications Element

The Standalone Applications element is a child of the App Agents element. It is a container element for all the Windows services or standalone applications you configure for instrumentation. See Enable the .NET Agent for Windows Services and Standalone Applications.

Optional Element: <standalone-applications>

Standalone Application Element

The Standalone Application element is a child of the Standalone Applications element. It specifies a Windows service or standalone application to instrument.

Optional Element: <standalone-application executable="MyWindowsApplication.exe">

Standalone Application executable attribute

The standalone application executable attribute specifies the file name of the Windows service or standalone application to instrument.

Only use the application file name. Do not include the full path to the file. For example, if you want to instrument, C:\Program Files\My Application\MyApp.exe, the executable value is "MyApp.exe". The file extension is optional, so "MyApp" also works.

Type: String
Default: None
Required: Yes

Standalone application app-domain-name attribute

For applications with multiple application domains, the app-domain-name attribute enables you to limit instrumentation to specific application domains. See Configure Application Domain Monitoring.

Type: String
Default: None
Required: No

Standalone Application Tier Element

The Tier element is a child of the Standalone Application element. If you enable instrumentation for an application, your must use a Tier element to assign the application to a tier in the Controller. See Logical Model.

Required Element: <tier name="Consumer" />

Tier name attribute

The tier name attribute indicates the business application tier.

Type: String
Default: None
Required: Yes

Sample Windows service and Standalone Application Configuration

<standalone-applications>
      <standalone-application executable="ExampleApplication.exe">
        <tier name="Standalone Application Tier"/>
      </standalone-application>
      <!-- Instrument a Windows service. -->
      <standalone-application executable="MyWindowsService.exe">
        <tier name="Windows Service Tier"/>
      </standalone-application>
</standalone-applications>

Learn More

• Logical Model
• Name Business Applications, Tiers, and Nodes
• Configure the .NET Agent
• Enable the .NET Agent for Windows Services
• Enable the .NET Agent for Windows Services and Standalone Applications