XMLによるトランザクションの作成（.NET）

New Relic は サポートしているフレームワーク を自動的に計測します。しかし、一部のトランザクションが自動的に作成されていないフレームワークや、インスツルメンテーションしたいメソッドが追加されている場合もあります。 トランザクション を作成することで、これらのメソッドにカスタムインスツルメンテーション を追加することができます。XML で作成されたトランザクションは、 New Relic UI では非ウェブ として分類されます。

このドキュメントでは、XMLファイルを使用してトランザクションを作成する方法について説明します。また、以下のことができます。

• 既存のトランザクションにXMLを使って詳細を追加
• .NET エージェント API を使って、トランザクションを作成したり、既存のトランザクションに詳細を追加したりすることができます。.

非IISアプリケーションを使用している場合、XMLインストルメンテーションでは、 .NETエージェントのインストール中にInstrument allオプションを有効にする必要があります。

XMLによるトランザクションの作成

カスタム・トランザクション（自動的にインスツルメンテーションされないトランザクション）は、カスタム・インスツルメンテーションXMLファイルで定義されます。トランザクションの作成をトリガーするメソッドを定義します。また、トリガー・メソッドによって呼び出される追加のメソッドをインストゥルメントすることもできます。

カスタムトランザクションを作成する前に知っておくべき重要なルールがあります。

• データベースや外部からの呼び出しは、自動的にインスツルメンテーションされるので、カスタムのインスツルメンテーションは必要ありません。
• XMLファイルが正しいパスにあることを確認してください。インストルメンテーションセットを定義するために、.NETエージェントはExtensionsディレクトリ内のすべてのXMLファイルを読み取ります。
• 計測しようとしたメソッドがすでに既存のトランザクションの一部である場合、そのトランザクションにセグメントとして追加されます。新しいトランザクションは作成されません。これは、親メソッドがカスタム・インスツルメンテーションを使用してインスツルメンテーションされている場合にも発生します。
• このメソッドはアプリケーションが終了するまで終了せず、データが New Relic に送信されない可能性があるため、 Main()などの計測は避けてください。

カスタムインストゥルメンテーションファイルを作成するには

1. .NETAgentディレクトリ内のExtensionsディレクトリに新しい.xmlファイルを作成します。このディレクトリの場所は、OSによって異なります。

   Windowsの.NET FrameworkまたはCoreエージェントの場合

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

   コピー

   重要

   Program Files }ディレクトリではなく、 ProgramDataディレクトリを使用してください。

   Linux 上の .NET Core の場合

   PATH_TO_AGENT_DIRECTORY/Extensions

   コピー

   PATH_TO_AGENT_DIRECTORY デフォルトの/usr/local/newrelic-dotnet-agent （エージェントバージョン10.0.0以降）、 /usr/local/newrelic-netcore20-agent （エージェントバージョン9.9.0以下）、またはインストール時に選択したディレクトリになります。

   Azure App Servicesの場合

   エージェント for .NET Framework:

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

   コピー

   .NET Core のエージェント:

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

   コピー

2. このテンプレートを、作成したファイルにコピーします。このテンプレートでは、トランザクションとして2つの独立したクラスとメソッドを定義していますが、さらに追加することができます。

   <?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. 作成したファイルで、属性値TransactionName 、 AssemblyName 、 NameSpace.ClassName 、およびMethodNameをカスタマイズします。トリガー メソッドと、トリガー メソッドによって呼び出されるメソッドの両方について、これらの値をカスタマイズします。上記の 3 番目の例に示すように、オプションのminVersionおよびmaxVersion属性値を使用して、特定のバージョンのアセンブリをターゲットにすることもできます。この機能には、エージェント 10.6.0 以降が必要であることに注意してください。

   ヒント

   これらの値は、大文字と小文字を区別します。

   • TransactionName: トランザクション名を定義します。metricName属性はオプションです。省略した場合、トランザクション名はNameSpace.ClassName/MethodNameになります。トランザクション カテゴリはCustomになります。結果の完全なメトリック名はOtherTransaction/Custom/TransactionNameになります。トランザクション カテゴリをCustomから変更する場合は、 SetTransactionName API 呼び出しを使用してください。New Relic UI では、トランザクション タイプ フィールドのカテゴリごとにトランザクションがグループ化されます。
   • AssemblyName：トリガーメソッドを含むアセンブリ。
   • NameSpace.ClassName：トリガーメソッドを含む完全修飾クラス名。
   • MethodName：トリガーメソッドの正確な名前。
   • minVersion: オプション (削除できます)。インストルメント化する最小アセンブリ バージョン (包括的)。省略した場合、最小バージョンは 0 と見なされます。エージェント 10.6.0 以降が必要です。
   • maxVersion: オプション (削除できます)。インスツルメントするアセンブリの最大バージョン (排他的)。省略した場合、最大バージョンはありません。エージェント 10.6.0 以降が必要です。

2. メソッドを追加するには、トランザクションとして定義される"NewRelic.Agent.Core.Tracer.Factories.BackgroundThreadTracerFactory"属性を含める必要があります。この属性のないタグは、既存の取引のみに詳細を追加します。

3. オプション：XMLファイルが正しくフォーマットされているかどうかを確認するには、任意のXSDバリデーターを使用してXSD（ C:\ProgramData\New Relic\.NET Agent\Extensions\extension.xsdにあります）と照合します。

トランザクションをUIで表示

カスタムトランザクションは、 methodNameで指定されたメソッドがassemblyNameで指定されたアセンブリで呼び出されたときに開始されます。メソッドが例外を返すかスローすると、トランザクションは終了します。

これらのメトリックは、 Transactions [トランザクション] ページ および トランザクション追跡で表示できます。トランザクションを表示するには: one.newrelic.com > All capabilities > APM & services > (アプリを選択) > Monitor > Transactions > Type > (タイプを選択)に移動します。API を使用してカテゴリを変更しない限り、タイプは Non-web/Custom になります。

例楽器の3つのメソッド

この例では、トランザクションを作成する簡単な実装を紹介します。

<?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();
                }
            }
        }
    }
}

例コンソールアプリのインストゥルメント化

このシンプルなコンソール アプリは、トランザクションの作成を示します。アプリケーションを数回実行すると、 Transactions page [トランザクション] ページ ( one.newrelic.com > All capabilities > APM & services > (アプリを選択) > Transactions > Type) に作成したトランザクションが表示されます。ダミー セグメントは、トランザクション内訳テーブルおよびトランザクション追跡に表示されます。

<?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);
        }
    }

}