Skip to content

Files

Latest commit

 

History

History

xml-custom-instrumentation

README.md

New Relic .NET Agent Sample - Custom XML Instrumentation

Overview

This sample demonstrates the use of a custom instrumentation XML in a .NET 9 Console app, using the NewRelic.Agent NuGet package. The application runs a BackgroundService that requests the current weather for Portland, OR (using a free api service) every 5 seconds and writes the JSON response to the console.

Custom instrumentation via XML is appropriate in cases where you cannot modify the source code of the application, or where you want to apply the same instrumentation to multiple applications. The XML file is used to define the custom instrumentation rules, which are then applied by the New Relic .NET agent at runtime.

The custom-instrumentation.xml file defines the custom instrumentation for the application. It specifies that BackgroundService.GetTheWeatherAsync() should be instrumented as a non-web transaction. An explicit metric name of GetTheWeather is specified, so the transaction will appear in the New Relic UI as OtherTransaction/Custom/GetTheWeather.

In order for custom instrumentation to be picked up by the .NET agent, the custom-instrumentation.xml file must be placed in the extensions folder below the New Relic .NET agent installation folder. For this specific application, the .NET agent is deployed from a NuGet package, so the installation folder will be the newrelic folder in the application's output directory. runSample.ps1 copies the custom-instrumentation.xml file to the appropriate location before starting the application.

For other installation types, you may need to manually copy the custom-instrumentation.xml file to the appropriate location. For example, if you are using the .NET agent MSI installer, the extensions folder will be located in the ProgramData\New Relic\.NET Agent\Extensions folder. Refer to Create Transactions using XML for more information.

To run this sample:

  1. Edit runSample.ps1 and replace <your-new-relic-license-key> with your New Relic license key.
  2. Start a Powershell terminal window and navigate to the custom-instrumentation\xml-custom-instrumentation folder, then run: 
    .\runSample.ps1
  3. Log in to your New Relic account and look for the CustomInstrumentationXmlSample app on the APM Summary page (it can take a few minutes). The custom instrumentation transactions will be under Transaction type = Non-web.
  4. You can view the logs generated by the New Relic .NET Agent by navigating to the bin\release\net9.0\newrelic\logs folder.

For more help

You can find more guidance regarding custom instrumentation in Introduction to .NET custom instrumentation.