.NET agent configuration

The New Relic .NET agent gets its configuration from the newrelic.config file. It finds 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's name and a boolean flag to enable or disable the agent.

Note: Prior to July 2013, the .NET agent used the newrelic.xml file.

Multiple applications

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

Configuration

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

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

It supports the following attributes:

agentEnabled

This sets whether or not the New Relic agent is enabled.

maxStackTraceLines

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

timingPrecision

Controls the precision of the timers used for the metrics gathered, with a trade-off in execution speed. Possible values are high and low. Defaults to low.

Service

The first child of the configuration element is a service element. It configures the agent to connect to the New Relic service.

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

It supports the following attributes:

licenseKey

This is where the key from your New Relic account goes. The key is used to locate the correct account to store data into when the agent connects to New Relic.

ssl

This sets whether or not to use SSL when communicating with New Relic.

sendEnvironmentInfo

This tells the agent to send the execution environment information back to the RPM. This includes information about the O/S; which version of the agent is used; information about all of the assemblies available at the time the environment information is captured. Defaults to true.

syncStartup

If true, the agent startup will block until a connection to the New Relic service is made. Defaults to false.

sendDataOnExit

If true, the agent will block process shutdown until it has gone through a harvest cycle and sent its data to the New Relic service. Defaults to false.

sendDataOnExitThreshold

The amount of time (in milliseconds) an agent must run before sending data on process shutdown. The default is 60 seconds or 60,000 milliseconds. This only applies when sendDataOnExit is set to true.

requestTimeout

The request timeout (in milliseconds) when communicating with the New Relic service.

Proxy

The proxy element is an optional child of the service element. It is used to configure the agent to talk to the New Relic service through a proxy.

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

It supports the following attributes:

host

This sets the proxy host.

port

Optionally sets the proxy port. Defaults to 8080.

domain

Optionally sets the domain used to authenticate with the proxy server.

user

Optionally sets a user name for authentication.

password

Optionally sets a password for authentication.

Application

The application element is a child of the configuration element which configures information about your application. It supports the following attributes:

name

The name of your application is a child of the application element. This is used to create an automatic "application definition" in New Relic. For example:

    <application>
      <name>My App</name>
    </application>
  

Note: As part of the installation process, change the default application name to a meaningful name.

disableSamplers

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

Log

The log element is a child of the configuration element which configures information about the logging of the New Relic Agent. The agent generates its own log file to keep its logging information separate from that of your application.

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

It supports the following attributes:

level

Sets 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

Defaults to info. Selecting more detailed logging levels will increase New Relic's performance impact.

auditLog

If this is true, then any data that is sent to New Relic and received from New Relic will be recorded in a separate log file, in addition to going to the log file. Defaults to false.

console

If this is true, then log messages are also appended to the console, in addition to going to the log file. Defaults to false.

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

The name of the log file to write. If this is omitted, then the name is derived from the name of the monitored process.

Instrumentation

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:

Run the installer, select Change, and then enable the Instrument all .NET applications option. (OR, do a clean install with this option enabled.) Then do either of the following:

  • Add an application setting to your application's configuration that enables the agent. For example, if the application name is MyServer.exe, edit MyServer.exe.config and add a new appSetting with a key named NewRelic.AgentEnabled and a value of true.
  • OR: Add an instrumentation element, with an applications element, containing one or more application names, each set to the name of your custom server application. Multiple application elements can be specified.

Application

The application element is a child of the instrumentation element. This represents a list of application names to instrument non-web applications. It contains a name attribute. Note: This is not the same as the application 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>

Request parameters

The requestParameters element is a child of the configuration element which tells the transaction tracer and the error collector whether or not to capture HTTP parameters. To ignore specific parameters so that they are never captured, specify ignore elements.

  <requestParameters enabled="true" >
    <ignore>credit_card</ignore>
    <ignore>pwd_field</ignore>
  </requestParameters>

It supports the following attribute and element:

enabled

Turns on request parameter capturing for the Transaction Tracer and Error Collector features. Defaults to false.

ignore

An element that represents the name of a specific request parameter to not capture.

Note: enabled must be set to true to use the ignore element.

Parameter groups

A parameter group is a named collection of key/value pairs that the New Relic agent can collect and send to the collector as part of a transaction trace or error. The detailed transaction trace or error data appears on the application's dashboard, and the parameter group name is the heading.

To turn on or turn off capturing parameter data, edit the <parameterGroups> section of the .NET agent's configuration file.

Tip: To capture some but not all parameters in a group, set enabled="true" and add an <ignore> element.

<parameterGroups>
  <identityParameters enabled="false">
    <ignore>username</ignore>
  </identityParameters>
  <responseHeaderParameters enabled="true">
    <ignore></ignore>
  </responseHeaderParameters>
  <customParameters enabled="true">
    <ignore>Queue Wait Time</ignore>
    <ignore>Original Url</ignore>
  </customParameters>
</parameterGroups>

Parameter groups for .NET include:

identityParameters

The agent captures the username associated with an authenticated transaction where the ASP.NET application is using a security principal. To ignore this value, specify "username" in an <ignore> element.

responseHeaderParameters

The agent captures an HTTP status value associated with a web response (for example, 200). To ignore this value, specify "status" in an <ignore> element.

customParameters

The agent captures the Queue Wait Time and the Original Url. To ignore a custom parameter value, specify an <ignore> element.

Analytics events

The analyticsEvents element is a child of the configuration element which configures the behaviors that provide the data for displaying histograms and percentiles in the UI.

<analyticsEvents enabled="true" 
  maximumSamplesPerMinute="10000" 
  maximumSamplesStored="10000" 
  captureAttributes="true">
  <transactions enabled="true" />  
</analyticsEvents>

Analytics events for .NET include:

enabled

Turns the event recorder on or off. Defaults to true.

maximumSamplesPerMinute

The maximum number of samples to send per minute. It is possible that fewer events will be sent, but never more. Defaults to 10000.

maximumSamplesStored

The maximum number of samples to store in memory at a time. Defaults to 10000.

captureAttributes

Include User parameters in transaction analytics events. User specified parameters can be added to transactions using the agent API's AddCustomParameter (System.String,System.lConvertible), AddCustomParameter (System.String,System.String) or SetUserParameters(System.String,System.String,System.String) methods. Defaults to true.

Transaction tracer

The transactionTracer element is a child of the configuration element which configures the ability to capture deep information about slow transactions and sends this to the New Relic service once a minute. Included in the transaction 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"
    captureAttributes="true"/>

It supports the following attributes:

enabled

This sets whether transaction tracer is enabled or not. This only works for Pro and Enterprise (Volume) subscription levels. Defaults to true.

transactionThreshold

This sets the threshold (in milliseconds) for which transaction traces are collected. If unspecified, the default is 2.0 seconds. You can also specify the string apdex_f, which will set the threshold to four times the apdex_t value. This means all frustrating transactions will be recorded. For more information about the Apdex T value and frustrating transactions, see Apdex. Defaults to apdex_f.

recordSql

Chooses which SQL recording policy to use. 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. Defaults to obfuscated.

stackTraceThreshold

Sets the threshold (in milliseconds) for which slow queries collect a stack trace of the calling code. Defaults to 500.

explainEnabled

When true, this captures EXPLAIN statements for slow SQL queries. Defaults to true.

explainThreshold

SQL queries slower than this threshold (in milliseconds) have an EXPLAIN plan captured. Defaults to 500.

maxSegments

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

maxStackTrace

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

maxExplainPlans

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

captureAttributes

Include User parameters in transaction analytics events. User specified parameters can be added to transactions using the agent API's AddCustomParameter (System.String,System.lConvertible), AddCustomParameter (System.String,System.String) or SetUserParameters(System.String,System.String,System.String) methods. Defaults to true.

Cross application tracer

The crossApplicationTracer element is a child of the configuration element which adds Cross Application Transaction Trace linking so that in SOA (service-oriented architectures) all applications that are instrumented by a New Relic agent and 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. This change helps improve the correlation of performance between services and applications.

<crossApplicationTracer enabled="true"/>

It supports the following attribute:

enabled

This sets whether Cross Application Tracing is enabled or not. Defaults to true.

Slow SQL

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

<slowSql enabled="true"/>

It supports the following attribute:

enabled

This sets whether slow SQL is enabled or not. Defaults to true.

Error collector

The errorCollector element is a child of the configuration element which configures the ability to capture information about uncaught exceptions and sends them to the New Relic service for viewing.

<errorCollector enabled="true" captureAttributes="true">
  <ignoreErrors>
    <exception>System.IO.FileNotFoundException</exception>
    <exception>System.Threading.ThreadAbortException</exception>
  </ignoreErrors>
  <ignoreStatusCodes>
    <code>401</code>
    <code>404</code>
  </ignoreStatusCodes>
</errorCollector>

It supports the following elements and attribute:

enabled

This sets whether the error collector is enabled or not. Defaults to true.

captureAttributes

Include User parameters in transaction analytics events. User specified parameters can be added to transactions using the agent API's AddCustomParameter (System.String,System.lConvertible), AddCustomParameter (System.String,System.String) or SetUserParameters(System.String,System.String,System.String) methods. Defaults to true.

ignoreErrors

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

ignoreStatusCodes

Represents a list of 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.

Browser monitoring

The browserMonitoring element is a child of the configuration element which configures how page load timing (sometimes referred to as real user monitoring or RUM) works in your applications. Page load timing gives you insight into the performance that end users are experiencing with your website. 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"/>

It supports the following attribute:

autoInstrument

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.

Include/Exclude application pools

The applicationPools element is a child of the configuration element. It helps the profiler explicitly determine which application pools should or should not be instrumented. This configuration element helps in situations where defining instrumentation behaviors is needed. For example, A given server has 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>

It supports the following elements:

defaultBehavior

Represents the element that defines how the .NET agent will behave on a "global" level for application pools being served via IIS. The instrument attribute defaults to true which means that the .NET agent should instrument all application pools by default and any application pools that were listed with an instrument attribute set to false would have instrumentation disabled. This attribute and the container element defaultBehavior are not a required parts of the XML in the config.

applicationPool

Represents the element that is used to explicitly define instrumentation behavior for a given application pool. The name attribute is the name of an application pool. The instrument attribute is used to either enable or disable profiling of a given application whose application pool name is defined in the name attribute.

For more help

Additional documentation resources include:

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