Reporting errors to New Relic from an Azure Worker Role

New Relic is a great tool for monitoring applications and servers. It can integrate nicely with Microsoft Azure, especially with web/IIS based applications. For applications that run in a Worker Role, it can be a bit more tricky to get the project set up correctly and data flowing to New Relic. The following steps walk through the simplest possible case of creating a new Worker role project, configuring it to send an application error to New Relic and deploying the application. A couple of important points that are crucial to getting the New Relic API agent and Azure Worker roles working together are highlighted along the way.

New Relic account

Before you start, make sure you have a New Relic account. You can sign up for free if you need to create one.

Create a Cloud Service project

Create a new Azure Cloud Service in Visual Studio.

In the next dialog called "New Microsoft Azure Cloud Service", add a Worker Role to the solution.

Visual Studio will create a solution with 2 projects for you. The first is the Cloud Service project, which contains associated Roles, along with service definitions and per environment configuration. The second is a standard C# project that contains an initial WorkerRole class that is a RoleEntryPoint.

Install New Relic

Right-click on the C# project and choose "Manage NuGet packages". Look for the "New Relic x64 for Windows Azure" package on nuget.org.

Installing this package will prompt you to enter your license key (which you can obtain from your New Relic account), and then an App Name. This is the name that will be used for displaying the application in the New Relic dashboard.

This package will set up a few things in your solution. It will add 2 msi installers and a cmd file to the C# project. These are used to install the New Relic server monitor and agent on the worker role when it gets deployed.

It will also add some configuration to the ServiceDefinition.csdef file. Namely, 4 environment variables, a Startup Task to install the New Relic bits and a configuration setting for the license key.

You'll also want to install the "NewRelic.Agent.Api" package, which will add a reference to NewRelic.Agent.Api.dll in your project, and enables you to make calls to API methods like IncrementCounter, RecordMetric and NoticeError.

You'll want to check that all these things have actually happened. The New Relic packages aren't perfect and can fail to set themselves up properly. This can happen if the projects aren't at the root of the solution (e.g. are in solution folders). It can also fail to add the license key configuration. If this happens you'll see an error like this when trying to build the solution:

If the configuration is defined in the csdef but not in the individual cscfg file the build will fail. Add it manually if necessary.

Instrument the application

Now you can add some New Relic instrumentation to the application. In this sample project, alter the WorkerRole.RunAsync method to include a call to the New Relic API method NoticeError. This takes an Exception.

There is an important point to note. Calling the NoticeError API alone will not actually cause the agent to report these errors to a New Relic dashboard for this application. Without custom instrumentation, Worker Roles only report database calls and external calls. In order for the API agent to attach to the application, at least one database or external call must be made. If an external call is instrumented, the application will appear in a dashboard, and you'll then be able to see the reported errors as well.

Chances are, your Worker Role is going to be integrating with Azure Storage or other Azure services. These calls will be enough to trigger the agent to attach. If the application has no external calls at all, and all you want to do is report errors to New Relic, you'll need to think of a way of fabricating an external call to get it to work, or consider setting up further custom instrumentation.

Deploy and view application errors

Publish the worker role and let it run. For a simple test project like this, you can easily publish directly from Visual Studio to your Azure subscription, by right-clicking on the Cloud project, and clicking 'Publish', then follow the wizard steps. Wait a minute for the data to make it to New Relic. You should see the application in the New Relic dashboard:

As well as the error we passed on to it: