Name your .NET application

New Relic collects information by license key and then by the primary application identifier or app name. New Relic aggregates metrics using these names, which allows you to run the same application on multiple hosts and have combined metrics from all instances. This document explains the various methods to name .NET applications.

After changing your .NET app's configuration file (newrelic.config or app.config), always perform an IISRESET from an administrative command prompt. Exception: Adjusting log levels in newrelic.config does not require an IISRESET.

Change default name

When you first deploy your app, change the default name to a descriptive name. You can also aggregate metrics by using multiple names. If a different APM agent already uses the same app name, the .NET app will report with (DOTNET) appended to the end of the name.

Use the .NET agent API

You can use the SetApplicationName() agent API call to set the application name at run time. This name will take priority over all other application name sources.

Each call to SetApplicationName will override the previous call. Application names set by using the .NET agent API will not be persisted between application restarts.

Use an environment variable

If you are using .NET agent version 6.17.387.0 or higher, you can use the environment variable NEW_RELIC_APP_NAME to set the application name. This name will take priority over an app's local newrelic.config. However, this name will not take priority over the web.config, the app config file for non-IIS apps, or the SetApplicationName API call.

Name IIS-hosted apps

You can name an IIS-hosted application by using either of these options:

  • web.config: Naming with web.config ensures each of your applications has a descriptive name. This also ensures that your metric data does not get aggregated improperly across multiple apps.
  • newrelic.config: If you do not want to alter web.config, you can also name your app by using its local newrelic.config.

Name app using web.config

Naming your app using web.config ensures each of your unique applications has a descriptive name. This name will take priority over all application name sources except the SetApplicationName() API call.

  1. Add the following entry to your web.config file:

    <appSettings>
        <add key = "NewRelic.AppName" value="Primary Name" />
    </appSettings>
  2. Optional: To give your app multiple names (up to three), specify each name individually with <name>. Assign the first name as the primary name.

    <appSettings>
        <add key="NewRelic.AppName" value="My First Application, My Second Application, My Third Application"/>
    </appSettings>
  3. Reset IIS.

As long as your app is receiving traffic, data should appear within a few minutes. If not, follow the troubleshooting procedures.

Name app using newrelic.config

If you do not want to edit web.config (or your app config file for non-IIS apps), you can copy newrelic.config into your app's root folder and edit the name there. Copying newrelic.config will override the global file.

  1. Copy newrelic.config from the agent home directory into your app's root folder as applicable:

    • Default: %ALLUSERSPROFILE%\New Relic\.NET Agent
    • Windows 2003: %ALLUSERSPROFILE%\Application Data\New Relic\.NET Agent
  2. Open the copy of newrelic.config. Specify a new name for your application in the <name> element:

    <application>
       <name> App Name </name>
    </application>
  3. Optional: To give your app multiple names (up to three), specify each name individually with <name>. Assign the first name as the primary name.

    <application>
        <name>My Application</name>
        <name>Second App Name</name>
        <name>Third App Name</name>
    </application>
  4. Reset IIS.

As long as your app is receiving traffic, data should appear within a few minutes. If not, follow the troubleshooting procedures.

Name after app pools

To name your app according to its parent app pool:

  1. Remove all explicit naming from newrelic.config and web.config.
  2. Ensure each app has a descriptive name by following the procedures in the SNCI naming instructions.
  3. In the newrelic.config, leave the <application></application> parent element. Only remove the child <name> </name>:

    <application>
    </application>
  4. Restart your application.

Name non-IIS apps

You can name your non-IIS hosted application in its app config file or in the app's local newrelic.config file. To set a name in the app config file:

  1. Add the following entry to your app config file (for example, applicationname.exe.config):

    <appSettings>
        <add key = "NewRelic.AppName" value="Descriptive Name" />
    </appSettings>
  2. Optional: To give your app multiple names (up to three), specify each name individually with <name>. Assign the first name as the primary name.

    <appSettings>
        <add key="NewRelic.AppName" value="My First Application, My Second Application, My Third Application"/>
    </appSettings>
  3. Restart your application.

As long as your app is active, data should appear within a few minutes. If not, follow the troubleshooting procedures.

Name using external appSettings file

If you normally specify configuration options for your app in an external file, you can call that external file to set your app's name:

  1. Verify that web.config or app.config is calling an external file.
  2. Add the follow entry to your appSettings file:

    <appSettings>
        <add key = "NewRelic.AppName" value="Descriptive Name" />
    </appSettings>
  3. Optional: To give your app multiple names (up to three), specify each name individually with <name>. Assign the first name as the primary name.

    <appSettings>
        <add key="NewRelic.AppName" value="My First Application, My Second Application, My Third Application"/>
    </appSettings>
  4. Reset IIS.

As long as your app is receiving traffic, data should appear within a few minutes. If not, follow the troubleshooting procedures.

Use SNCI

If you are building a "web farm" by using a shared network content infrastructure (SCNI), each of your apps will report to a single name by default. This is because SNCI uses only one web.config file.

In SNCI environments, preloading app pools will restrict New Relic's ability to capture the application name. Be sure to disable preloading app pools if using SNCI.

To ensure each unique application has a descriptive name:

  1. Split each application into its own app pool, and assign each app pool a descriptive name.
  2. Remove all naming from web.config (if any) by removing all NewRelic.AppName keys from appSettings:

    <appSettings>
    </appSettings>
  3. Remove all naming from newrelic.config (if any) by removing all <name> elements from the <application> element. Ensure you do not delete the surrounding <application></application> tags.

    <application>
    </application>

Each app will then report according to its app pool name.

For more help

Recommendations for learning more: