This document contains the configuration options for the APM .NET agent.
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
app.config file, perform an
IISRESET from an administrative command prompt. Log level adjustments do not require a reset.
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:
This diagram explains the order of precedence for different ways you might configure the .NET agent.
Here are details about the configuration methods shown in the diagram, and their precedence levels:
Details and precedence
Configuration settings set in these files take highest precedence.
However, if the agent is disabled in the local or global
Second-highest precedence. For more about these, see .NET environment variables.
Third-highest precedence. A limited number of server-side configuration settings are available; the other settings will come from other configuration sources.
Fourth-highest precedence. You can create app-local
The agent looks for app-local config files in the following directories, in this order:
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:
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
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:
For specific install instructions, see the .NET agent install documentation.
Some configuration options in New Relic's .NET agent can be set via environment variables as an alternative to setting them in a config file. Below is a list of environment variables recognized by the .NET agent with example values.
NEW_RELIC_LICENSE_KEY=XXXXXXXX NEW_RELIC_LOG=MyApp.log NEW_RELIC_APP_NAME=Descriptive Name MAX_TRANSACTION_SAMPLES_STORED=500 MAX_EVENT_SAMPLES_STORED=500 NEW_RELIC_DISTRIBUTED_TRACING_ENABLED=true NEW_RELIC_SPAN_EVENTS_ENABLED=false NEW_RELIC_LABELS=foo:bar;zip:zap NEW_RELIC_CONFIG_OBSCURING_KEY=XXXXXXXX NEW_RELIC_DISABLE_SAMPLERS=true NEWRELIC_PROFILER_LOG_DIRECTORY=path\to\agent\directory (not configurable via config file)
Use these options to setup and configure your agent via the newrelic.config file. The New Relic .NET agent supports the following categories of setup options:
- Configuration element
- Service element
- Obscuring key element
- Proxy element
- Log element
- Application element (configuration)
- Data transmission element
- Host name
The root element of the configuration document is a
configuration element supports the following attributes:
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"/>
service element supports the following attributes:
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 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>
proxy element supports the following attributes:
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" />
log element supports the following attributes:
application element is a child of the
configuration element. This required element defines your application name, and disables or enables sampling.
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 element supports the following attributes:
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.
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.
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 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 is a child of the
instrumentation element. The applications element specifies which non-web apps to instrument. It contains a
<instrumentation> <applications> <application name="MyService1.exe" /> <application name="MyService2.exe" /> <application name="MyService3.exe" /> </applications> </instrumentation>
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>
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
- Browser instrumentation
- Slow Queries
- Transaction traces
- Datastore tracer
- Distributed tracing
- Span events
This is only applicable to a system's global config file.
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>
applicationPools element supports the following elements:
crossApplicationTracer element is a child of the
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 element supports the following attribute:
errorCollector element is a child of the
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.
errorCollector element supports the following elements and attributes:
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.
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.
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>
transactionEvents element supports the following attributes:
customEvents element is a child of the
configuration element. Use
customEvents to configure custom events.
<customEvents enabled="true" maximumSamplesStored="10000"/>
CustomEvents element supports the following attributes:
customParameters element is a child of the
configuration element. Use
customParameters to configure custom parameters.
<customParameters enabled="true" />
CustomParameters element supports the following attributes:
labels element is a child of the
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:
browserMonitoring element is a child of the
// 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>
browserMonitoring element supports the following attributes:
slowSql element is a child of the
slowSql configures capturing information about slow query executions, and captures and obfuscates explain plans for these queries.
slowSql element supports the following attribute:
transactionTracer element is a child of the
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>
transactionTracer element supports the following attributes:
datastoreTracer element is a child of the
<datastoreTracer><instanceReporting enabled="true" /><databaseNameReporting enabled="true" /><queryParameters enabled="false" /></datastoreTracer>
datastoreTracer element supports the following sub-elements:
distributedTracing element is a child of the
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 220.127.116.11 or higher.
distributedTracing element supports the following attributes:
To enable or disable, see Enable 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:
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>
infiniteTracing element supports the following elements:
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>
spanEvents element supports the following attributes:
For ASP.NET and .NET Framework console apps you can also configure the following settings in your app's
web.config, within the outermost element,
For .NET Core apps, you can configure the following settings in
appsettings.json if the following is true:
appsettings.jsonfile must be located in the current working directory of the application.
- The application must have the following dependencies: