How to monitor a .NET Core application with New Relic

With .NET Core, you can build a wide variety of applications and services that work on any operating system—web, mobile and desktop apps, games, microservices, internet of things, and more. But how do you know if your application is running slow? And how do you determine whether you are spending money on unnecessary resources? To answer questions like these, you need to monitor your application’s performance. Monitoring can help you understand the health and behavior of your application, which helps you to quickly identify and resolve issues in your app. 

But you might not know what exact metrics are key to your app’s performance, and you might not have a lot of time to investigate and set something up. This is where New Relic quickstarts can give you curated, opinionated monitoring for your entire technology stack in just a few minutes. In this blog, you’ll learn how to set up .NET Core monitoring by:

• Using the .NET Core quickstart to install the New Relic .NET agent to monitor an ASP.NET Core MVC application running in a Linux Docker container.
• Implementing the pre-configured dashboard and alerts that come with the .NET Core quickstart.
• Understanding how you can use the .NET Core quickstart to monitor a .NET Core application, service, or your infrastructure running on other technology such as Windows, Linux, Azure, and AWS. 

Why you should monitor .NET Core with New Relic

Distributed software environments make tracking and troubleshooting issues much more complicated. Not only are you dealing with multiple components that may be built with different technology, you can’t always predict what will go wrong in a distributed system. That’s why it’s important to use an all-in-one observability solution like New Relic that can instrument and collect data from your entire stack, including from highly custom, proprietary software.

Some observability solutions are designed to focus on vendor-specific services, which either limits you to the vendor or leads to tool fragmentation. For example, Azure Monitor and Application Insights are designed mainly for Azure-based services. On the other hand, New Relic supports monitoring of applications and services running across multiple cloud providers (Azure, AWS, GCP), on-premises, or in hybrid environments. This flexibility allows businesses with diverse infrastructure setups to standardize on a single monitoring tool. 

When you instrument everything and collect all your telemetry data in one location, that’s when you are truly practicing and benefiting from observability. Here are some of the benefits:

• Your telemetry data is unified for consumption across teams.
• Developer and engineer time is shifted from incident response (reactive) towards higher-value work (proactive).
• Cross-team collaboration improves and enables you to make decisions related to the software stack.
• Your revenue retention improves from mitigated service disruptions and business risk, and from a deeper understanding of customer behavior.

Curated monitoring tools for your .NET Core application

A quickstart is a guided installation that helps you identify and install the right New Relic agent to monitor your .NET Core app and infrastructure. As well as acting as an installation guide, the .NET Core quickstart comes with a set of curated tools that can help you start making sense of incoming telemetry data. You’ll get the following:

• An interactive dashboard that helps drive insight from important metrics, like CPU usage, total transactions, and slowest query time. The next image shows what the pre-built dashboard looks like.
• Alerts that detect changes in key performance metrics. When you set up notifications, New Relic will let you know when something needs your attention. The dashboard comes with the following alerts:
  • Apdex Score. Apdex measures user satisfaction using the response time your application or service. This alert is triggered when the Apdex score is below 0.5 for 5 minutes, which means your application or service is slow and likely frustrating users. 
  • Memory Usage. This alert is triggered when memory usage is above 90%, which helps identify processes that are using too much memory so you can fix them and prevent downtime. 
  • Transaction Errors. This alert is triggered when application transactions fail more than 10% of the time in 5 minutes. This alert can help you stay on top of emergent issues in your application so that you can resolve them faster and reduce downtime.

How to use the .NET Core quickstart

In this next section, you’ll use the .NET Core quickstart to instrument a Docker container running an ASP.NET Core web app. These are the steps you’ll complete:

1. Log in to your New Relic account, or sign up if you don’t have one.
2. Install the New Relic .NET agent using the quickstart guide.
3. Configure the .NET agent in the Docker container.
4. View the .NET Core application data in New Relic.
5. Deploy the quickstart resources: a dashboard and three alerts.

Prerequisite: Confirm system requirements

To check compatibility, see .NET agent: compatibility and requirements for .NET Core.

1. Log in to New Relic

Log in to your New Relic account. Sign up if you don’t have an account. Your free account includes 100 GB/month of data ingest, one  full-platform user, and unlimited basic users.

2. Install the New Relic .NET agent with the quickstart guide

After you’ve logged in to New Relic, navigate to the .NET Core quickstart and select the Install now button. This will take you to an installation guide in New Relic, as shown in the next image.

The Quickstart installation web page prompts you to confirm that you want to install the capabilities that come with the .NET Core quickstart. 

To move onto the next step, select the Begin installation button to the right of the web page. Doing so will open up a new page within the quickstart guide, as shown in the next image.

This web page describes the Installation plan, which includes three steps: selecting an account, installing the New Relic .NET agent, and then deploying the quickstart dashboards and alerts.

This page also includes quick access to your Ingest Credentials (license key) and Support information. The New Relic agent will use the license key to report data to your New Relic account. Depending on how you are planning to install the .NET Core agent, you may need to copy this key to add it to your code. To install the .NET Core agent in a Linux Docker container, you will need the license key, so go ahead and select the icon Copy to clipboard to the right of the license key. You can also quickly grab your API keys from your account administration in New Relic. 

Select the Begin Installation button. You'll be prompted to install New Relic and confirm the version of the .NET agent you’ll be installing.

Select the Begin Installation button once more, and a new web page will open asking you to confirm how you want to install the New Relic .NET agent. You’ll have several installation options to choose from:

• On a Linux host
• On a Windows hosting with IIS
• On a Windows hosting without IIS
• Docker for Linux
• Docker for Windows
• Azure Web Apps
• AWS Lambda

Select the installation process that makes sense for your application. The installation guide will vary based on which process you select. 

To follow along with this blog, select Docker for Linux, which will open up a new browser tab to Monitoring your .NET app in the New Relic docs. In a later step you’ll come back to the quickstart guide, so leave that browser tab open for now.

3. Configure the .NET agent in your Dockerfile

Within the docs on Monitoring your .NET app, scroll down to the Configure Docker section to read about next steps.

The Configure Docker section covers a few important topics:

• How you must implement New Relic in a Linux Docker container running .NET Core
• The variation in names for the .NET agent based on whether you are using 10.0.0 or higher, or version 9.9.0 or lower
• Two example code snippets that show how to install and enable the .NET agent in a Linux Dockerfile and a Linux multi-stage Dockerfile

You’ll use some of the code in the provided code snippets, but before you do, it’s time to spin up a .NET Core application in a Linux Docker container. You’re welcome to use an existing project you have and skip these next steps. Or you can follow along with the next set of three steps to spin up a sample application from Microsoft that contains a simple ASP.NET Core web app in a Linux Docker container:

1. Clone down the sample application: 
   • git clone https://github.com/dotnet/dotnet-docker.
2. Navigate to dotnet-docker/samples/aspnetapp and run the following commands:
   • docker build -t aspnetapp . to build the image.
   • docker run -it --rm -p 5000:80 --name aspnetcore_sample aspnetapp to run the container.
3. Confirm the example app is running as expected in your browser at http://localhost:5000.

With your chosen .NET Core app, the next step is to open up your Dockerfile to install and enable the New Relic .NET agent. 

If you’re using the sample ASP.NET Core app from Microsoft, open the Dockerfile in the dotnet-docker/samples/aspnetapp folder. This is a multi-stage Dockerfile and this is what the code should look like:

Next, go back to Configure Docker in the New Relic docs and scroll down to the code snippet called Example Linux Multi-stage Dockerfile. Copy the following code to install and enable the New Relic .NET agent:

Important: The code to enable the New Relic .NET agent in a Linux Docker container is the same whether or not your Dockerfile is multi-stage. 

Next, you’ll paste the code within the # final stage/image of your Dockerfile, below the FROM mcr.microsoft.com/dotnet/aspnet:7.0 AS final statement and above the WORKDIR /app statement. Here’s what your multi-stage Docker file should look like when you're done:

Whether you’re using a multi-stage Dockerfile or not, installing and enabling the .NET agent should go in roughly the same location: after the app is built, but before the working directory moves to the /app folder within the image.

The next step is to update the sample New Relic configuration code in the Dockerfile with your custom information. Update the following values:

• Set the value of NEW_RELIC_LICENSE_KEY to your license key. If you don’t have it, get your New Relic API key.
• Set the value of NEW_RELIC_APP_NAME to whatever you would like to call this app. This name is what you’ll use to find and identify this app in New Relic.

Here’s an example of what the values might look like with a sample, invalid license key:

4. View .NET Core application data in New Relic

To view your data in New Relic, open https://one.newrelic.com/ in a new browser tab. You’ll revisit the tab with the quickstart soon, so don’t mess with it for now. 

It can take a few minutes for New Relic to receive data from the .NET agent monitoring your .NET Core app. You can select All Entities in New Relic to see if your data is being received in New Relic. The All Entities page shows everything that you've instrumented with New Relic. You’ll know that your app’s data is being received when you see its name in the list, as shown in the next image.

Select the name of your application to go to its summary page within New Relic APM & Services. You should see something similar to the next image.

The summary page gives you an overview of the most important metrics affecting the health and performance of your application. This includes charts for:

• Web transactions time
• Apdex score
• Throughput
• Error rate
• Logs
• Transactions
• Infrastructure

You can select the question mark next to the title of each chart to learn more about what the chart shows, how its data is collected, and find links to relevant resources. You’ll also find many other links that will help you set up deployment tracking and service levels, as well as other web pages that can help you expand your monitoring, triage errors, get insight into events, and more.

For recommendations on what else you can do to get the most out of application performance monitoring, select the Recommendations menu item. For tips on application performance monitoring, check out the APM best practices guide on the New Relic docs.

There’s a lot to explore on this page, but there’s one last step to complete in the quickstart guide.

5. Deploy the dashboard and alerts 

The last step in the .NET Core quickstart is to deploy the pre-built dashboard and alerts. Navigate back to the browser tab opened to the quickstart. Close out of the installation web pages until you return to the Installation Plan page, as shown in the next image.

Since you’ve finished installing and enabling the .NET agent with the help of the New Relic docs, select Skip this step to move on to deploying the quickstart dashboard and alerts. The link is highlighted in a green square in the next image.

This will move you to the last step in the quickstart guide, and confirm the resources that will be installed to your account.

Select the button See your data to open your curated dashboard for .NET. 

How to use the .NET quickstart dashboard

The .NET dashboard includes an overview page that shows data from all of your instrumented .NET applications and services. This page highlights the most frequently used metrics for measuring your application’s performance: transactions, response times, errors, and resource usage.

Dashboards are configurable tools. To learn how to customize your dashboard, visit the documentation Manage your dashboard.

To narrow your view and look at the data from only one app on your dashboard, use the filter to search by your app’s name or another value. You can create a new filter by following these steps:

1. Select the filter icon to expand the menu.
2. For the ATTRIBUTE field, enter “appName” or another attribute you want to search by.
3. For the VALUE field, enter your app’s name. In this example, the app’s name is “aspnetcore_on_docker_linux_container”.
4. Select Apply to apply your filter.

The .NET dashboard also contains five other tabs that display the following data: thread pool, garbage collection, transactions, errors, and alerts. For example, here’s what the thread pool tab looks like:

With the thread pool dashboard, you can see how your app is handling user traffic (throughput) and how many threads and workers are in use versus how many are actually available so that you can quickly identify any bottlenecks in your app’s performance.

And here’s what the garbage collection tab looks like:

This tab visualizes .NET garbage collection metrics as they relate to memory usage. Monitoring these metrics can help you identify and resolve performance issues related to improper memory management that can stop or slow down your application.

To see example images of the other tabs in the .NET dashboard—transactions, errors, and alerts—visit the .NET Core quickstart.

How to find and use alerts

You can find the .NET Core alerts in New Relic by selecting Alerts & AI > Alert Conditions & Policies > .NET core alert policy.

Within the .NET core alert policy, you’ll find the three alerts that come with the .NET Core quickstart: transaction errors, memory usage, and Apdex score. From this page, you can do a few things:

• Manage the policy.
• Select an alert to see its details including how the query for this alert is created using NRQL.
• Edit an alert.
• Create a new alert condition. 

Pay attention to the warning at the top of the page. Even though your alert conditions are set up, you need to also set up notifications to get notified when an alert threshold is crossed.