.NETエージェント8.xから9.xへの移行ガイド

このガイドでは、.NETエージェントの8.xバージョンと9.xバージョンの間の主な変更点、アップグレード時に発生する可能性のある問題、およびバージョン9.xへの移行を成功させる方法について説明しています。

主な変更点は以下の通りです。

ディストリビュートトレーシングはデフォルトで有効
非推奨のパブリックエージェントAPIの削除
非推奨の設定可能なエージェント設定の削除

デフォルトで有効な分散型トレーシング

分散トレーシングは、2018年7月から.NETエージェントに存在する機能です。クロスアプリケーショントレース（CAT）に代わるもので、分散型アプリケーションアーキテクチャの様々なサービスを経由するリクエストに何が起こっているのかを素早く理解するための最適な方法です。CATはバージョン9.0の時点で.NETエージェントでは非推奨となり、将来のメジャーリリースで削除される予定です。

.NET エージェントの 8.x バージョンでは、任意の .NET エージェントインストーラーによってホストにインストールされたデフォルトのnewrelic.configファイルには、 crossApplicationTracer要素が存在し、 enabled="true"が設定されていました。distributedTracing要素はデフォルトでは存在しませんでした。

9.x では、これが逆になります。 crossApplicationTracerはデフォルトでは存在せず、 distributedTracingはデフォルト値のenabled="true"で存在します。ただし、あるバージョンから別のバージョンにアップグレードする場合、エージェントインストーラーは既存のnewrelic.configファイルを上書きしません。したがって、特定のホストでエージェントを 8.x から 9.x にアップグレードする場合、そのホストでのエージェントの動作は変わりません。

ヒント

8.xから9.xへのアップグレード時に、新しいデフォルトのトレース動作を採用したい場合は、分散型トレースを有効にするようにエージェントの設定を変更する必要があります。9.xエージェントを新規にインストールしたホストでは、デフォルトで分散トレーシングが有効になります。

非推奨のパブリックエージェントAPIメソッドの削除

非推奨のAPIメソッドには、同等の機能を持つ代替APIメソッドが用意されています。

ヒント

アプリケーションコードで.NETエージェントAPIを使用している場合は、.NETエージェントを9.xにアップグレードする前に、プロジェクトのパッケージ参照を最新の9.xバージョンのエージェントAPIアセンブリに更新することをお勧めします。これにより、コードで9.xで削除されたAPIメソッドを使用している場合、コンパイル時のエラーが発生します。

重要

8.xまたはそれ以前のバージョンのAPIアセンブリを引き続き使用していて、コードが以下の非推奨APIのいずれかを使用している場合は、コンパイル時エラーは発生しません。しかし、9.xバージョンのエージェントでアプリをインストゥルメントすると、APIメソッドは影響を受けず、エージェントのログファイルにランタイム警告メッセージが表示されます。

削除されたAPI	リプレースメントAPI
`CreateDistributedTracePayload`	`InsertDistributedTraceHeaders` W3C Trace Context ヘッダや、New Relic の分散型トレースヘッダを作成します。
`AcceptDistributedTracePayload`	`AcceptDistributedTraceHeaders` W3C Trace Context ヘッダや、New Relic の分散型トレースヘッダを受け入れます。
`AddCustomParameter`	`AddCustomAttribute` `AddCustomAttribute` はITransactionインターフェイスのメソッドであるため、この API を使用するには現在のトランザクションへの参照が必要です。
`GetBrowserTimingFooter`	`GetBrowserTimingHeader` `GetBrowserTimingFooter` エージェントバージョン 3.x 以降ではObsoleteとしてマークされています。

例

CreateDistributedTracePayload

以前、以下のようなコードがあったとします。

// Create an external web request to another instrumented service
HttpWebRequest requestMessage = (HttpWebRequest)WebRequest.Create("https://remote-address");

// Create the trace payload 
IAgent agent = NewRelic.Api.Agent.NewRelic.GetAgent();
ITransaction transaction = agent.CurrentTransaction;
IDistributedTracePayload payload = transaction.CreateDistributedTracePayload();

// Add the trace payload to the headers of the outgoing request
requestMessage.Headers.Set(NewRelic.Api.Agent.Constants.DistributedTracePayloadKey, payload.HttpSafe());

に置き換えることができます。

// Create an external web request to another instrumented service
HttpWebRequest requestMessage = (HttpWebRequest)WebRequest.Create("https://remote-address");

// Insert the distributed trace headers to the message. The "setter"
// action tells the API how to add headers to the "carrier", which
// is the HttpWebRequest message in this example
IAgent agent = NewRelic.Api.Agent.NewRelic.GetAgent();
ITransaction currentTransaction = agent.CurrentTransaction;
var setter = new Action<HttpWebRequest, string, string>((carrier, key, value) =>
{
    carrier.Headers?.Set(key, value);
});
currentTransaction.InsertDistributedTraceHeaders(requestMessage, setter);

AcceptDistributedTracePayload

以前、以下のようなコードがあったとします。

// Obtain the payload from the upstream request object
HttpContext httpContext = HttpContext.Current;
string payload = httpContext.Request.Headers[NewRelic.Api.Agent.Constants.DistributedTracePayloadKey];

// Accept the payload
IAgent agent = NewRelic.Api.Agent.NewRelic.GetAgent();
ITransaction transaction = agent.CurrentTransaction;
transaction.AcceptDistributedTracePayload(payload, TransportType.HTTP);

に置き換えることができます。

HttpContext httpContext = HttpContext.Current;
IAgent agent = NewRelic.Api.Agent.NewRelic.GetAgent();
ITransaction currentTransaction = agent.CurrentTransaction;

// The "Getter" method defines how to get headers from the carrier, 
// which is the HttpContext in this example 
IEnumerable<string> Getter(HttpContext carrier, string key)
{
    string value = carrier.Request.Headers[key];
    return value == null ? null : new string[] { value };
}

// Call the API
currentTransaction.AcceptDistributedTraceHeaders(httpContext, Getter, TransportType.HTTP);

AddCustomParameter

以前、以下のようなコードがあったとします。

// Called in code that runs inside a transaction created by the
// agent, for example an ASP.NET WebApi endpoint
NewRelic.Api.Agent.NewRelic.AddCustomParameter("myCustomParameter", "myValue");

に置き換えることができます。

// Get the current transaction
IAgent agent = NewRelic.Api.Agent.NewRelic.GetAgent();
ITransaction currentTransaction = agent.CurrentTransaction;

// Add the custom attribute to the current transaction
currentTransaction.AddCustomAttribute("myCustomParameter", "myValue");

非推奨のエージェント設定の削除

次のエージェント構成設定がエージェントから削除されています。8.x から 9.x へのアップグレードパスをできるだけスムーズにするために、 newrelic.configファイルの XML スキーマから設定を削除しません。ただし、エージェントの内部構成ロジックは、これらの設定を無視するように更新され、これらの構成値が無効であることを警告するメッセージをエージェントログファイルに記録します。

表記法について：説明を簡単にするために、このセクションの残りの部分では、コンフィギュレーション要素を完全なXMLではなく、「ドット記法」という略記法で記述します。

たとえば、 newrelic.configファイルに表示される構成要素は次のようになります。

<configuration>
  <parameterGroups>
    <identityParameters>
      …
    </identityParameters>
  </parameterGroups>
  …
</configuration>

この例では、 parameterGroups.IdentityParametersと記述されます。これらの構成要素はすべて最上位の<configuration>要素の子であるため、簡潔にするために省略されています。

削除される設定オプションのほとんどは、属性データの取得または除外に関するものです。以下のドキュメントは、エージェントの属性データ収集の全体像とその設定方法を理解するのに役立ちます。

設定オプションの削除	交換構成オプション
`parameterGroups.identityParameters.*`	`attributes.include` `<parameterGroups> <identityParameter enabled="true"/> </parameterGroups>` に相当します。 `<attributes enabled="true"> <include>identity.*</include> </attributes>`
`parameterGroups.customParameters.enabled`	`attributes.include`
`parameterGroups.customParameters.ignore`	`attributes.exclude`
`parameterGroups.requestHeaderParameters.enabled`	`attributes.include` `<attributes> <include>request.parameters.*</include> </attributes>` すべてのリクエストパラメーターを含みます。
`parameterGroups.requestHeaderParameters.ignore`	`attributes.exclude` `<attributes> <exclude>request.parameters.specificRequestParameter</exclude> </attributes>`
`parameterGroups.responseHeaderParameters.*`	なし
`requestParameters.enabled`	`attributes.include` `<attributes> <include>request.parameters.*</include> </attributes>` すべてのリクエストパラメーターを含みます。
`requestParameters.ignore`	`attributes.exclude` `<attributes> <exclude>request.parameters.specificRequestParamter</exclude> </attributes>`
`analyticsEvents.*`	`transactionEvents.` `analyticsEvents.`のすべての子構成要素と属性も`transactionEvents.`に存在し、非推奨の`transactionEvents.maximumSamplesPerMinute`オプションを除いて同じ意味を持ちます。さらに、 `transactionEvents.attributes`を使用すると、トランザクションイベントでのカスタム属性の包含と除外をより細かく制御できます。
`transactionTracer.captureAttributes`	`transactionTracer.attributes.enabled` `transactionTracer.attributes.include`/ `exclude`を使用すると、トランザクション追跡に含めるカスタム属性をより細かく制御できます。
`errorCollector.captureAttributes`	`errorCollector.attributes.enabled` `errorCollector.attributes.include`/ `exclude`を使用すると、エラーイベントに含めるカスタム属性をより細かく制御できます。
`browserMonitoring.captureAttributes`	`browserMonitoring.attributes.enabled` `browserMonitoring.attributes.include`/ `exclude`では、データに含めるカスタムアトリビュートをより細かく制御できます。
`errorCollector.ignoreErrors`	`errorCollector.ignoreClasses` 詳しくは、エラー収集設定のドキュメントを参照してください。
`transactionEvents.maximumSamplesPerMinute`	なしこの構成要素は、エージェントで使用されていませんでした。

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

.NETエージェント8.xから9.xへの移行ガイド

デフォルトで有効な分散型トレーシング.css-21sua1{background:none;border:none;width:0;padding:0;}

ヒント

非推奨のパブリックエージェントAPIメソッドの削除

ヒント

重要

例

CreateDistributedTracePayload

AcceptDistributedTracePayload

AddCustomParameter

非推奨のエージェント設定の削除

デフォルトで有効な分散型トレーシング