This document explains how to install and enable New Relic's .NET agent on Linux for application performance monitoring.
To use .NET or any other agent, as well as the rest of our observability platform, join the New Relic family! Sign up to create your free account in only a few seconds. Then ingest up to 100GB of data for free each month. Forever.
Install overview
The instructions in this document are for a standard .NET agent installation on Linux. However, some setups have specific install documentation that you should read first:
If you modify your newrelic.config
file, make sure it retains the default UTF-8 encoding. If your editor adds a BOM (Byte Order Mark) to the encoding, the agent will be unable to read the file and will not start up in Linux.
Step 1. Download and install the agent
Security notice: Make sure that the location where you install the .NET agent is configured to prevent unauthorized access.
To install the .NET agent on a Linux system with a package manager:
-
Install the agent. These details are the same for all installations using a package manager:
- Install location:
/usr/local/newrelic-netcore20-agent
. - The file
newrelic-netcore20-agent-path.sh
is placed in/etc/profile.d
, and this will set theCORECLR_NEWRELIC_HOME
environment variable on system start. - The path to
newrelic.config
file is${CORECLR_NEWRELIC_HOME}/newrelic.config
.
- Install location:
-
Follow the instructions for your package manager:
- Install with apt (Debian, Linux Mint, or Ubuntu)
-
-
Configure the New Relic apt repository by adding
deb http://apt.newrelic.com/debian/ newrelic non-free
to/etc/apt/sources.list.d/newrelic.list
:echo 'deb http://apt.newrelic.com/debian/ newrelic non-free' | sudo tee /etc/apt/sources.list.d/newrelic.list
-
Enable New Relic's GPG key to allow apt to find New Relic packages. To avoid possible errors about public keys, run this command as root:
wget -O- https://download.newrelic.com/548C16BF.gpg | sudo apt-key add -
-
Update the local package list:
sudo apt-get update
-
Install the agent:
sudo apt-get install newrelic-netcore20-agent
-
- Install with dpkg (Debian, Linux Mint, or Ubuntu)
-
- Go to download.newrelic.com/dot_net_agent/latest_release, and copy the URL that corresponds to your architecture and to the latest
newrelic-netcore20-agent
package. -
Download the package with
wget
, replacinghttps://LINK_TO_PACKAGE
with the full URL of the package:wget -L https://LINK_TO_PACKAGE
-
Install the agent, replacing
VERSION
with the current version:sudo dpkg -i newrelic-netcore20-agent_VERSION_amd64.deb
- Go to download.newrelic.com/dot_net_agent/latest_release, and copy the URL that corresponds to your architecture and to the latest
- Install with rpm or yum (CentOS, Oracle Linux, or RHEL)
-
-
Configure the New Relic rpm repository:
sudo rpm -Uvh http://yum.newrelic.com/pub/newrelic/el5/x86_64/newrelic-repo-5-3.noarch.rpm cat << REPO | sudo tee "/etc/yum.repos.d/newrelic-netcore20-agent.repo" [newrelic-netcore20-agent-repo] name=New Relic .NET Core packages for Enterprise Linux baseurl=http://yum.newrelic.com/pub/newrelic/el7/\$basearch enabled=1 gpgcheck=1 gpgkey=file:///etc/pki/rpm-gpg/RPM-GPG-KEY-NewRelic REPO
-
Install the agent, replacing
VERSION
with the current version:-
Install with rpm:
sudo rpm -i newrelic-netcore20-agent_VERSION.x86_64.rpm
-
Install with yum:
sudo yum install newrelic-netcore20-agent
-
-
- Install with tarball
-
- Go to download.newrelic.com/dot_net_agent/latest_release, and copy the URL that corresponds to your architecture and to the latest
newrelic-netcore20-agent-VERSION.tar.gz
package. -
Download the package with wget, replacing
https://LINK_TO_PACKAGE
with the full URL of the package:wget -L https://LINK_TO_PACKAGE
-
Extract the agent:
tar xzf newrelic*.tar.gz
-
Move the
newrelic-netcore20-agent
directory to/usr/local
or your preferred install location. -
Verify that the environment variable
CORECLR_NEWRELIC_HOME
points to thenewrelic-netcore20-agent
directory and that the directory is readable by monitored .NET processes.If
CORECLR_NEWRELIC_HOME
does not exist, create it and point it to thenewrelic-netcore20-agent
directory. -
Verify that the
logs
directory in the agent home directory is writeable by monitored .NET processes.
- Go to download.newrelic.com/dot_net_agent/latest_release, and copy the URL that corresponds to your architecture and to the latest
Continue to step 2.
Step 2. Enable the agent
Use one of the following methods to set the environment variables that enable the agent and define your license key. For an ASP.NET Core app targeting .NET Core, use the environment variable method.
- Set environment variables manually
-
You can configure your environment using a custom script. The script must define the variables before your app starts.
Set the environment variables for each application that you want to instrument. If you set these environment variables globally, you could instrument .NET processes other than your apps.
- Set the following environment variables, replacing
PATH_TO_AGENT_DIRECTORY
with the actual path to the .NET Core agent installation folder:CORECLR_ENABLE_PROFILING=1 CORECLR_PROFILER={36032161-FFC0-4B61-B559-F6C5D41BAE5A} CORECLR_NEWRELIC_HOME=PATH_TO_AGENT_DIRECTORY CORECLR_PROFILER_PATH="PATH_TO_AGENT_DIRECTORY/libNewRelicProfiler.so"
-
Use one of the following methods to set your license key (required) and your app name (optional).
- Set via environment variable:
NEW_RELIC_LICENSE_KEY=YOUR_LICENSE_KEY NEW_RELIC_APP_NAME=YOUR_APP_NAME
- Set in
newrelic.config
with thelicenseKey
andname
elements. When setting the app name, give your app a meaningful name.
- Set via environment variable:
- Set the following environment variables, replacing
- Start your app with run.sh
-
-
Use
run.sh
to start your app. For example:$CORECLR_NEWRELIC_HOME/run.sh dotnet MYAPP.dll
-
Use one of the following methods to set your license key (required) and your app name (optional):
-
Set via environment variable:
NEW_RELIC_LICENSE_KEY=YOUR_LICENSE_KEY NEW_RELIC_APP_NAME=YOUR_APP_NAME
-
Set in
newrelic.config
with thelicenseKey
andname
elements. When setting the app name, give your app a meaningful name.
-
-
- Use setenv.sh
-
Except for
CORECLR_NEWRELIC_HOME
, thesource /usr/local/newrelic-netcore20-agent/setenv.sh
script included with the .NET agent configures the environment variables automatically.Set these environment variables before running any apps that you want instrumented. This sets the environment variables only for the current shell and any child processes of that shell.
-
Set the
CORECLR_NEWRELIC_HOME
environment variable to the .NET agent installation directory. -
Use one of the following methods to set your license key (required) and your app name (optional):
- Set via environment variable:
NEW_RELIC_LICENSE_KEY=YOUR_LICENSE_KEY NEW_RELIC_APP_NAME=YOUR_APP_NAME
-
Set in
newrelic.config
with thelicenseKey
andname
elements. When setting the app name, give your app a meaningful name.
- Set via environment variable:
-
Run the
setenv.sh
script located in the directory where you installed the .NET agent.
-
Continue to step 3.
Step 3. View your data in New Relic
After you finish enabling the .NET agent:
- Start or restart your application.
- Generate some traffic, then wait a few minutes for data to appear in the New Relic UI.
If no data appears for your application after a few minutes, follow the troubleshooting procedures. For an in-depth explanation of how to troubleshoot any problems with your .NET agent installation, see .NET agent install for .NET Core: a troubleshooting guide in New Relic's Explorers Hub.