This document contains the configuration options for the APM .NET agent.
Configuration overview
APM agent configuration options allow you to control some aspects of how the agent behaves. Some of these config options are part of the basic install process (like setting your license key and app name), but most are more advanced settings, such as: setting a log level, setting up proxy host access, excluding certain attributes, and enabling distributed tracing.
The .NET agent gets its configuration from the newrelic.config
file, which is generated as part of the install process. By default, only a global newrelic.config
file is created, but you can also create app-local newrelic.config
files for finer control over a multi-app system. Other ways to set config options include: using environment variables, or setting server-side configuration from the UI. For more on the various config options and what overrides what, see Config settings precedence.
Support for both .NET Framework and .NET Core use the same configuration options and have the same APM features, unless otherwise stated.
If you make changes to the config file and want to validate that it's in the right format, you can check it against the XSD file (for example, at C:\ProgramData\New Relic\.NET Agent\newrelic.xsd
for Windows) with any XSD validator.
For IIS: after you change your newrelic.config
or app.config
file, perform an IISRESET
from an administrative command prompt. Log level adjustments do not require a reset.
Configuration methods and precedence levels
Upon installation, the .NET agent's configuration file (newrelic.config
) applies to all monitored applications, but you can configure the agent in other ways. Here's a diagram showing how different configuration options take precedence over one another:

Here are details about the configuration methods shown in the diagram, and their precedence levels:
.NET configuration | Details and precedence |
---|---|
web.config or app.config or appsettings.json |
Configuration settings set in these files take highest precedence. However, if the agent is disabled in the local or global |
Environment variables |
Second-highest precedence. For more about these, see .NET environment variables. |
Server-side configuration |
Third-highest precedence. A limited number of server-side configuration settings are available; the other settings will come from other configuration sources. |
App-local |
Fourth-highest precedence. You can create app-local The agent looks for app-local config files in the following directories, in this order:
Note that the app-local config file must be complete and validate against the XSD file (for example, at |
Default (global) newrelic.config |
Default source and the lowest precedence. Will configure all applications on a host in the absence of other config files. The global config file is located in the New Relic agent home directory: |
Required environment variables
New Relic's .NET agent relies on environment variables to tell the .NET Common Language Runtime (CLR) to attach New Relic to your processes. Some .NET agent install procedures (like the MSI installer) will automatically set these variables for you; some procedures will require you to manually set them.
Security recommendation: You should consider what users can set system environment variables. You should also secure the accounts under which your applications execute to prevent user environment variables overriding system environment variables
- .NET Framework environment variables
-
For .NET Framework, the following variables are required:
COR_ENABLE_PROFILING=1 COR_PROFILER={71DA0A04-7777-4EC6-9643-7D28B46A8A41} NEWRELIC_INSTALL_PATH=path\to\agent\directory
The .NET agent installer will add these to IIS or as system-wide environment variables.
- .NET Core environment variables
-
For .NET Core, the following variables are required:
Linux:
CORECLR_ENABLE_PROFILING=1 CORECLR_PROFILER={36032161-FFC0-4B61-B559-F6C5D41BAE5A} CORECLR_NEWRELIC_HOME=path/to/agent/directory CORECLR_PROFILER_PATH="${CORECLR_NEWRELIC_HOME}/libNewRelicProfiler.so"
Windows:
CORECLR_ENABLE_PROFILING=1 CORECLR_PROFILER={36032161-FFC0-4B61-B559-F6C5D41BAE5A} NEWRELIC_INSTALL_PATH=path\to\agent\directory CORECLR_NEWRELIC_HOME=path\to\agent\directory
The .NET agent installer will add these to IIS or as system-wide environment variables.
If your system has previously used monitoring services (non-New Relic), you may have a "profiler conflict" when trying to install and use the New Relic agent. More details:
- Profiler conflict explanation
-
New Relic’s .NET agents rely on environment variables to tell the .NET Common Language Runtime (CLR) to load New Relic into your processes. The install-related environment variables are Microsoft variables, not New Relic variables. They can be used by other .NET profilers, and only one profiler can be attached to a process at a time. For this reason, if you have used previous application monitoring products, you may have profiler conflicts.
For specific install instructions, see the .NET agent install documentation.
Setup options
Use these options to setup and configure your agent. The New Relic .NET agent supports the following categories of setup options:
- Multiple applications
- Configuration element
- Service element
- Obscuring key element
- Proxy element
- Log element
- Application element (configuration)
- Data transmission element
- Host name
Configuration element
The root element of the configuration document is a configuration
element.
<configuration xmlns="urn:newrelic-config" agentEnabled="true" maxStackTraceLines="50" timingPrecision="low">
The configuration
element 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
andlow
.
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="YOUR_LICENSE_KEY" sendEnvironmentInfo="true" syncStartup="false" sendDataOnExit="false" sendDataOnExitThreshold="60000" autoStart="true"/>
The service
element supports the following attributes:
- licenseKey (required)
-
Type String Default (none) Your New Relic license key. New Relic uses the license key to match your app's data to the correct account in the UI. Set the license key via environment variable.
Optionally set the
NEW_RELIC_LICENSE_KEY
environment variable in the application's environment.NEW_RELIC_LICENSE_KEY=XXXXXXXX
- 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
istrue
. - completeTransactionsOnThread
-
Type Boolean Default false
If false, the agent uses a pool thread to complete the transaction processing.
If true, the agent will complete transaction processing on the request thread.
- requestTimeout
-
Type Integer Default 2000
(sendDataOnExit
enabled)120000
(sendDataOnExit
disabled)Unit Milliseconds The agent's request timeout when communicating with New Relic.
- autoStart
-
Type Boolean Default True
Automatically start the .NET agent when the first instrumented method is hit.
- ssl (DEPRECATED)
-
Type Boolean Default true
The option to disable SSL is valid only for .NET agent versions 7.x and earlier. .NET agent version 8.x and higher communicate only via SSL.
The agent communicates with New Relic via HTTPS by default, and New Relic requires HTTPS for all traffic to APM and the New Relic REST API.
Obscuring key element
The obscuringKey
element is an optional child of the service
element. The .NET Agent uses this value to deobfuscate supported configuration values. For example, when an obfuscated proxy password is supplied, it will be deobfuscated using this key.
<service licenseKey="YOUR_LICENSE_KEY"> <obscuringKey>OBSCURING_KEY</obscuringKey> </service>
The obscuring key may also be configured by setting the NEW_RELIC_CONFIG_OBSCURING_KEY
environment variable.
Security recommendation: The placement of the obscuring Key in the same configuration file as an obfuscated value may pose a security risk. Consider placing the obscuring key in an environment variable and limiting access to environment variables within your environment.
Proxy element
The proxy
element is an optional child of the service
element. The proxy
element is used when the agent communicates to the New Relic back-end service via a proxy.
<service licenseKey="YOUR_LICENSE_KEY"> <proxy host="hostname" port="PROXY_PORT" uriPath="path/to/something.aspx" domain="mydomain.com" user="PROXY_USERNAME" password="PROXY_PASSWORD" passwordObfuscated="OBFUSCATED_PROXY_PASSWORD"/> </service>
The proxy
element supports the following attributes:
- host
-
Type String Default (none) Defines the proxy host.
- port
-
Type Integer Default 8080
Defines the proxy port.
- uriPath
-
Type String Default (none) Optionally define a proxy URI path.
- 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.
- passwordObfuscated
-
Type String Default (none) For additional security, the .NET Agent supports the use of an obfuscated proxy password with the passwordObfuscated attribute. The obfuscated proxy password is generated using the following New Relic CLI command:
newrelic agent config obfuscate --key OBSCURING_KEY --value "CLEAR_TEXT_PROXY_PASSWORD"
When using an obfuscated proxy password, the obscuring key must also be configured.
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="false" console="false" directory="PATH\TO\LOG\DIRECTORY" fileName="FILENAME.log" />
The log
element 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
error
warn
info
debug
finest
all
Increasing the log 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
-
Type String Default C:\ProgramData\New Relic\.NET Agent\Logs
The directory to hold log files generated by the agent. If this is omitted, then a directory named logs in the New Relic agent install 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.Optionally set the
NEW_RELIC_LOG
environment variable in the application's environment.NEW_RELIC_LOG=MyApp.log
Application element (required)
The application
element is a child of the configuration
element. This required element defines your application name, and disables or enables sampling.
- name
-
Type String Default My Application
The name of your .NET 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 namedAppA
andAppB
, you will see two applications in the New Relic interface:AppA
andAppB
.You can also assign up to three names to your app. The first name is the primary name. For example:
<application> <name>MY APPLICATION PRIMARY</name> <name>SECOND APP NAME</name> <name>THIRD APP NAME</name> </application>
Optionally set the
NEW_RELIC_APP_NAME
environment variable in the application's environment.NEW_RELIC_APP_NAME=Descriptive Name
- disableSamplers
-
Type Boolean Default false
Samplers collect information about memory and CPU consumption. Set this to
true
to disable sampling.
Data transmission element
The dataTransmission
element is a child of the configuration
element. This element affects how data is sent to New Relic and can be used if you have specific data transmission requirements.
<dataTransmission putForDataSend="false" compressedContentEncoding="deflate"/>
The dataTransmission
element supports the following attributes:
- putForDataSend
-
Type Boolean Default false
Defines the HTTP method used when sending data to New Relic. Set this to
true
to enable using thePUT
method when sending data. ThePOST
method is used by default.
Host name
If the default host name label in the APM UI is not useful, you can decorate that name in the New Relic UI with a display name. After the application process is restarted and the .NET agent is reporting again, the display name will appear in the Servers drop-down list. This host name setting does not affect the list of hosts on your application's Summary page.
To set a display name, choose one of the following options. The environment variable takes precedence over the config file value. Then restart your application to see your changes in the New Relic UI.
- Set using config file
-
Set the
displayName
attribute in theprocessHost
element innewrelic.config
. TheprocessHost
element is a child of theconfiguration
element.<configuration . . . > <processHost displayName="CUSTOM_NAME" /> </configuration>
- Set using environment variable
-
Set the
NEW_RELIC_PROCESS_HOST_DISPLAY_NAME
environment variable:NEW_RELIC_PROCESS_HOST_DISPLAY_NAME
= "CUSTOM_NAME"
Cloud platform utilization
Configures the utilization
configuration element to control how the agent collects utilization information and sends it to the New Relic service to determine pricing. The agent can collect information from Amazon Web Services (AWS) EC2 instances, Docker containers, Azure, Google Cloud Platform, Pivotal Cloud Foundry, and Kubernetes.
- detectAws
-
Type Boolean Default true
Determines whether the agent polls AWS metadata API.
- detectAzure
-
Type Boolean Default true
Determines whether the agent polls Azure metadata API.
- detectGcp
-
Type Boolean Default true
Determines whether the agent polls GCP metadata API.
- detectPcf
-
Type Boolean Default true
Determines whether the agent polls PCF information from environment variables.
- detectDocker
-
Type Boolean Default true
Determines whether the agent reads Docker information from the file system.
- detectKubernetes
-
Type Boolean Default true
Determines whether the agent polls Kubernetes information from environment variables.
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.
This is not the same as the application
(configuration) element, which is a child of the configuration
element.
<instrumentation> <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, Transaction events, TransactionError events, or 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, Browser instrumentation, 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 view the .NET APM attributes on the .NET agent attributes page. You can also define custom attributes with the agent API call AddCustomParameter
.
- 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
- Cross application traces
- Error collection
- High security mode
- Strip exception messages
- Transaction events
- Custom events
- Custom parameters
- Tags/labels
- Browser instrumentation
- Slow Queries
- Transaction traces
- Datastore tracer
- Distributed tracing
- Span events
App pools
This is only applicable to a system's global config file.
The applicationPools
element is a child of the configuration
element. The applicationPools
element specifies for the profiler exactly which application pools to instrument and uses the same name as the IIS application pool name. 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
element 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 aninstrument
attribute set to false will not be instrumented.Essentially, when set to
false
, the application pool list acts as an allow list. When set totrue
, the application pool list acts as a deny list. - applicationPool
-
Defines instrumentation behavior for a specific application pool. The
name
attribute is the name of an application pool. Enable or disable profiling in theinstrument
attribute. Define this application in thename
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
element 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" captureEvents="true" maxEventSamplesStored="100"> <ignoreClasses> <errorClass>System.IO.FileNotFoundException</errorClass> <errorClass>System.Threading.ThreadAbortException</errorClass> </ignoreClasses> <ignoreMessages> <errorClass name="System.Exception"> <message>Ignore message</message> <message>Ignore too</message> </errorClass> </ignoreMessages> <ignoreStatusCodes> <code>401</code> <code>404</code> </ignoreStatusCodes> <expectedClasses> <errorClass>System.ArgumentNullException</errorClass> <errorClass>System.ArgumentOutOfRangeException</errorClass> </expectedClasses> <expectedMessages> <errorClass name="System.Exception"> <message>Expected message</message> <message>Expected too</message> </errorClass> </expectedMessages> <expectedStatusCodes>403,500-505</expectedStatusCodes> <attributes enabled="true"> <exclude>myApiKey.*</exclude> <include>myApiKey.foo</include> </attributes> </errorCollector>
For an overview of error configuration in APM, see Manage errors in APM.
The errorCollector
element supports the following elements and attributes:
- enabled
-
Type Boolean Default true
Enable or disable the error collector.
- captureEvents
-
Type Boolean Default true
Enable or disable the capturing of error events.
- maxEventSamplesStored
-
Type Integer Default 100
Reservoir limit for error events.
- ignoreClasses
-
A list of fully qualified class names to be ignored. The maximum number of error class and message combinations that SHOULD be reported is 50. If more than 50 are listed, then only the first 50 SHOULD be used
- ignoreMessages
-
An optional map of fully qualified class names to list of strings matching a substring of the message of an error. The maximum number of error class and message combinations that SHOULD be reported is 50. If more than 50 are listed, then only the first 50 SHOULD be used
- ignoreErrors (DEPRECATED)
-
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.
- expectedClasses
-
A list of fully qualified class names to be marked as expected. The maximum number of error class and message combinations that SHOULD be reported is 50. If more than 50 are listed, then only the first 50 SHOULD be used
- expectedMessages
-
An optional map of fully qualified class names to list of strings matching a substring of the message of an error. The maximum number of error class and message combinations that SHOULD be reported is 50. If more than 50 are listed, then only the first 50 SHOULD be used
- expectedStatusCodes
-
A comma separated list of status codes. The list may include integer ranges, using a single dash (-) and will be inclusive of both the starting and ending integer in the range.
- 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
, andexclude
.
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 parameters and custom parameters are not collected, strip exception messages is enabled, and queries cannot be sent to New Relic in their raw form.
- enabled
-
Type Boolean Default false
Enable or disable high security mode. Example:
<highSecurity enabled="true"/>
Strip exception messages
The stripExceptionMessages
element is a child of the configuration
element. To enable strip exception messages, set this property to true
. By default, this is set to false, which means that the agent sends messages from all exceptions to the New Relic collector. If you enable high security mode, this is automatically changed to true, and the agent strips the messages from exceptions.
- enabled
-
Type Boolean Default false
Enable or disable strip exception messages. Example:
<stripExceptionMessages enabled="true"/>
Transaction events
The transactionEvents
element is a child of the configuration
element. Use transactionEvents
to configure transaction events.
<transactionEvents enabled="true" maximumSamplesStored="10000"> <attributes enabled="true"> <exclude>myApiKey.*</exclude> <include>myApiKey.foo</include> </attributes> </transactionEvents>
The transactionEvents
element supports the following attributes:
- enabled
-
Type Boolean Default true
Enable or disable the event recorder.
- maximumSamplesStored
-
Type Integer Default 10000
The maximum number of samples to store in memory at once.
Optionally set the
MAX_TRANSACTION_SAMPLES_STORED
environment variable in the application's environment.MAX_TRANSACTION_SAMPLES_STORED=500
- 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
, andexclude
.These attribute settings are specific to
transaction
events. Attribute settings can be applied globally to all event types to with this configuration setting.When distributed tracing and/or Infinite Tracing are enabled, information from transaction events is applied to the root Span Event of the transaction. Consider applying any attribute settings for transaction events to span events and/or apply them as Global Attribute settings.
Custom events
The customEvents
element is a child of the configuration
element. Use customEvents
to configure custom events.
<customEvents enabled="true" maximumSamplesStored="10000"/>
The CustomEvents
element supports the following attributes:
- enabled
-
Type Boolean Default true
Enable or disable the event recorder.
- maximumSamplesStored
-
Type Integer Default 10000
The maximum number of samples to store in memory at once.
Optionally set the
MAX_EVENT_SAMPLES_STORED
environment variable in the application's environment.MAX_EVENT_SAMPLES_STORED=500
Custom parameters
The customParameters
element is a child of the configuration
element. Use customParameters
to configure custom parameters.
<customParameters enabled="true" />
The CustomParameters
element supports the following attributes:
- enabled
-
Type Boolean Default true
Enable or disable the capture of custom parameters.
Labels (tags)
The labels
element is a child of the configuration
element.
This sets tag names and values. The list is a semicolon delimited list of colon-separated name and value pairs. You can also use with the NEW_RELIC_LABELS
environment variable. Example:
<labels>foo:bar;zip:zap</labels>
Browser instrumentation
The browserMonitoring
element is a child of the configuration
element. browserMonitoring
configures Browser monitoring in your .NET application. Browser 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.
// If you use both the Exclude and Attribute elements // the Exclude element must be listed first. <browserMonitoring autoInstrument="true"> <requestPathsExcluded> <path regex="url-regex-1"/> <path regex="url-regex-2"/> ... <path regex="url-regex-n"/> </requestPathsExcluded> <attributes enabled="true"> <exclude>myApiKey.*</exclude> <include>myApiKey.foo</include> </attributes> </browserMonitoring>
The browserMonitoring
element supports the following attributes:
- autoInstrument
-
Type Boolean Default true
By default the agent automatically injects the Browser agent JavaScript. To turn off automatic injection, set this attribute to
false
. - attributes
-
Use this sub-element to customize your agent attribute settings for Browser. This sub-element uses the same settings as the primary
attributes
element:enabled
,include
, andexclude
. - requestPathsExcluded
-
Use this sub-element to prevent the Browser agent from being injected in specific pages. The element is used as follows:
<requestPathsExcluded> <path regex="url-regex-1"/> <path regex="url-regex-2"/> ... <path regex="url-regex-n"/> </requestPathsExcluded>
The agent will not inject the Browser agent into pages whose URL matches one of the specified regular expressions. The regular expression should follow Microsoft guidelines for the Regex class.
It is a reference to the virtual directory of the path in your application and not the full URL of the path you wish to exclude. For example, to exclude the pages in
https://www.mywebsite.com/mywebpages/
you would simply insert/mywebpages/
as the path regex value.The
requestPathsExcluded
element should be used in cases where it is impossible or undesirable to use theDisableBrowserMonitoring()
call. To minimize a possible performance impact try to use as few regular expressions as possible and keep them as simple as possible.
Slow queries
The slowSql
element is a child of the configuration
element. slowSql
configures capturing information about slow query executions, and captures and obfuscates explain plans for these queries.
<slowSql enabled="true"/>
The slowSql
element supports the following attribute:
- enabled
-
Type Boolean Default true
Enable or disable slow query tracing.
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 query statements issued.
<transactionTracer enabled="true" transactionThreshold="apdex_f" recordSql="obfuscated" explainEnabled="true" explainThreshold="500" maxSegments="3000" maxExplainPlans="20"> <attributes enabled="true"> <exclude>myApiKey.*</exclude> <include>myApiKey.foo</include> </attributes> </transactionTracer>
The transactionTracer
element supports the following attributes:
- enabled
-
Type Boolean Default true
Enable or disable transaction traces.
- transactionThreshold
-
Type String Default apdex_f
Defines the threshold for transaction traces. If a transaction takes longer than the threshold, it is eligible for being traced. See transaction trace basics for more about the rules governing traces.
The default value is
apdex_f
, which sets the threshold to four times the application's apdex_t value. For more information about apdex_t, see Apdex.You can also set the threshold to be a specific time value in milliseconds.
- recordSql
-
Type String Default obfuscated
Select a query tracing policy. Options are
off
, which records nothing;obfuscated
, which records an obfuscated version of the query; orraw
, which records the query exactly as it is issued to the database.Recording raw queries may capture sensitive information.
- explainEnabled
-
Type Boolean Default false
When
true
, the agent capturesEXPLAIN
statements for slow queries. - explainThreshold
-
Type Integer Default 500
Unit Milliseconds The agent collects slow query data for queries that exceed this threshold, along with any available explain plans, as part of transaction traces.
- maxSegments
-
Type Integer Default 3000
The maximum number of segments to collect in a transaction trace.
- 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
, andexclude
.
Datastore tracer
The datastoreTracer
element is a child of the configuration
element.
<datastoreTracer> <instanceReporting enabled="true" /> <databaseNameReporting enabled="true" /> <queryParameters enabled="false" /> </datastoreTracer>
The datastoreTracer
element supports the following sub-elements:
- instanceReporting
-
Use this sub-element to enable collection of datastore instance metrics (such as the host and port) for some database drivers. These are reported on slow query traces and transaction traces. The default value of attribute
enabled
istrue
. - databaseNameReporting
-
Use this sub-element to enable collection of the database name on slow query traces and transaction traces for some database drivers. The default value of attribute
enabled
istrue
. - queryParameters
-
Use this sub-element to enable collection of the SQL query parameters on slow query traces. The default value of attribute
enabled
isfalse
.- Recording query parameters may capture sensitive information.
- The
transactionTracer.recordSql
configuration option must be set toraw
or this option is ignored.
Distributed tracing
The distributedTracing
element is a child of the configuration
element.
<distributedTracing enabled="false" excludeNewrelicHeader="false"/>
Distributed tracing lets you see the path that a request takes as it travels through a distributed system. Enabling distributed tracing disables cross application tracing, and has other effects on APM features. Before enabling, read the planning guide.
Requires .NET agent version 8.6.45.0 or higher.
The distributedTracing
element supports the following attributes:
To enable or disable, see Enable distributed tracing.
- enabled
-
Type Boolean Default false
- Enable distributed tracing via environment variable
-
Optionally enable distributed tracing via the
NEW_RELIC_DISTRIBUTED_TRACING_ENABLED
environment variable in the application's environment.NEW_RELIC_DISTRIBUTED_TRACING_ENABLED=true
- excludeNewrelicHeader
-
Type Boolean Default false
By default, supported versions of the agent utilize both the
newrelic
header and W3C Trace Context headers for distributed tracing. Thenewrelic
distributed tracing header allows interoperability with older agents that don't support W3C Trace Context headers. Agent versions that support W3C Trace Context headers will prioritize them overnewrelic
headers for distributed tracing.If you do not want to utilize the
newrelic
header, setting this totrue
will result in the agent excluding thenewrelic
header and only using W3C Trace Context headers for distributed tracing.
Distributed tracing reports span events. Span event reporting is enabled by default, but distributed tracing must be enabled for spans to be reported. To disable span events, choose one of the following options:
- Disable span events via config file
-
Set the
<spanEvents>
element tofalse
to disable via the newrelic.config file. This element is a child of the<configuration>
element.<configuration . . . > <spanEvents enabled="false" /> </configuration>
- Disable span events via environment variable
-
Set the
NEW_RELIC_SPAN_EVENTS_ENABLED
environment variable in the application's environment.NEW_RELIC_SPAN_EVENTS_ENABLED=false
Infinite Tracing
Infinite Tracing extends the distributed tracing service by employing a trace observer that is external to the agent. It observes 100% of your application traces across various services and provides actionable data so you can solve issues faster.
Infinite Tracing requires .NET Agent version 8.30 or higher.
To turn on Infinite Tracing, enable distributed tracing and add the additional settings below
<configuration . . . > <distributedTracing enabled="true" /> <infiniteTracing> <trace_observer host="YOUR_TRACE_OBSERVER_HOST" /> </infiniteTracing> </configuration>
The infiniteTracing
element supports the following elements:
- trace_observer
-
The
trace_observer
element identifies an observer host that is independent from the agent. For help getting a valid Infinite Tracing trace observer host entry, see Find or create a trace observer endpoint.The trace observer may be configured using the
NEW_RELIC_INFINITE_TRACING_TRACE_OBSERVER_HOST
environment variable as well.When configuring the trace observer, you should not supply the protocol as part of the host. For example, use
myhost.infinitetracing.com
instead ofhttps://myhost.infinitetracing.com
.
Span events
The spanEvents
element is a child of the configuration
element. Use spanEvents
to configure span events.
<spanEvents enabled="true"> <attributes enabled="true"> <exclude>myApiKey.*</exclude> <include>myApiKey.foo</include> </attributes> </spanEvents>
The spanEvents
element supports the following attributes:
- enabled
-
Type Boolean Default true
Enable or disable the event recorder.
- attributes
-
Use this sub-element to customize your agent attribute settings for span events. This sub-element uses the same settings as the primary
attributes
element:enabled
,include
, andexclude
.These attribute settings are specific to span events. Attribute settings may be applied globally to all event types to with this configuration setting.
Settings in app.config or web.config
For ASP.NET and .NET Framework console apps you can also configure the following settings in your app's app.config
or web.config
, within the outermost element, <configuration>
:
- Enable and disable the agent
-
<appSettings> <add key = "NewRelic.AgentEnabled" value="false" /> </appSettings>
If the agent is disabled in the local or global
newrelic.config
, theNewRelic.AgentEnabled
settings in these files will be ignored. - Application name
-
For more information, see Name your .NET application.
<appSettings> <add key = "NewRelic.AppName" value ="Descriptive Name" /> </appSettings>
- License key
-
<appSettings> <add key = "NewRelic.LicenseKey" value ="XXXXXXXX" /> </appSettings>
- Change newrelic.config location
-
Designates an alternative location for the config file outside of the local root of the app or global config location. The location entered must be an absolute path.
<appSettings> <add key = "NewRelic.ConfigFile" value="C:\Path-to-alternate-config-dir\newrelic.config" /> </appSettings>
Settings in appsettings.json
For .NET Core apps, you can configure the following settings in appsettings.json
if the following is true:
- The
appsettings.json
file must be located in the current working directory of the application. - The application must have the following dependencies:
- Enable and disable the agent
-
{ "NewRelic.AgentEnabled":"false" }
If the agent is disabled in the local or global
newrelic.config
, theNewRelic.AgentEnabled
setting in this file will be ignored. - Application name
-
For more information, see Name your .NET application.
{ "NewRelic.AppName": "Descriptive Name" }
- License key
-
{ "NewRelic.LicenseKey": "XXXXXXXX" }
- Change newrelic.config location
-
Designates an alternative location for the config file outside of the local root of the app or global config location. The location entered must be an absolute path.
{ "NewRelic.ConfigFile": "C:\\Path-to-alternate-config-dir\\newrelic.config" }