Install .NET Core agent

This document explains how to install and enable the New Relic APM .NET Core agent (not the .NET Framework agent).

Get started with the .NET Core agent

Before installing the New Relic .NET Core agent:

Security notice: the location where the .NET Core agent is installed should be configured to prevent unauthorized access.

If your application uses one of these hosting platforms, read that documentation:

Install procedures for ASP.NET Core applications:

For non-ASP.NET Core applications, you'll need to implement custom instrumentation after you install the .NET Core agent.

Install for Windows with zipped agent file (recommended)

The zipped .NET Core agent file package can be manually installed and enabled or used in an automated script process.

Before installing the agent:

To install the .NET Core agent using its .zip file:

  1. Go to the .NET agent download site and get the file matching your application architecture:
    • 32-bit: newrelic-netcore20-agent-win-x86-VERSION.zip
    • 64-bit: newrelic-netcore20-agent-win-x64-VERSION.zip
  2. Unzip the agent folder in the desired location.
  3. Set the following environment variables. Note that setting these system-wide will result in all available .NET applications being monitored.

    CORECLR_ENABLE_PROFILING=1
    CORECLR_PROFILER={36032161-FFC0-4B61-B559-F6C5D41BAE5A}
    CORECLR_NEWRELIC_HOME=PATH\TO\INSTALL
    CORECLR_PROFILER_PATH=%CORECLR_NEWRELIC_HOME%\NewRelic.Profiler.dll
    NEW_RELIC_LICENSE_KEY=YOUR_LICENSE_KEY
    NEW_RELIC_APP_NAME=YOUR_APP_NAME
    

    For more context, see Environment variables.

    Instructions for IIS-hosted ASP.NET Core apps

    If you're using an ASP.NET Core application that uses IIS as a reverse proxy (via the AspNetCoreModule), you can set the required environment variables in your web.config file, under the aspNetCore section.

    Here's an example of how that section would look after configuration:

    <aspNetCore processPath="dotnet" arguments=".\MyAppName.dll" stdoutLogEnabled="false" stdoutLogFile=".\logs\stdout" >
    <environmentVariables>
    <environmentVariable name="CORECLR_ENABLE_PROFILING" value="1" />
    <environmentVariable name="CORECLR_PROFILER" value="{36032161-FFC0-4B61-B559-F6C5D41BAE5A}" />
    <environmentVariable name="CORECLR_NEWRELIC_HOME" value="C:\ProgramData\New Relic\.NET Core Agent\" />
    <environmentVariable name="CORECLR_PROFILER_PATH" value="C:\ProgramData\New Relic\.NET Core Agent\NewRelic.Profiler.dll" />
    <environmentVariable name="NEW_RELIC_LICENSE_KEY" value="YOUR_LICENSE_KEY" />
    <environmentVariable name="NEW_RELIC_APP_NAME" value="YOUR_APP_NAME" />
    </environmentVariables>
    </aspNetCore>
    

    For more context on these values, see Environment variables.

    For more on using the web.config, see Microsoft's ANCM configuration documentation.

  4. Restart your application. If using IIS, restart IIS.

If your application is receiving traffic, data should appear within a few minutes. If it doesn't, see No data appears.

For an in-depth explanation of .NET Core install issues, see the New Relic Explorer's Hub post .NET Core agent install: a troubleshooting guide.

Install with NuGet (Windows and Linux)

The NewRelic.Agent NuGet package places the New Relic agent in your application build's output directory so that New Relic monitoring is included when the application is deployed.

Before installing the agent:

  • A 64-bit system is required to use NuGet to install the .NET agent (see other .NET Core agent requirements).
  • Note that if you use NuGet to update an existing .NET agent, this will overwrite previously made changes to newrelic.config. To preserve changes, first save the config file outside of your project, then restore it after updating.

Here's an example of using NuGet via Visual Studio to install the .NET Core agent:

  1. Open your Visual Studio solution, or create a new one by selecting File > New > Project. For multi-project solutions, be sure to select the correct project (for example, a specific website project).
  2. Open the Package Manager console by selecting Tools > Library Package Manager > Package Manager Console. Set your project as the default project.
  3. From the Package Manager command prompt, type Install-Package NewRelic.Agent and press Enter. When you build your project, the .NET agent folder will be copied to your build output directory.
  4. Set environment variables (below). How to do this will vary, depending on your system and environment.

    Environment variables for Windows
    CORECLR_ENABLE_PROFILING=1
    CORECLR_PROFILER={36032161-FFC0-4B61-B559-F6C5D41BAE5A}
    CORECLR_PROFILER_PATH=APP_DEPLOYMENT_DIRECTORY\newrelic\NewRelic.Profiler.dll
    CORECLR_NEWRELIC_HOME=APP_DEPLOYMENT_DIRECTORY\newrelic
    NEW_RELIC_LICENSE_KEY=YOUR_LICENSE_KEY
    NEW_RELIC_APP_NAME=YOUR_APP_NAME
    

    The license key and app name aren't required environment variables; they can be set in other ways.

    Environment variables for Linux
    CORECLR_ENABLE_PROFILING=1
    CORECLR_PROFILER={36032161-FFC0-4B61-B559-F6C5D41BAE5A}
    CORECLR_PROFILER_PATH=APP_DEPLOYMENT_DIRECTORY/newrelic/libNewRelicProfiler.so
    CORECLR_NEWRELIC_HOME=APP_DEPLOYMENT_DIRECTORY/newrelic
    NEW_RELIC_LICENSE_KEY=YOUR_LICENSE_KEY
    NEW_RELIC_APP_NAME=YOUR_APP_NAME
    

    The license key and app name aren't required environment variables; they can be set in other ways.

If your application is receiving traffic, data should appear within a few minutes. If it doesn't, see No data appears.

Install with scriptable installer (Windows)

The scriptable installer package is a zip archive containing a PowerShell script for installing the .NET agent on a Windows system. For more details about this tool, see the install resources.

Before installing the agent:

For security reasons, it is necessary to execute the installAgent.ps1 script as shown below, by prepending ./ to the script filename, rather than by prepending powershell to the script. If you execute the script by prepending powershell, and any of your supplied arguments (e.g. the install path or custom log path) have spaces in them, these arguments will be corrupted, which would lead to the agent being installed to a location other than the intended location, which could be unsecure.

To install the .NET Core agent with the scriptable installer on a Windows system:

  1. Ensure you have administrator rights for your Windows admin group. For more details on this, see the permissions documentation
  2. Download the .NET Core agent's scriptable installer package from the .NET agent download site. By downloading or using one of these packages, you agree to and accept the license terms.
  3. Unzip the package in the desired location.
  4. Open a command shell and navigate into the unzipped package's folder.
  5. You can install the agent either locally or globally:

    Local install

    For a simple install, with no options, use this command:

    ./installAgent.ps1 -destination PATH -installType global -licenseKey YOUR_LICENSE_KEY \
    	[-appName "YOUR_APPLICATION_NAME" -logDir "PATH_TO_CUSTOM_LOG_LOCATION"]
    

    To install with one or more additional options, use the same command with appended options (options highlighted below). For option descriptions, see Scriptable installer options.

    ./installAgent.ps1 -destination PATH -installType local -licenseKey YOUR_LICENSE_KEY \
    	[-appName "YOUR_APPLICATION_NAME" -logDir "PATH_TO_CUSTOM_LOG_LOCATION" -X86 -ResetIIS -Force]  
    
    Global install

    The global install will instrument all .NET Core processes on your system. Only choose the global install if you want all .NET Core processes monitored.

    For a simple install with no options, use this command:

    ./installAgent.ps1 -destination PATH -installType global -licenseKey YOUR_LICENSE_KEY \
    	[-appName "YOUR_APPLICATION_NAME" -logDir "PATH_TO_CUSTOM_LOG_LOCATION"]
    

    To install with one or more additional options, use the same command with appended options (some options highlighted below). To see all of the available options and their descriptions, see Scriptable installer options.

    ./installAgent.ps1 -destination PATH -installType local -licenseKey YOUR_LICENSE_KEY \
    	[-appName "YOUR_APPLICATION_NAME" -logDir "PATH_TO_CUSTOM_LOG_LOCATION" -X86 -ResetIIS -Force]  
    

If your application is receiving traffic, data should appear within a few minutes. If it doesn't, see No data appears.

Install with package managers (Linux)

To install the .NET Core 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.

    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
    Install with dpkg (Debian, Linux Mint, or Ubuntu)
    1. Go to the .NET agent 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
    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
    Install with tarball
    1. Go to the .NET agent 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.

  2. Use one of the following methods to set the environment variables that enable the agent and define your license key:

    When setting the app name, we recommend you 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 or restart your application.

If your application is receiving traffic, data should appear within a few minutes. If it doesn't, see No data appears.

For an in-depth explanation of .NET Core install issues, see the New Relic Explorer's Hub post .NET Core agent install: a troubleshooting guide.

For more help

Recommendations for learning more: