Install .NET Core agent on Linux

This document explains how to install the New Relic .NET Core agent on Linux.

1. Install the agent

To ensure you're using the most relevant install procedures, first read the .NET agent install overview.

The following details are the same for all installations from a package manager:

  • The installation location is /usr/local/newrelic-netcore20-agent.
  • A file named 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 the newrelic.config file is ${CORECLR_NEWRELIC_HOME}/newrelic.config.

To install the .NET Core agent, 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 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
    
  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 -
  3. Update the local package list:

    sudo apt-get update
  4. Install the agent:

    sudo apt-get install newrelic-netcore20-agent
  5. To finish the installation, configure your license key and set the environment variables.

Install with dpkg (Debian, Linux Mint, or Ubuntu)
  1. Go to the download site and copy the URL that corresponds to your architecture and to the latest newrelic-netcore20-agent 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
  3. Install the agent, replacing VERSION with the current version:

    sudo dpkg -i newrelic-netcore20-agent_VERSION_amd64.deb
  4. To finish the installation, configure your license key and set the environment variables.

Install with rpm or yum (CentOS, Oracle Linux, or RHEL)
  1. 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 Agent 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
           
  2. 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
  3. To finish the installation, configure your license key and set the environment variables.

Install with tarball
  1. Go to the download site 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
  3. Extract the agent:

    tar xzf newrelic*.tar.gz
  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.

    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.

  7. To finish the installation, configure your license key and set the environment variables.

2. Configure your local environment

Once the .NET Core agent is installed, set the environment variables that define your license key and enable the agent.

When setting the app name, give your app a meaningful name.

Set environment variables manually

You can configure your environment using a custom script. The script must define the variables before your app starts.

New Relic recommends that you set the environment variables for each application that you want to instrument. If you set these environment variables globally, you might instrument .NET processes other than your apps.

  1. 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"
  2. 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 the licenseKey and name elements.
Start your app with run.sh
  1. Use run.sh to start your app. For example:

    $CORECLR_NEWRELIC_HOME/run.sh dotnet MYAPP.dll
  2. 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 the licenseKey and name elements.
Setup using setenv.sh

Except for CORECLR_NEWRELIC_HOME, the source /usr/local/newrelic-netcore20-agent/setenv.sh script included with the 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.

  1. Set the CORECLR_NEWRELIC_HOME environment variable to the .NET Core agent installation directory.
  2. 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 the licenseKey and name elements.
  3. Run the setenv.sh script located in the directory that you installed the agent in.

3. Start your app

Start or restart your application.

As long as your app is receiving traffic, data should start appearing in your APM Overview page within a few minutes. If no data appears, see No data appears.

Troubleshooting

If you experience troubleshooting issues during the .NET Core installation process, see the New Relic Explorer's Hub post .NET Core agent install troubleshooting.

For more help

Recommendations for learning more: