New Relic connects metrics to individual applications using your license key and the primary application name. You can change the app's name in your config file, or assign an alias to the app to change how it appears in the New Relic UI.
Important
If you do not specify the app name in your New Relic configuration file, most New Relic agents provide a generic application name by default. To ensure all aggregated data for the same app is reported accurately, make sure you give each app a descriptive name.
Changing the name vs. the alias
You can assign a new app name or change the app alias. These have two different effects:
Term | How to change it | Effect |
|---|---|---|
Name | Changing the app name in the agent's configuration file will cause the application to report to a new heading in the New Relic user interface, with a total discontinuity of data. This is useful, for example, if you want to start over and report new data. If no other agents are reporting to the old app name, the old app name will appear gray and can be deleted. | |
Alias | Creating an alias for the app name only changes how the app name appears in the New Relic UI. Changing the alias does not affect how data is reported. It simply helps you keep track of your data with a useful alias. |
Give each app a descriptive name
By default, most New Relic agents provide a default application name, such as My Application or PHP Application, for each app that is linked to your account.
Important
We recommend changing the default name of an app to a more descriptive name before deployment, and it can be up to 128 characters long.
Each unique app name creates a new application record in your New Relic UI, which allows you to:
- Run an application on more than one host, and have all the data aggregated (collected) under the same name.
- Run multiple applications on a single host, and have all the data aggregated (collected) under different names.
Assign the name in your config file
To change the app name, set the app name value in the agent's configuration file. If you have deployed an app via one APM agent, and then deploy another app with the same name via a different APM agent, New Relic will automatically append the agent language name to the end of the second app's name. For example, if you deploy a Node.js app named New-App, and then deploy a .NET app named New-App, New Relic will automatically append the second app name as New-App (DOTNET).
To ensure compliance with naming conventions, please note that the symbols < and > are not permitted in the application name. If these symbols are included, they will be automatically removed. Please ensure that your application name adheres to this requirement.
Agent | Configuration file value |
|---|---|
C | Identify a maximum of three names separated by a semicolon |
Go | Set |
Java | See the options for naming your Java application. |
.NET | Use any of the available options to name your .NET app. |
Node.js | Set |
PHP | See the options for naming your PHP application. |
Python | Set |
Ruby | Set |
Change the application's alias
The application name you set in the New Relic user interface is a human-readable alias. If you rename your app, the visible name is updated everywhere in the New Relic UI, including in linked browser apps.
Initially, this alias is the same as the app's identifier name in the New Relic agent configuration file. However, changing the UI alias does not affect the underlying app name used for data rollup, which is set in the agent config file. The application must be actively reporting data to change the alias. Changing the UI alias will cause all agents that report under the app identifier to restart themselves.
To change the alias for your application's name in the New Relic user interface:
- Go to one.newrelic.com > All capabilities > APM & services > (select an app) > Settings > Application.
- In the Application alias field, type a new name (alias) for the selected app.
- Select Save application settings.
You can also change the app's alias with the New Relic REST API.
Tip
When you make a change via Application settings, the saved change will restart the agent. Only the agent for this specific service will restart, but the action will not restart your app pools or web servers.
Using multiple names for an app
By giving your app multiple names, you can aggregate metrics for multiple agents across an entire app or service.
Important
If you use multiple names for an app, the last name assigned is the least specific name New Relic uses to roll up the data. For best results to view both instance-level and aggregated data, set the order of your app's rollup names from most specific to least specific in your configuration file.