Create transactions via XML (.NET)

New Relic instruments supported frameworks automatically. However, you may also have other frameworks for which some transactions are not being created automatically or additional methods that you would like to instrument. You can add custom instrumentation to these methods by creating transactions. Transactions created via XML are classified as non-web in the New Relic UI.

This document describes how to create transactions with an XML file. You can also:

• Add details to existing transactions using XML
• Create transactions and add detail to existing transactions with the .NET agent API.

If you have a non-IIS application, XML instrumentation requires enabling the Instrument all option during the .NET agent installation.

Create transactions using XML

Custom transactions (transactions not instrumented automatically) are defined in a custom instrumentation XML file. You define a method that triggers the creation of a transaction. You can also instrument additional methods called by the trigger method.

Some important rules to know before you create a custom transaction:

• Database and external calls do not require custom instrumentation because they're automatically instrumented.
• Ensure your XML file is in the correct path. To define its instrumentation set, the .NET agent reads every XML file in the Extensions directory.
• If a method you attempt to instrument is already part of an existing transaction, it will be added as a segment to that transaction. No new transaction will be created. This will occur even if the parent method is instrumented using custom instrumentation.
• Avoid instrumenting things like Main() as this method won't end until the application ends and data may not be sent to New Relic.

To create a custom instrumentation file:

1. Create a new .xml file in the Extensions directory within your .NET Agent directory. The location of this directory depends on your OS:

   For the .NET Framework or Core agent on Windows

   C:\ProgramData\New Relic\.NET Agent\Extensions

   카피

   중요

   Use the ProgramData directory, not the Program Files directory.

   For .NET Core on Linux

   PATH_TO_AGENT_DIRECTORY/Extensions

   카피

   PATH_TO_AGENT_DIRECTORY will be the default /usr/local/newrelic-dotnet-agent (agent versions 10.0.0 or higher), /usr/local/newrelic-netcore20-agent (agent versions 9.9.0 or lower), or the directory chosen at installation.

   For Azure App Services

   Agent for .NET Framework:

   D:\home\site\wwwroot\newrelic\extensions

   카피

   Agent for .NET Core:

   D:\home\site\wwwroot\newrelic_core\extensions

   카피

2. Copy this template into the file you created. This template defines two separate class and methods as transactions but more can be added:

   <?xml version="1.0" encoding="utf-8"?>
   <extension xmlns="urn:newrelic-extension">
     <instrumentation>
       <!-- Define the method which triggers the creation of a transaction. -->
       <tracerFactory name="NewRelic.Agent.Core.Tracer.Factories.BackgroundThreadTracerFactory" metricName="TransactionName">
         <match assemblyName="AssemblyName" className="NameSpace.ClassName">
           <exactMethodMatcher methodName="MethodName" />
         </match>
       </tracerFactory>
       <!-- Define the method which triggers the creation of a transaction. -->
       <tracerFactory name="NewRelic.Agent.Core.Tracer.Factories.BackgroundThreadTracerFactory" metricName="TransactionName2">
         <match assemblyName="AssemblyName" className="NameSpace.ClassName2">
           <exactMethodMatcher methodName="MethodName2" />
         </match>
       </tracerFactory>
       <!-- Define the method which triggers the creation of a transaction. -->
       <tracerFactory name="NewRelic.Agent.Core.Tracer.Factories.BackgroundThreadTracerFactory" metricName="TransactionName3">
         <match assemblyName="AssemblyName" className="NameSpace.ClassName3" minVersion="1.0.0" maxVersion="99.99.99">
           <exactMethodMatcher methodName="MethodName3" />
         </match>
       </tracerFactory>
     </instrumentation>
   </extension>

   카피

1. In the file you created, customize the attribute values TransactionName, AssemblyName, NameSpace.ClassName, and MethodName. Customize these values for both the trigger method and for any methods called by the trigger method. You can also use the optional minVersion and maxVersion attribute values to target specific versions of an assembly, as shown in the third example above. Note that this functionality requires agent 10.6.0 or higher.

   팁

   These values are case sensitive.

   • TransactionName: Defines the transaction name. The metricName attribute is optional. If omitted, the transaction name will be NameSpace.ClassName/MethodName. The transaction category will be Custom. The resulting full metric name will be OtherTransaction/Custom/TransactionName. If you wish to change the transaction category from Custom, use the SetTransactionName API call. The New Relic UI groups transactions under categories in the transaction type field.
   • AssemblyName: The assembly that contains the trigger method.
   • NameSpace.ClassName: The fully-qualified class name that contains the trigger method.
   • MethodName: The exact name of the trigger method.
   • minVersion: Optional (you can remove it). The minimum assembly version to instrument (inclusive). If omitted, the minimum version is considered to be 0. Requires agent 10.6.0 or higher.
   • maxVersion: Optional (you can remove it). The maximum assembly version to instrument (exclusive). If ommitted, there is no maximum version. Requires agent 10.6.0 or higher.

2. Adding additional methods must include the "NewRelic.Agent.Core.Tracer.Factories.BackgroundThreadTracerFactory" attribute to be defined as a transaction. Tags without this attribute will add detail to existing transactions only.

3. Optional: To check if the XML file is formatted correctly, you can check it against the XSD (located at C:\ProgramData\New Relic\.NET Agent\Extensions\extension.xsd) using any XSD validator.

View transactions in the UI

The custom transaction starts when the method specified by methodName is invoked in the assembly specified by assemblyName. The transaction ends when the method returns or throws an exception.

You can view these metrics in the Transactions page and in transaction traces. To view the transaction: Go to one.newrelic.com > All capabilities > APM & services > (select an app) > Monitor > Transactions > Type > (select a type). The type will Non-web/Custom unless you use the API to change the category.

Example: Instrument three methods

This example presents a simple implementation of creating transactions.

<?xml version="1.0" encoding="utf-8"?>
<extension xmlns="urn:newrelic-extension">
  <instrumentation>
    <!-- Define the method which triggers the creation of a transaction. -->
    <tracerFactory name="NewRelic.Agent.Core.Tracer.Factories.BackgroundThreadTracerFactory" metricName="Bars">
      <match assemblyName="Foo" className="Foo.Bar">
        <exactMethodMatcher methodName="Bar1" />
        <exactMethodMatcher methodName="Bar2" />
      </match>
    </tracerFactory>
    <!-- Instrument 0 or more methods called by the trigger method. These methods appear in the transaction breakdown table and in transaction traces. -->
    <tracerFactory>
      <match assemblyName="Foo" className="Foo.Bar">
        <exactMethodMatcher methodName="Bar3" />
      </match>
    </tracerFactory>
  </instrumentation>
</extension>

var bar = new Bar();
bar.Bar1(); // Creates a transaction named Bars in the Custom category.
bar.Bar2(); // Creates a transaction named Bars in the Custom category.
bar.Bar3(); // Won't create a new transaction. See `If Bar3 is called directly`, below.

namespace Foo
{
    public class Bar
    {
        // The agent creates a transaction that includes an external service request in its transaction traces.
        public void Bar1()
        {
            new WebClient().DownloadString("https://www.google.com/");
        }

        // Creates  a transaction containing one segment.
        public void Bar2()
        {
            // The Bar3 segment will contain your SQL query inside of it and possibly an execution plan.
            Bar3();
        }

        // If Bar3 is called directly, the agent will not create a transaction.
        // However, if Bar3 is called from Bar1 or Bar2, Bar3 will appear as a segment containing its SQL query.
        private void Bar3()
        {
            using (var connection = new SqlConnection(ConnectionStrings["MsSqlConnection"].ConnectionString))
            {
                connection.Open();
                using (var command = new SqlCommand("SELECT * FROM table", connection))
                using (var reader = command.ExecuteReader())
                {
                    reader.Read();
                }
            }
        }
    }
}

Example: Instrument a console app

This simple console app demonstrates creating transactions. After running the application a few times, you see the transactions you created in the Transactions page (at one.newrelic.com > All capabilities > APM & services > (select an app) > Transactions > Type). The Dummy segment will be visible in the transactions breakdown table and in any transaction traces.

<?xml version="1.0" encoding="utf-8"?>
<extension xmlns="urn:newrelic-extension">
    <instrumentation>
        <!-- Define the method which triggers the creation of a transaction. -->
        <tracerFactory name="NewRelic.Agent.Core.Tracer.Factories.BackgroundThreadTracerFactory" metricName="CustomTransaction">
          <match assemblyName="ConsoleApplication1" className="ConsoleApplication1.CustomTransaction">
            <exactMethodMatcher methodName="StartTransaction" />
          </match>
        </tracerFactory>
        <!-- Instrument 0 or more methods called by the trigger method. These methods appear in the transaction breakdown table and in transaction traces. -->
        <tracerFactory>
          <match assemblyName="ConsoleApplication1" className="ConsoleApplication1.CustomTransaction">
            <exactMethodMatcher methodName="Dummy" />
          </match>
        </tracerFactory>
    </instrumentation>
</extension>

using System;
using System.Collections.Generic;
using System.Linq;
using System.Text;
using System.Threading.Tasks;

namespace ConsoleApplication1
{
    class Program
    {
        static void Main(string[] args)
        {
            Console.WriteLine("Custom Transactions");
            var t = new CustomTransaction();
            while (true)
                t.StartTransaction();
        }
    }
    class CustomTransaction
    {
        public void StartTransaction()
        {
            Console.WriteLine("StartTransaction");     
            Dummy();
        }
        void Dummy()
        {
            System.Threading.Thread.Sleep(5000);
        }
    }

}