Install .NET agent for Linux

This document explains how to install and enable New Relic's .NET agent on Linux for application performance monitoring.

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:

• ASP.NET Core
• Azure installations
• NuGet install
• Docker container install

Step 1. Download and install the agent

Before you can install, you need a New Relic account (It's free, forever!).

To install the .NET agent on a Linux system with a package manager:

1. 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 the CORECLR_NEWRELIC_HOME environment variable on system start.
   • The path to newrelic.config file is ${CORECLR_NEWRELIC_HOME}/newrelic.config.

2. Follow the instructions for your package manager:

   Install with apt (Debian, Linux Mint, or Ubuntu)

   1. Configure the New Relic apt repository by adding deb https://apt.newrelic.com/debian/ newrelic non-free to /etc/apt/sources.list.d/newrelic.list:

      echo 'deb https://apt.newrelic.com/debian/ newrelic non-free' | sudo tee /etc/apt/sources.list.d/newrelic.list

      Copy

   2. 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 -

      Copy

   3. Update the local package list:

      sudo apt-get update

      Copy

   4. Install the agent:

      sudo apt-get install newrelic-netcore20-agent

      Copy

   Install with dpkg (Debian, Linux Mint, or Ubuntu)

   1. 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 .deb package.

   2. Download the package with wget, replacing https://LINK_TO_PACKAGE with the full URL of the package:

      wget -L https://LINK_TO_PACKAGE

      Copy

   3. Install the agent, replacing VERSION with the current version:

      sudo dpkg -i newrelic-netcore20-agent_VERSION_ARCHITECTURE.deb

      Copy

   Install with yum (CentOS, Oracle Linux, or RHEL)

   Important

   New Relic does not currently offer Linux rpm packages for ARM64. Instead, leverage the tarball to install on these platforms.

   1. Configure the New Relic yum repository:

      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=https://yum.newrelic.com/pub/newrelic/el7/\$basearch
      enabled=1
      gpgcheck=1
      gpgkey=file:///etc/pki/rpm-gpg/RPM-GPG-KEY-NewRelic
      REPO

      Copy

   2. Install the agent:

      sudo yum install newrelic-netcore20-agent

      Copy

   Install with rpm (CentOS, Oracle Linux, or RHEL)

   Important

   New Relic does not currently offer Linux rpm packages for ARM64. Instead, leverage the tarball to install on these platforms.

   1. 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 .rpm package.

   2. Download the package with wget, replacing https://LINK_TO_PACKAGE with the full URL of the package:

      wget -L https://LINK_TO_PACKAGE

      Copy

   3. Install the agent, replacing VERSION with the current version:

      sudo rpm -i newrelic-netcore20-agent_VERSION.x86_64.rpm

      Copy

   Install with tarball

   1. 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.

   2. Download the package with wget, replacing https://LINK_TO_PACKAGE with the full URL of the package:

      wget -L https://LINK_TO_PACKAGE

      Copy

   3. Extract the agent:

      tar xzf newrelic*.tar.gz

      Copy

   4. Move the newrelic-netcore20-agent directory to /usr/local or your preferred install location.

   5. Verify that the environment variable CORECLR_NEWRELIC_HOME points to the newrelic-netcore20-agent directory and that the directory is readable by monitored .NET processes.

      Important

      If CORECLR_NEWRELIC_HOME does not exist, create it and point it to the newrelic-netcore20-agent directory.

   6. Verify that the logs directory in the agent home directory is writeable by monitored .NET processes.

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.

Continue to step 3.

Step 3. View your data in New Relic

After you finish enabling the .NET agent:

1. Start or restart your application.
2. 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.