This post assumes that the .NET Framework agent is installed on your host and that, when your non-IIS application is restarted, profiler logs are generated for the process in the agent’s logs folder (
C:\ProgramData\New Relic\.NET Agent\Logs). If you do not see logs being generated in the logs folder when you restart your application, please see this post to troubleshoot the agent’s installation.
The New Relic .NET Framework agent instruments IIS-hosted ASP.NET web applications “out of the box”, but with non-IIS applications there is some additional configuration that needs to be put in place in order for the agent to successfully monitor the application.
This configuration can be separated into two categories:
- Configure the agent to target your application.
- Put custom instrumentation in place to tell the agent what parts of your application are important for monitoring and what constitutes the scope of a transaction.
Configure the Agent to Target Your Application.
Official documentation on targeting non-IIS applications can be found at this link.
This is a pretty straight-forward, simple process. Essentially what you’re doing is telling the agent “When you see my executable start on the host, pay attention and try to monitor it”.
This can be done in one of two ways. Choose the one that works best for your needs.
In the application’s config file: Add the following line inside the
<appSettings> element of your app’s config file.
<add key="NewRelic.AgentEnabled" value="true" />
In the global
newrelic.config file: Add the following to your global
newrelic.config file (
C:\ProgramData\New Relic\.NET Agent), inside the
<configuration> element. Make sure to adjust the file name as needed. Only the actual file name is needed, not the path to it.
<instrumentation> <applications> <application name="YourApplicationExecutable.exe" /> </applications> </instrumentation>
How you know it worked
Once one of the above configurations are in place, restart your application and look in
C:\ProgramData\New Relic\.NET Agent\Logs for a file named
If the agent was correctly configured to target your application, you should see a line like this:
Enabling instrumentation for this process (Path\To\Your\Application.exe) due to . . .
If the agent was not correctly configured to target the application, you’ll see:
This process (Path\To\Your\Application.exe) is not configured to be instrumented.
Once the agent is successfully targeting your application, you may see the application show up in your New Relic account. If the application makes database or external calls, the application will show up in the UI. If it does not make database or external calls, you won’t see it show up in the UI yet.
Even if it does show up in the UI at this point, it won’t actually contain any data about your app until you put some custom instrumentation in place.
Put Custom Instrumentation in Place.
Custom instrumentation is the process of telling the agent which methods in your application should be monitored. In order to see data in your New Relic account for non-IIS applications, you must define at least one custom transaction to contain the data.
A transaction is defined against a specific method and encompases everything that happens from the time that method is called until it returns a value or otherwise terminates.
Going into the process you should keep one thing in mind:
You should never configure custom instrumentation/transactions for methods that do not terminate (such as
Main()). When you define such a method as the start of a transaction, the transaction never completes because the method never ends. The result is that no complete transaction is ever created, therefore nothing from that transaction is sent to New Relic servers.
There are two different ways to create custom instrumentation in the .NET agent:
Attribute Instrumentation - Use the .NET Agent API to add in-code attributes to your methods. Requires agent version 6.16 or newer.
- Easy to use
- No external file configuration/management required
- Requires code-level changes to your application
- Changes to instrumentation require an application restart/redeploy.
The official documentation on Attribute-based instrumentation is pretty thorough, so I’ll just refer you there for directions on getting that set up.
XML-based Instrumentation - Create custom XML files which define the methods in your code you want to instrument.
- Does not require code-level changes to your application.
- Changes to instrumentation do not require an application restart (agent version 7.0 or newer only).
- More complicated to set up than attribute instrumentation.
- Requires configuring and managing XML files on your server.
This is a big subject, so it has its own dedicated post. You can find that here.
There is also official documentation on creating custom transactions with XML files here.
One Final Note
New Relic agent’s harvest cycle is 60 seconds. If your non-IIS app does not run for a minimum of 60 seconds, you will need to add the
sendDataOnExitThresholdservice elements to your newrelic.config to ensure that New Relic collects and receives your metrics properly. Make sure to set your
sendDataOnExitThresholdvalue to less time than the process stays “alive”.