.NET 에이전트는 .NET CLR 프로파일러이며 앱의 환경 변수를 사용하여 .NET 앱을 New Relic과 연결합니다. .NET 에이전트가 사용하는 환경 변수에 대해 자세히 알아보려면 아래 섹션을 참조하십시오.
약관 개요
다음은 이 페이지에서 사용되는 용어를 이해하기 위한 몇 가지 팁입니다.
- ".NET Core"는 .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 런타임에 프로파일링 활성화 여부와 사용할 프로파일러를 알려주는 데 사용되는 세 가지 환경 변수 세트( COR_ENABLE_PROFILING, COR_PROFILER 및 COR_PROFILER_PATH 가 있습니다. 이러한 변수의 이름과 각각의 올바른 값은 애플리케이션이 .NET Framework 또는 .NET Core용으로 빌드되었는지 여부에 따라 다릅니다.
.NET Framework 애플리케이션의 경우:
COR_ENABLE_PROFILING 애플리케이션에 대해 프로파일링을 활성화할지 여부를 런타임에 알려줍니다. 프로파일링을 활성화하려면 1로 설정하고 비활성화하려면 0으로 설정합니다.
COR_PROFILER 사용할 프로파일러를 런타임에 알려줍니다. 값은 지정된 프로파일러에 고유한 GUID입니다. New Relic의 .NET Framework용 프로파일러의 경우 올바른 값은 {71DA0A04-7777-4EC6-9643-7D28B46A8A41}입니다.
COR_PROFILER_PATH 시스템에서 프로파일러를 찾을 위치를 런타임에 알려주고 설치 유형 및 플랫폼에 따라 다릅니다. COR_PROFILER에 설정된 GUID를 기반으로 프로파일러 DLL을 시스템에 등록하는 MSI 설치 프로그램으로 에이전트를 설치한 경우에는 이 작업이 필요하지 않을 수 있습니다. 그러나 값이 올바른 경로로 설정되어 있는 한 어쨌든 설정하는 것이 안전합니다.
일반적인 값:
COR_ENABLE_PROFILING=1COR_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입니다. New Relic의 .NET Core용 프로파일러의 경우 올바른 값은 {36032161-FFC0-4B61-B559-F6C5D41BAE5A}입니다.
CORECLR_PROFILER_PATH 시스템에서 프로파일러를 찾을 위치를 런타임에 알려줍니다.
일반적인 값:
CORECLR_ENABLE_PROFILING=1CORECLR_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 버전에서만 사용됨
- 에이전트 구성 자산(
newrelic.config및extensions하위 폴더의 계측 XML 파일)을 찾는 데 사용됩니다. - 에이전트 바이너리 자산이 구성 자산과 동일한 위치에 설치된 경우 에이전트 바이너리 자산을 찾는 데 사용할 수 있습니다.
참고: 이 변수는 에이전트의 .NET Core 버전에 대해 항상 설정해야 합니다.
NEWRELIC_INSTALL_PATH
이 변수는 주로 다음과 같이 사용됩니다.
- .NET 및 .NET Core 버전의 에이전트가 모두 시스템에 나란히 설치된 경우
- 에이전트의 바이너리 구성 요소가 구성 자산과 다른 시스템 위치에 설치된 경우
- Windows에서 MSI 설치 프로그램으로 에이전트를 설치한 경우(위 두 가지 모두 수행)
이 변수는 디렉터리/폴더로 설정되며 프로파일러에서 에이전트 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 설치 프로그램은 에이전트의 프레임워크 및 Core 버전을 나란히 설치합니다. 또한 MSI 설치 프로그램은 위에서 설명한 대로 일부 필수 환경 변수를 불필요하게 명시적으로 설정하도록 여러 레지스트리 키를 설정합니다.
MSI 설치 프로그램을 사용할 때 사용자 지정 설치 경로를 지정하지 않는다고 가정하면 올바른 환경 변수 값은 다음과 같습니다.
.NET Framework 애플리케이션의 경우:
COR_ENABLE_PROFILING=1COR_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 systemNEWRELIC_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=1CORECLR_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 아카이브에는 나란히 있는 디렉터리에 에이전트의 Framework 버전과 Core 버전이 모두 포함되어 있습니다. CUSTOM_AGENT_PATH 시스템에서 아카이브의 압축을 풀 때의 경로로 바꿉니다.
.NET Framework 애플리케이션의 경우:
COR_ENABLE_PROFILING=1COR_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=1CORECLR_PROFILER={36032161-FFC0-4B61-B559-F6C5D41BAE5A}CORECLR_PROFILER_PATH="CUSTOM_AGENT_PATH\netcore\NewRelic.Profiler.dll"CORECLR_NEWRELIC_HOME="CUSTOM_AGENT_PATH\netcore"리눅스 패키지
Linux 설치 패키지(.deb 또는 .rpm, Linux 배포판에 맞게) .NET Core용 .NET 에이전트를 설치합니다. 기본적으로 /usr/local/newrelic-dotnet-agent 에 모든 것을 설치합니다.
CORECLR_ENABLE_PROFILING=1CORECLR_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용으로 올바른 버전의 에이전트가 추가됩니다. 64비트 및 32비트 버전의 Windows 프로파일러와 x64 및 arm64 버전의 Linux 프로파일러를 포함하여 Windows 및 Linux용 프로파일러가 추가되었습니다. 애플리케이션이 시스템에 배포될 때마다 <YOUR_APPLICATION_PATH> 자리 표시자로 사용하면 이는 올바른 환경 변수 값입니다.
.NET Framework 애플리케이션(64비트)의 경우:
COR_ENABLE_PROFILING=1COR_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=1COR_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=1CORECLR_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=1CORECLR_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=1CORECLR_PROFILER={36032161-FFC0-4B61-B559-F6C5D41BAE5A}CORECLR_PROFILER_PATH="<YOUR_APPLICATION_PATH>/newrelic/linux-arm64/libNewRelicProfiler.so"CORECLR_NEWRELIC_HOME="<YOUR_APPLICATION_PATH>/newrelic"