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

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

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

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

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

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

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

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

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

.NETAgentディレクトリ内のExtensionsディレクトリに新しい.xmlファイルを作成します。このディレクトリの場所は、OSによって異なります。
C:\ProgramData\New Relic\.NET Agent\Extensions
重要
Program Files }ディレクトリではなく、 ProgramDataディレクトリを使用してください。
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以下）、またはインストール時に選択したディレクトリになります。
エージェント for .NET Framework:
D:\home\site\wwwroot\newrelic\extensions
.NET Core のエージェント:
D:\home\site\wwwroot\newrelic_core\extensions

このテンプレートを、作成したファイルにコピーします。このテンプレートでは、トランザクションとして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>

作成したファイルで、属性値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 以降が必要です。
メソッドを追加するには、トランザクションとして定義される"NewRelic.Agent.Core.Tracer.Factories.BackgroundThreadTracerFactory"属性を含める必要があります。この属性のないタグは、既存の取引のみに詳細を追加します。
オプション：XMLファイルが正しくフォーマットされているかどうかを確認するには、任意のXSDバリデーターを使用してXSD（ C:\ProgramData\New Relic\.NET Agent\Extensions\extension.xsdにあります）と照合します。

重要

トランザクション名の末尾に角かっこ[suffix]を使用しないでください。 New Relicは、名前から角かっこを自動的に削除します。代わりに、必要に応じて括弧(suffix)またはその他の記号を使用してください。

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

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

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

one.newrelic.com > All capabilities > APM & services > (アプリを選択) > Monitoring > Transactions > Type > (選択したタイプ): Type [タイプ] メニューを使用してカスタムトランザクションを表示します。

例楽器の3つのメソッド

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

このカスタム・インスツルメンテーション・ファイルでは、インスツルメンテーションを行う3つのメソッドを定義しています。トランザクションとして定義されているのは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="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>

このコードには3つのメソッドが含まれており、それぞれのメソッドがいつエージェントに搭載されるかを説明するコメントも含まれています。

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) に作成したトランザクションが表示されます。ダミー セグメントは、トランザクション内訳テーブルおよびトランザクション追跡に表示されます。

このカスタムインストルメントファイルでは、インストルメントを行うための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="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>

このコードには、カスタム・インスツルメンテーション・ファイルで指定された2つのメソッドが含まれています。

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

}

この機械翻訳は、参考として提供されています。

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