.NET agent configuration

The New Relic .NET agent gets its configuration from the newrelic.config file. It looks for this file in:

  • The web root directory (for web applications)
  • Your execution path (where the executable is located)
  • The current working directory
  • New Relic agent home directory:
    Default: %ALLUSERSPROFILE%\New Relic\.NET Agent
    Windows 2003 only: %ALLUSERSPROFILE%\Application Data\New Relic\.NET Agent

You can also configure two settings in your app's config file: the application name and a boolean flag to enable or disable the agent.

Note: After making any changes to your newrelic.config or app's config file, always perform an IISRESET from an administrative command prompt.

Setup options

Use these options to setup and configure your agent. New Relic for .NET supports the following categories of setup options:

Multiple applications

To specify different configuration options for multiple applications or application pools, include a separate newrelic.config in each application's root directory.

Tip: You can use the global version of newrelic.config to configure system-wide settings, and specify individual application names in web.config. This ensures each app reports to a unique application name, without maintaining individual newrelic.config files for each of your apps.

Configuration element

The root element of the configuration document is a configuration element.


<configuration xmlns="urn:newrelic-config"
  agentEnabled="true"
  maxStackTraceLines="50"
  timingPrecision="high">

The configuration supports the following attributes:

agentEnabled
Type Boolean
Default True

Enable or disable the New Relic agent.

maxStackTraceLines
Type Integer
Default 80

The maximum number of stack frames to trace in any stack dump.

timingPrecision
Type String
Default Low

Controls the precision of the timers. High precision will provide better data, but at a lower execution speed. Possible values are high and low.

Service element

The first child of the configuration element is a service element. The service element configures the agent's connection to the New Relic service.


<service licenseKey="key"
  ssl="true"
  sendEnvironmentInfo="true"
  syncStartup="false"
  sendDataOnExit="false"
  sendDataOnExitThreshold="60000">

The service supports the following attributes:

licenseKey
Type String
Default (none)

Your New Relic account key. This is used to match your data to the correct account that appears in the UI.

ssl
Type Boolean
Default True

By default, the agent uses SSL to communicate with New Relic. Set to false to disable SSL.

sendEnvironmentInfo
Type Boolean
Default True

Instructs the agent to record execution environment information. Environment information includes operating system, agent version, and which assemblies are available.

syncStartup
Type Boolean
Default False

Block application startup until the agent connects to New Relic. If set to true, the first transaction may take substantially longer to complete, because it is blocked until the connection to New Relic is finished.

sendDataOnExit
Type Boolean
Default False

Block application shutdown until the agent sends all data from the latest harvest cycle.

sendDataOnExitThreshold
Type Integer
Default 60000
Unit Milliseconds

The minimum amount of time the process must run before the agent blocks it from shutting down. This setting only applies when sendDataOnExit is true.

requestTimeout
Type Integer
Default

2000 (sendDataOnExit enabled)

120000 (sendDataOnExit disabled)

Unit Milliseconds

The agent's request timeout when communicating with New Relic.

Proxy element

The proxy element is an optional child of the service element. Use the proxy element if you want the agent to communicate with New Relic service via a proxy.


<proxy
  host="hostname"
  port="81"
  domain="mydomain.com"
  user="newrelic"
  password="xyz"/>

The proxy supports the following attributes:

host
Type String
Default (none)

Defines the proxy host.

port
Type Integer
Default 8080

Defines the proxy port.

domain
Type String
Default (none)

Optionally define a domain to use when authenticating with the proxy server.

user
Type String
Default (none)

Optionally define a user name for authentication.

password
Type String
Default (none)

Optionally define a password for authentication.

Log element

The log element is a child of the configuration element. The log element configures New Relic's logging . The agent generates its own log file to keep its logging information separate from your application's logs.


<log level="info"
  auditLog="true"
  console="true"
  directory="c:\temp"
  fileName="newrelic.log" />

The log supports the following attributes:

level
Type String
Default Info

Defines the level of detail recorded in the log file. Possible values, in increasing order of detail, are:

  • off
  • emergency
  • fatal
  • alert
  • critical
  • severe
  • error
  • warn
  • notice
  • info
  • debug
  • fine
  • trace
  • finer
  • verbose
  • finest
  • all

Increasing the logging level will increase New Relic's performance impact.

auditLog
Type Boolean
Default False

Records all data sent to and received from New Relic in both an auditlog log file and the standard log file.

console
Type Boolean
Default False

Send log messages to the console, in addition to the log file.

directory

The directory to hold log files generated by the agent. If this is omitted, then a directory named logs in the New Relic Agent installation area will be used by default.

fileName
Type String
Default (none)

Defines a name for the log file. If you do not define a fileName, the name is derived from the name of the monitored process.

Application element (configuration)

The application element is a child of the configuration element. This element defines your application name, and disables or enables sampling.

name
Type String
Default My Application

The name of your application is a child of the application element. New Relic will aggregate your data according to this name. For example, if you have two running applications named AppA and AppB, you will see two applications in the New Relic interface: AppA and AppB (for more information, see Naming your .NET application). The first name assigned to an application mustbe unique. For example:

<application>
  <name>My App</name>
</application>
disableSamplers
Type Boolean
Default False

Samplers collect information about memory and CPU consumption. Set this to true to disable sampling.

Instrumentation options

Use these options to configure which elements of your application and environment to instrument. New Relic for .NET supports the following categories of instrumentation options:

Instrumentation element

The instrumentation element is a child of the configuration element. By default, the .NET agent instruments IIS asp worker processes and Azure web and worker roles. To instrument other processes, see Instrumenting custom applications.

Applications element (instrumentation)

The applications element is a child of the instrumentation element. The applications element specifies which non-web apps to instrument. It contains a name attribute.

Note: This is not the same as the application (configuration) element, which is a child of the configuration element.


<instrumentation log="false">
  <applications>
    <application name="MyService1.exe" />
    <application name="MyService2.exe" />
    <application name="MyService3.exe" />
  </applications>
</instrumentation>

Attributes element

An attribute is a key/value pair that determines the properties of an event or transaction. Each attribute is sent to APM transaction traces, APM error traces, Insights transaction events, or Insights PageView events. The primary attributes element enables or disables attribute collection for the .NET agent, and defines specific attributes to collect or exclude. You can also configure attribute settings based on their destination: Error collection, transaction traces, page load timing, and transaction events.

In this example, the agent excludes all attributes whose key begins with myApiKey (myApiKey.bar, myApiKey.value), but collects the custom attribute myApiKey.foo.


<attributes enabled=”true”>
  <exclude>myApiKey.*</exclude>
  <include>myApiKey.foo</include>
</attributes>

You can also define custom attributes with the agent API methods AddCustomParameter (System.lConvertible), AddCustomParameter (System.String), and SetUserParameters.

enabled
Type Boolean
Default True

Enable or disable attribute collection. When set to false in the primary attribute element, this setting overrides all attribute settings for individual destinations.

include
Type String
Default (None)

If attributes are enabled, the agent will collect all attribute keys specified in this list. To specify multiple attribute keys, specify each individually. You can also use a * wildcard character at the end of a key to match multiple attributes (for example, myApiKey.*). For more information, see Attribute rules.

exclude
Type String
Default (None)

If attributes are enabled, the agent will not collect attribute keys specified in this list. To specify multiple attribute keys, specify each individually. You can also use a * wildcard character at the end of a key to match multiple attributes (for example, myApiKey.*). For more information, see Attribute rules.

Feature options

Use these options to enable, disable, and configure New Relic features. New Relic for .NET allows you to configure the following features:

App pools

The applicationPools element is a child of the configuration element. applicationPools specifies for the profiler exactly which which application pools should be instrumented. This configuration element is useful when you may need to instrument only a small subset of your app pools. For example, a given server might have several hundred application pools, but only a few of those pools need to be instrumented by the .NET agent.

Here is an example of disabling instrumentation for specific application pools:


<applicationPools>
  <applicationPool name="Foo" instrument="false"/>
  <applicationPool name="Bar" instrument="false"/>
</applicationPools>

Here is an example of disabling instrumentation for all application pools currently executing on the server and enabling instrumentation for specific application pools:


<applicationPools>
  <defaultBehavior instrument="false"/>
  <applicationPool name="Foo" instrument="true"/>
  <applicationPool name="Bar" instrument="true"/>
</applicationPools>

The applicationPools supports the following elements:

defaultBehavior
Type Boolean
Default False

Defines how the .NET agent will behave on a "global" level for application pools served via IIS. The .NET agent instruments all application pools by default. When true, application pools listed under applicationPool with an instrument attribute set to false will not be instrumented.

Essentially, when set to false, the application pool list act as a whitelist. When set to true, the application pool list acts as a blacklist.

applicationPool

Defines instrumentation behavior for a specific application pool. The name attribute is the name of an application pool. Enable or disable profiling in the instrument attribute. Define this application in the name attribute.

Cross application traces

The crossApplicationTracer element is a child of the configuration element. crossApplicationTracer links transaction traces across applications. When linked in a service-oriented architecture, all instrumented applications that communicate with each other via HTTP will now "link" transaction traces with the applications that they call and the applications they are called by. Cross application tracing makes it easier to understand the performance relationship between services and applications.


<crossApplicationTracer enabled="true"/>

The crossApplicationTracer supports the following attribute:

enabled
Type Boolean
Default True

Enable or disable cross application tracing

Error collection

The errorCollector element is a child of the configuration element. errorCollector configures error collection, which captures information about uncaught exceptions and sends them to New Relic.


<errorCollector enabled="true">
  <ignoreErrors>
    <exception>System.IO.FileNotFoundException</exception>
    <exception>System.Threading.ThreadAbortException</exception>
  </ignoreErrors>
  <ignoreStatusCodes>
    <code>401</code>
    <code>404</code>
  </ignoreStatusCodes>
  <attributes enabled=”true”>
    <exclude>myApiKey.*</exclude>
    <include>myApiKey.foo</include>
  </attributes>
</errorCollector>

The errorCollector supports the following elements and attribute:

enabled
Type Boolean
Default True

Enable or disable the error collector.

ignoreErrors
Type String
Default (none)

Lists specific exceptions to not report to New Relic. The full name of the exception should be used, such as System.IO.FileNotFoundException.

ignoreStatusCodes
Type String
Default (none)

Lists specific HTTP error codes to not report to New Relic. You can use standard integral HTTP error codes, such as just 401, or you may use Microsoft full status codes with decimal points, such as 401.4 or 403.18.

attributes

Use this sub-element to customize your agent attribute settings for error traces. This sub-element uses the same settings as the primary attributes element: enabled, include, and exclude.

High security mode

The highSecurity element is a child of the configuration element. To enable high security mode, set this property to true and enable high security property in the New Relic user interface. Enabling high security means SSL is turned on, request and message queue parameters are not collected, and SQL cannot be sent to New Relic in its raw form.

enabled
Type Boolean
Default False

Enable or disable high security mode. Example:

<highSecurity enabled="true"/>

Transaction events

The transactionEvents element is a child of the configuration element. Use transactionEvents to configure transaction events.


<transactionEvents enabled="true" 
  maximumSamplesPerMinute="10000" 
  maximumSamplesStored="10000">
 <attributes enabled=”true”>
    <exclude>myApiKey.*</exclude>
    <include>myApiKey.foo</include>
  </attributes>  
</transactionEvents>

TransactionEvents supports the following attributes:

enabled
Type Boolean
Default True

Enable or disable the event recorder.

maximumSamplesPerMinute
Type Integer
Default 10000

The maximum number of samples to send per minute.

maximumSamplesStored
Type Integer
Default 10000

The maximum number of samples to store in memory at once.

attributes

Use this sub-element to customize your agent attribute settings for transaction events. This sub-element uses the same settings as the primary attributes element: enabled, include, and exclude.

Labels

The labels element is a child of the configuration element. This sets the label names and values to associate with the application. The list is a semicolon delimited list of colon-separated name and value pairs. You can also use with theNEW_RELIC_LABELS environment variable. Example:

<labels>foo:bar;zip:zap</labels>

Page load timing

The browserMonitoring element is a child of the configuration element. browserMonitoring configures page load timing (sometimes referred to as real user monitoring or RUM) in your .NET application. Page load timing gives you insight your end users' performance experience. This is accomplished by measuring the time it takes for your users' browsers to download and render your webpages by injecting a small amount of JavaScript code into the header and footer of each page.


<browserMonitoring autoInstrument="true">
<attributes enabled=”true”>
    <exclude>myApiKey.*</exclude>
    <include>myApiKey.foo</include>
  </attributes>
 </browserMonitoring>

The browserMonitoring supports the following attributes:

autoInstrument
Type Boolean
Default True

By default the agent automatically injects the JavaScript for page load timing into ASP pages. To turn off automatic page load timing, set this attribute to false.

attributes

Use this sub-element to customize your agent attribute settings for page load timing. This sub-element uses the same settings as the primary attributes element: enabled, include, and exclude.

Slow SQL

The slowSql element is a child of the configuration element. slowSql configures capturing information about slow SQL executions, and captures and obfuscates explain plans for these queries.


<slowSql enabled="true"/>

The slowSql supports the following attribute:

enabled
Type Boolean
Default True

Enable or disable slow SQL.

Transaction traces

The transactionTracer element is a child of the configuration element. transactionTracer configures transaction traces. Included in the trace is the exact call sequence of the transactions, including any SQL statements issued.

<transactionTracer enabled="true"
    transactionThreshold="apdex_f"
    stackTraceThreshold="500"
    recordSql="obfuscated"
    explainEnabled="true"
    explainThreshold="500"
    maxSegments="3000"
    maxStackTrace="30"
    maxExplainPlans="20">
  <attributes enabled=”true”>
    <exclude>myApiKey.*</exclude>
    <include>myApiKey.foo</include>
  </attributes>
 </transactionTracer>

The transactionTracer supports the following attributes:

enabled
Type Boolean
Default True

Enable or disable transaction tracing.

Note: Transaction traces available only to New Relic Pro subscription levels and higher.

transactionThreshold
Type String
Default apdex_f

Defines a threshold for a "slow" transaction. Over this threshold, the agent will collect transaction traces. You can also specify a time threshold in milliseconds. The default is apdex_f, which will set the threshold to four times the apdex_t value. For more information about apdex_t and frustrating transactions, see Apdex.

recordSql
Type String
Default obfuscated

Select an SQL tracing policy. Options are off, which records nothing; obfuscated, which records an obfuscated version of the SQL; or raw, which records the SQL exactly as it is issued to the database.

Caution: Recording raw SQL may capture sensitive information.

stackTraceThreshold
Type Integer
Default 500
Unit Milliseconds

Defines the threshold for a slow query. Over this threshold the agent collects a stack trace of the calling code.

explainEnabled
Type Boolean
Default True

When true, the agent captures EXPLAIN statements for slow SQL queries..

explainThreshold
Type Integer
Default 500
Unit Milliseconds

The agent captures an explain plan for SQL queries slower than this threshold (in milliseconds).

maxSegments
Type Integer
Default 3000

The maximum number of segments to collect in a transaction trace.

maxStackTrace
Type Integer
Default 30

The maximum number of stack traces to collect during a harvest cycle.

maxExplainPlans
Type Integer
Default 20

The maximum number of explain plans to collect during a harvest cycle.

attributes

Use this sub-element to customize your agent attribute settings for transaction traces. This sub-element uses the same settings as the primary attributes element: enabled, include, and exclude.

For more help

Additional documentation resources include:

If you need additional help, get support at support.newrelic.com.