4.0.x Documentation


PDFs

Learn by Watching


This page applies to an earlier version of the AppDynamics App IQ Platform.
For documentation on the latest version, see the 4.4 Documentation.


Skip to end of metadata
Go to start of metadata

On this page:

Related pages:

This topic is a reference for the configuration properties for the .Net Agent config.xml file. For information about how to edit the file and apply your changes, see Administer the .NET 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.

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

Required Element: <controller host="mycontroller.mycompany.com" port="8090" ssl="false" enable_tls12="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 enable TLS 1.2 attribute

4.0 to 4.0.3: When you enable SSL, the agent encrypts communications with the Controller using TLS 1.2 by default. If you are unwilling or unable to use TLS 1.2, set the Controller enable TLS 1.2 attribute to "false". 

New in 4.0.4: When you enable SSL, the agent secures communication to the Controller using the protocols set for ServicePointManager.SecurityProtocol in your application. Set the Controller enable TLS 1.2 attribute to "true" to add TLS 1.2 as the first option in the list of protocols. This affects all secure communications from your application, not just requests to the AppDynamics Controller.

Type: Boolean
Default: 4.0 to 4.0.3: true; 4.0.4 and later: 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.
    (info) Multiple application support has requires different configuration elements, including the <applications> container element.

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

Type: String
Default: None
Required: Yes

(info) 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 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: true
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

 

Machine Snapshot window size attribute

Specify the window size time range in seconds for the .NET Machine Agent to take samples. During a window, the agent takes samples and checks them for breached thresholds: max percent CPU, the max percent memory, and max queue item age.

Type: Integer
Default: 600
Required: No

Machine Snapshot samples per window attribute

Specify the number of samples the .NET Machine Agent takes during the specified window. For example, if the window size is 600 and the samples per window is 60, the agent takes a sample once every 10 seconds.

Type: Integer
Default: 60
Required: No

Machine Snapshot violations per window attribute

When the .NET Machine Agent detects the number of violations per window for one threshold, it takes a snapshot. The agent only takes one snapshot per window for thresholds exceeded. For example, if the violations per window is set to 6, and six samples show memory usage at 80% or greater, the agent takes a snapshot. The counters for each threshold are separate.

Type: Integer
Default: 6
Required: No

Machine Snapshot max percent memory attribute

When the .NET Machine agent detects CPU usage on the machine equals or exceeds the max percent cpu value, it flags the sample as a violation. The minimum value is 20; the maximum value is 100.

Type: Integer
Default: 80
Required: No

Machine Snapshot max percent cpu attribute

When the .NET Machine agent detects memory usage on the machine equals or exceeds the max percent memory value, it flags the sample as a violation. The minimum value is 20; the maximum value is 100.

Type: Integer
Default: 80
Required: No

Machine Snapshot max queue item age attribute

When the .NET Machine agent detects the oldest item in the IIS queue equals or exceeds the max queue item age value in milliseconds, it flags the sample as a violation.

Type: Integer
Default: 100
Required: No

Machine Snapshot periodic collection attribute

The .NET Machine agent takes one snapshot per periodic collection time range. Specify the value in seconds. The minimum is 60 seconds.

Type: Integer
Default: 600
Required: No

CLR Crash Reporting Element

The CLR Crash Reporting element is a child element of the Machine Agent element. Use the CLR Crash Reporting element to control whether or not the .NET Machine Agent reports CLR crash events to the Controller. See Monitor CLR Crashes.

Optional Element: <clrcrash-reporting enabled="true"/>

CLR Crash Reporting enabled attribute

Set the enabled attribute to "false" to stop reporting CLR Crash events to the controller. 

Type: Boolean
Default: true
Required: No

Process Monitor Element

The Process Monitor element is a child element of the Machine Agent element. By default, the agent enables process monitoring for all IIS processes.

Optional Element: <process-monitor report-all-iis-processes="true"/>

Process Monitor report all IIS processes attribute

New in 4.0.1, set the report-all-iis-prcocesses attribute to "false" to enable process monitoring only for instrumented IIS processes. 

Type: Boolean
Default: true
Required: No

Metrics Element

The Metrics element is a child element of the Machine Agent element. By default, the machine agent registers a maximum of 200 metrics. See Metrics Limits. Use the Metrics element to increase the number of metrics the .NET Machine Agent can register.

Use caution when increasing the metric registration limits. Increasing the limit can increase the resource overhead for agents and Controller.

Optional Element: <metrics max-metrics="200"/>

Metrics max-metrics attribute

Specify the maximum number of metrics the .NET Machine Agent can register. 

Type: Integer
Default: 200
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.

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

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

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

Profiler - Successful Exit Code Element

The Successful Exit Code element is a child of the Profiler element.  The default successful exit code determines whether or not the agent flags a CLR restart event as graceful or not for Windows services or standalone applications. This configuration doesn't apply to IIS. 

Optional Element: <successful-exit-code value="0"/>

Successful exit code value attribute

Type: Integer
Default: 0
Required: No

Sample Default Profiler Configuration

<app-agents>
    <profiler>
      <disabled-features value="LOG_PAYLOAD,RAW_SQL,CUSTOM_EXIT_SNAP_DATA"/>
	  <-- Set the successful exit code for Windows services and standalone applications to "1." -->
      <successful-exit-code value="1"/>
    </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.

(warning) 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 AppDynamics Concepts.

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" site-regex="false">

Application site attribute

The application site attribute indicates the root site in IIS for the application. The site name accepts a regular expression for cases like windows Azure where you may only know a partial site name. If you use a regular expression, set the Application site-regex attribute to true. For an example, see "Customize Tier Names for Azure Roles" on Install AppDynamics for Windows Azure with NuGet.

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

Application site-regex attribute

Set the Application site-regex attribute to true to treat the value of the Application site attribute as a regular expression.

Type: Boolean
Default: false
Required: No

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

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>
        <!-- Regular expression for site name -->
        <!-- assigns all sites beginning with "MyRole" to the Credit Services tier. -->
        <application path="/" site="MyRole_\w+" site-regex="true">
            <tier name="Credit Services"/>
        </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 standalone applications you configure for instrumentation.

(info) For instructions to instrument standalone applications, see Instrument 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" command-line="">

Standalone Application executable attribute

The standalone application executable attribute specifies the file name of the Windows application to instrument. Set the Standalone Application element executable attribute to one of the following:

  • Executable name. For example, MyStandaloneApp.exe or MyWindowsService.exe. The file extension is optional, so MyStandaloneApp also works.

  • Full path to the executable. For example, C:\Program Files\MyApplication\MyStandaloneApp.exe.
  • Partial path to the executable. For example, MyApplication\MyStandaloneApp.exe. Use the full or partial path to the executable when you want to assign different tiers to separate instances of the same executable running from different paths.

Type: String
Default: None
Required: Yes

Standalone Application command-line attribute

To differentiate between two instances of the same executable, specify any unique portion of the application's command line, such as an argument, in the Standalone Application command-line attribute.

Type: String
Default: None
Required: No

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

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 using arguments. -->
  <!-- The following example matches the command "MyWindowsService.exe -d -x -r". -->
  <standalone-application executable="MyWindowsService.exe" command-line="-x">
    <tier name="Windows Service Tier"/>
  </standalone-application>
</standalone-applications>


Have a question about the topic on this page? Ask the AppDynamics Community.