必要な .NET エージェント環境変数について

当社の .NET エージェントは .NET CLR プロファイラーであり、アプリの環境変数に依存して .NET アプリを New Relic に接続します。.NET エージェントが使用する環境変数の詳細については、以下のセクションを参照してください。

規約概要

このページで使用されている用語を理解するためのヒントを次に示します。

• ".NET Core" は、.NET バージョン (および .NET バージョンでビルドされたアプリケーション、.NET バージョン用にビルドされたアプリケーション) 5.0 以降 (単に ".NET")、および .NET Core 2.0 から 3.1 を指します。
• 「プロファイラー」とは、.NET プロファイリング API を実装するエージェントのコンポーネントを指します。正しく構成されている場合、CLR はプロファイラーを .NET アプリケーションにアタッチします。その後、プロファイラーは残りのエージェントをアプリケーションに読み込みます。

.NET エージェントによる環境変数の使用方法

当社の .NET エージェントは .NET CLR プロファイラー であり、.NET プロファイリング API のサブセットを実装しています。.NET ランタイムに、プロセスをプロファイリングする必要があること、およびどのプロファイラーを使用するかを伝えるために、特定の環境変数が .NET プロセスの環境に存在する必要があります。追加の環境変数は、.NET エージェント自体がインストールされている場所と方法を知らせるために使用されます。

.NET エージェントを使用するには、次の環境変数が必要です。

• プロファイリングを有効にして正しいプロファイラーを特定する
• プロファイラーにエージェントの残りの場所を伝える

プロファイリングを有効にして正しいプロファイラーを識別するための変数

プロファイリングを有効にするかどうか、およびどのプロファイラーを使用するかを .NET ランタイムに指示するために使用される 3 つの環境変数のセット ( COR_ENABLE_PROFILING 、 COR_PROFILER 、およびCOR_PROFILER_PATH ) があります。これらの変数の名前とそれぞれの正しい値は、アプリケーションが .NET Framework 用に構築されているか、.NET Core 用に構築されているかによって異なります。

.NET Framework アプリケーションの場合:

COR_ENABLE_PROFILING アプリケーションのプロファイリングを有効にするかどうかをランタイムに指示します。プロファイリングを有効にするには 1 に設定し、無効にするには 0 に設定します。

COR_PROFILER 使用するプロファイラーをランタイムに指示します。値は、特定のプロファイラーに固有の GUID です。.NET Framework 用の New Relic のプロファイラーの場合、正しい値は {71DA0A04-7777-4EC6-9643-7D28B46A8A41}です。

COR_PROFILER_PATH システム上のプロファイラーを見つける場所をランタイムに指示し、インストールの種類とプラットフォームに依存します。エージェントが MSI インストーラーを使用してインストールされた場合、これは必要ない可能性があることに注意してください。MSI インストーラーは、 COR_PROFILERで設定された GUID に基づいてプロファイラー DLL をシステムに登録します。ただし、値が正しいパスに設定されている限り、とにかく設定しても安全です。

典型的な値:

COR_ENABLE_PROFILING=1
COR_PROFILER={71DA0A04-7777-4EC6-9643-7D28B46A8A41}
COR_PROFILER_PATH="C:\Program Files\New Relic\.NET Agent\netframework\NewRelic.Profiler.dll"

.NET Core アプリケーションの場合:

CORECLR_ENABLE_PROFILING アプリケーションのプロファイリングを有効にするかどうかをランタイムに指示します。プロファイリングを有効にするには 1 に設定し、無効にするには 0 に設定します。

CORECLR_PROFILER 使用するプロファイラーをランタイムに指示します。値は、特定のプロファイラーに固有の GUID です。.NET Core 用の New Relic のプロファイラーの場合、正しい値は {36032161-FFC0-4B61-B559-F6C5D41BAE5A}です。

CORECLR_PROFILER_PATH システム上のプロファイラーの場所をランタイムに伝えます。

典型的な値:

CORECLR_ENABLE_PROFILING=1
CORECLR_PROFILER={36032161-FFC0-4B61-B559-F6C5D41BAE5A}
CORECLR_PROFILER_PATH="C:\Program Files\New Relic\.NET Agent\netcore\NewRelic.Profiler.dll"

注: .NET エージェント プロファイラーの動作は、.NET Framework と .NET Core の間で若干異なります。.NET Framework の場合、.NET Framework プロセスの環境でプロファイリングが有効になっている場合でも、次の条件のいずれかが満たされる場合にのみ、エージェントによってインストルメントされます。

• アプリケーションは IIS でホストされます。(a) アプリケーション プールがデフォルトでインストルメントされるように構成されているか、(b) アプリケーションをホストしているアプリケーション プールが明示的にインストルメントされるように構成されています。
• アプリケーションは、システム全体の newrelic.config ファイルに組み込まれるように明示的に構成されています
• AgentEnabled="true" アプリローカルのnewrelic.configファイルに設定されます

ただし、.NET エージェントの場合、環境内でCORECLR_ENABLE_PROFILINGが 1 に設定されているプロセスはすべて、エージェントによって計測されます。したがって、この環境変数をシステム全体で1に設定することはお勧めしません。過剰なシステム リソースの消費や、予想よりも多くのデータが New Relic に送信される可能性があるからです。代わりに、インストルメント化するプロセスの環境でのみ、この変数を1に設定してください。

残りの .NET エージェントがどこにあるかをプロファイラーに伝える変数

.NET ランタイムがプロファイラーを見つけてアプリケーションにアタッチする方法を認識したので、バイナリ (DLL) コンポーネントと構成 (XML) コンポーネントの両方を含む残りのエージェント アセットを見つけるために、他の環境変数が必要になります。これらの変数は、エージェントの残りの部分でも使用されます。

注: インストール シナリオによっては、これらの変数の一部のみが必要になります。

NEWRELIC_HOME

この変数:

• エージェントの .NET Framework バージョンでのみ使用されます
• エージェント構成資産 (newrelic.config および extensions サブフォルダー内の計測 XML ファイル) を検索するために使用されます
• 構成資産と同じ場所にインストールされている場合、エージェントのバイナリ資産を見つけるために使用できます

注: MSI インストーラーを使用してエージェントをインストールする場合、MSI はレジストリ キー (HKEY_LOCAL_MACHINE\Software\New Relic\.NET Agent\NewRelicHome) にも正しい値を設定するため、この変数を設定する必要がない場合があります。設定されている場合、環境変数が優先されます。

CORECLR_NEWRELIC_HOME

この変数は次のとおりです。

• エージェントの .NET Core バージョンでのみ使用されます
• エージェント構成資産 ( extensions サブフォルダー内のnewrelic.config および計測 XML ファイル) を検索するために使用されます
• 構成資産と同じ場所にインストールされている場合、エージェントのバイナリ資産を見つけるために使用できます

注: この変数は、エージェントの .NET Core バージョンに対して常に設定する必要があります。

NEWRELIC_INSTALL_PATH

この変数は主に次の場合に使用されます。

• エージェントの .NET バージョンと .NET Core バージョンの両方がシステムに並行してインストールされている場合
• エージェントのバイナリ コンポーネントが、構成アセットとは異なるシステム上の場所にインストールされている場合
• エージェントが MSI インストーラーを使用して Windows にインストールされている場合 (上記の両方を実行します)

この変数はディレクトリ/フォルダーに設定され、プロファイラーがエージェントCore.dllを見つけるために使用します。この変数で指定されたパスにNewRelic.Agent.Core.dllファイルが含まれている場合、それが使用されます。Core.dllが見つからない場合、プロファイラーは指定されたパスにnetframeworkまたはnetcoreを追加し、その場所でCore.dllを検索します。それでもCore.dll見つからない場合、プロファイラーは、 NEWRELIC_HOME (.NET Framework) またはCORECLR_NEWRELIC_HOME (.NET Core) での検索に戻ります。

この変数は、 extensions サブフォルダからインストルメンテーション拡張バイナリをロードするためにエージェントによっても使用されます。この変数が設定されると、エージェントは常に netframework または netcore をこの変数の値に追加します。設定されていない場合、エージェントは NEWRELIC_HOME\extensions (.NET Framework) または CORECLR_NEWRELIC_HOME\extensions (.NET Core) での検索に戻ります。

一般的な設置シナリオの値

MSI インストーラー (Windows)

MSI はほとんどすべてのことを自動的に行うので使いやすいですが、背後で行っていることは複雑です。MSI インストーラーは、エージェントのさまざまな部分をシステムのさまざまな場所に配置します。デフォルトでは、バイナリ エージェント アセットを C:\Program Files\New Relic\.NET Agent に配置し、構成アセットを C:\ProgramData\New Relic\.NET Agentに配置します。これは、権限のないユーザーが ProgramData ではファイルにアクセス/編集できるが、 Program Filesではできないというシナリオをサポートするためのものです。MSI インストーラーは、エージェントのフレームワーク バージョンとコア バージョンの両方を並べてインストールします。MSI インストーラーは、上記で説明したように、必要な環境変数の一部を明示的に設定する必要のない多数のレジストリ キーも設定します。

MSI インストーラーを使用するときにカスタム インストール パスを指定しないと仮定すると、これらは正しい環境変数の値です。

.NET Framework アプリケーションの場合:

COR_ENABLE_PROFILING=1
COR_PROFILER={71DA0A04-7777-4EC6-9643-7D28B46A8A41}
COR_PROFILER_PATH="C:\Program Files\New Relic\.NET Agent\netframework\NewRelic.Profiler.dll" # may not be necessary due to profiler being registered with the system
NEWRELIC_INSTALL_PATH="C:\Program Files\New Relic\.NET Agent"
NEWRELIC_HOME="C:\ProgramData\New Relic\.NET Agent" # may not be necessary due to registry key being set

.NET Core アプリケーションの場合:

CORECLR_ENABLE_PROFILING=1
CORECLR_PROFILER={36032161-FFC0-4B61-B559-F6C5D41BAE5A}
CORECLR_PROFILER_PATH="C:\Program Files\New Relic\.NET Agent\netcore\NewRelic.Profiler.dll"
NEWRELIC_INSTALL_PATH="C:\Program Files\New Relic\.NET Agent"
CORECLR_NEWRELIC_HOME="C:\ProgramData\New Relic\.NET Agent"

ZIP アーカイブ (Windows)

Windows 用エージェントの ZIP アーカイブには、エージェントのフレームワーク バージョンとコア バージョンの両方が隣り合ったディレクトリに含まれています。CUSTOM_AGENT_PATHシステム上でアーカイブを解凍する場所のパスに置き換えます。

.NET Framework アプリケーションの場合:

COR_ENABLE_PROFILING=1
COR_PROFILER={71DA0A04-7777-4EC6-9643-7D28B46A8A41}
COR_PROFILER_PATH="CUSTOM_AGENT_PATH\netframework\NewRelic.Profiler.dll"
NEWRELIC_HOME="CUSTOM_AGENT_PATH\netframework"

.NET Core アプリケーションの場合:

CORECLR_ENABLE_PROFILING=1
CORECLR_PROFILER={36032161-FFC0-4B61-B559-F6C5D41BAE5A}
CORECLR_PROFILER_PATH="CUSTOM_AGENT_PATH\netcore\NewRelic.Profiler.dll"
CORECLR_NEWRELIC_HOME="CUSTOM_AGENT_PATH\netcore"

Linux パッケージ

Linux インストール パッケージ (.deb または .rpm、Linux ディストリビューションに応じて)、.NET Core の .NET エージェントをインストールします。デフォルトでは、すべてが/usr/local/newrelic-dotnet-agentにインストールされます。

CORECLR_ENABLE_PROFILING=1
CORECLR_PROFILER={36032161-FFC0-4B61-B559-F6C5D41BAE5A}
CORECLR_PROFILER_PATH="/usr/local/newrelic-dotnet-agent/libNewRelicProfiler.so"
CORECLR_NEWRELIC_HOME="/usr/local/newrelic-dotnet-agent"

Linux に手動でインストールするためのエージェントの .tar.gz アーカイブもあります。その場合、 /usr/local/newrelic-dotnet-agent 、上記の変数でシステム上のアーカイブを解凍した場所に置き換えます。

NewRelic.Agent NuGet パッケージ

アプリケーションのプロジェクトに追加されると、NewRelic.Agent NuGet パッケージによってエージェントがアプリケーションのnewrelicサブディレクトリに追加されます。アプリケーションの種類に応じて、.NET Framework または .NET Core 用の正しいバージョンのエージェントが追加されます。Windows と Linux の両方のプロファイラーが追加されます。これには、Windows プロファイラーの 64 ビット バージョンと 32 ビット バージョンの両方、Linux プロファイラーの x64 バージョンと arm64 バージョンが含まれます。アプリケーションがシステムにデプロイされる場所のプレースホルダーとして<YOUR_APPLICATION_PATH>を使用すると、これらは正しい環境変数値になります。

.NET Framework アプリケーション (64 ビット) の場合:

COR_ENABLE_PROFILING=1
COR_PROFILER={71DA0A04-7777-4EC6-9643-7D28B46A8A41}
COR_PROFILER_PATH="<YOUR_APPLICATION_PATH>\newrelic\NewRelic.Profiler.dll"
NEWRELIC_HOME="<YOUR_APPLICATION_PATH>\newrelic"

.NET Framework アプリケーション (32 ビット) の場合:

COR_ENABLE_PROFILING=1
COR_PROFILER={71DA0A04-7777-4EC6-9643-7D28B46A8A41}
COR_PROFILER_PATH="<YOUR_APPLICATION_PATH>\newrelic\x86\NewRelic.Profiler.dll"
NEWRELIC_HOME="<YOUR_APPLICATION_PATH>\newrelic"

.NET Core アプリケーション (Windows) の場合:

CORECLR_ENABLE_PROFILING=1
CORECLR_PROFILER={36032161-FFC0-4B61-B559-F6C5D41BAE5A}
CORECLR_PROFILER_PATH="<YOUR_APPLICATION_PATH>\newrelic\NewRelic.Profiler.dll"
CORECLR_NEWRELIC_HOME="<YOUR_APPLICATION_PATH>\newrelic"

.NET Core アプリケーション (Linux、x64) の場合:

CORECLR_ENABLE_PROFILING=1
CORECLR_PROFILER={36032161-FFC0-4B61-B559-F6C5D41BAE5A}
CORECLR_PROFILER_PATH="<YOUR_APPLICATION_PATH>/newrelic/libNewRelicProfiler.so"
CORECLR_NEWRELIC_HOME="<YOUR_APPLICATION_PATH>/newrelic"

.NET Core アプリケーション (Linux、arm64) の場合:

CORECLR_ENABLE_PROFILING=1
CORECLR_PROFILER={36032161-FFC0-4B61-B559-F6C5D41BAE5A}
CORECLR_PROFILER_PATH="<YOUR_APPLICATION_PATH>/newrelic/linux-arm64/libNewRelicProfiler.so"
CORECLR_NEWRELIC_HOME="<YOUR_APPLICATION_PATH>/newrelic"

IISでホストされるアプリケーションの環境変数を設定する

アプリケーションがIISでホストされている場合、システム全体の環境変数として設定する代わりに（またはそれに加えて）、IISのApplicationHost.configファイルを直接編集することで、アプリケーションプールごとに環境変数を設定できます。これは、マシンのすべてのプロセスに対してではなく、特定のアプリケーションプールに対してのみ.NETエージェントを有効にするか、構成する場合に便利です。

デフォルトでは、ApplicationHost.configはC:\Windows\System32\inetsrv\config\ApplicationHost.configにあります。<applicationPools>セクション内で、アプリケーションプールを表す各<add>要素には<environmentVariables>子要素を含めることができます。この子要素には、そのアプリケーションプールに設定する各環境変数の<add name="..." value="..." />エントリが含まれます。

たとえば、.NETエージェントを有効にし、TestApplicationという名前のアプリケーションプールのいくつかの一般的な設定オプションを設定するには：

<applicationPools>
    <add name="DefaultAppPool" />
    <add name="TestApplication" autoStart="true" managedRuntimeVersion="v4.0">
        <environmentVariables>
            <add name="COR_ENABLE_PROFILING" value="1" />
            <add name="NEW_RELIC_LICENSE_KEY" value="xxxxxxxx" />
            <add name="NEW_RELIC_APP_NAME" value="MyIisApplication" />
            <add name="NEWRELIC_LOG_LEVEL" value="debug" />
            <add name="NEW_RELIC_APPLICATION_LOGGING_FORWARDING_ENABLED" value="true" />
        </environmentVariables>
    </add>
    <applicationPoolDefaults managedRuntimeVersion="v4.0">
        <processModel identityType="ApplicationPoolIdentity" loadUserProfile="true" setProfileEnvironment="false" />
    </applicationPoolDefaults>
</applicationPools>

また、特定のプールの独自のenvironmentVariables設定によって上書きされない限り、システム全体の環境変数と同様に、デフォルトですべてのアプリケーションプールに適用される環境変数を設定するためにapplicationPoolDefaultsを使用することもできます。

この設定要素の詳細については、applicationPoolDefaults environmentVariablesに関するMicrosoftのドキュメントを参照してください。