제니퍼 에이전트(.net) 설치 및 구성

이 장에서는 제니퍼 닷넷 에이전트의 설치 방법을 설명한다.

닷넷 에이전트 지원버전

지원되는 OS

.NET Framework

.NET Framework를 위한 닷넷 에이전트를 정상적으로 설치할 수 있는 운영체제는 다음과 같다.

클라이언트용 윈도우 버전의 경우 공식적인 기술 지원 대상은 아님.

Windows Server 2003 (SP2): 5.4.0.4 버전의 에이전트를 끝으로 지원 종료.

Windows Server 2008: 5.5.1.11 버전의 에이전트를 끝으로 지원 종료.

.NET Core/5+

.NET Core/5+는 리눅스 운영체제도 지원하는데, 이 경우 .NET Core 2.0 이후의 운영체제를 대상으로 지원한다. 이 목록은 현재 마이크로소프트의 공식 문서에 따라,

Prerequisites for .NET Core on Linux

https://learn.microsoft.com/en-us/dotnet/core/linux-prerequisites?tabs=netcore2x

다음과 같다. (닷넷 버전에 따라 리눅스 지원 운영체제도 바뀌는 점에 유의하자)

에이전트 설치 및 제거

윈도우 운영체제 - 일반 서버 및 클라우드의 단독 가상 머신 환경

설치

제니퍼 닷넷 에이전트의 압축 파일(jennifer-agent-dotnet-[version].zip)을 해제하면 다음의 파일이 생성된다.

윈도우 환경에서 설치를 진행하려면 Installer.exe를 실행할 수 있고, 정상적으로 설치된 경우 다음의 하위 폴더들이 생성된다.

디렉터리 설명

디렉터리

설명

bin/

에이전트 실행 파일이 있는 디렉터리

config/

에이전트가 적용되는 응용 프로그램들의 구성 설정 파일을 보관하는 디렉터리

logs/

에이전트 로그 파일이 있는 디렉터리

utility/

유틸리티 실행 파일이 있는 디렉터리

정상적으로 프로그램의 등록 작업이 완료되었으면 이제 모니터링을 원하는 응용 프로그램을 선택해야 한다. 어떤 응용 프로그램을 모니터링해야 할지 결정했다면 그에 대해 .conf 구성 정보 파일을 만들어야만 제니퍼 닷넷 에이전트가 동작하게 된다. 이 작업은 모니터링을 위한 설정 파일 구성 절을 참조한다.

제거

Installer.exe 실행 시 "/u" 인자를 주면 제거가 된다. (또는 Installer.exe로 설치했을 때 함께 생성된 uninstall.bat 파일을 실행해도 된다.)

> Installer.exe /u
또는
> uninstall.bat

이는 시스템에 등록된 정보만 제거하는 것으로 현재 모니터링 중인 프로세스는 여전히 제니퍼 에이전트의 모듈을 사용 중일 수 있다.

따라서, 기존에 모니터링되고 있는 프로그램이 있다면 프로세스(EXE) 종료 후 다시 실행해야 제니퍼 모듈이 완전하게 내려간다. (예를 들어, IIS 웹 사이트인 경우 반드시 "iisreset" 명령을 실행해야 한다.)

제니퍼 닷넷이 설치된 폴더는 모든 프로세스에서 에이전트 사용이 해제되고 난 후에야 삭제할 수 있다.

만약 삭제가 안된다면 제니퍼 모듈이 올라간 프로세스가 여전히 실행 중인지를 확인하고, 있다면 종료 후 다시 삭제를 시도한다.

새 버전 패치 및 기존 버전으로 롤백

새로운 버전 적용하는 방법

새 버전의 닷넷 에이전트는 제니퍼 콘솔의 "에이전트 업그레이드(http://docs.jennifersoft.com/r/viewer/book/030835299a0ceff3#mng_agentUpgrade)" 메뉴를 이용하면 쉽게 적용할 수 있다. 또는, 다음과 같은 방법으로 직접 설치하는 것도 가능하다.

  1. 새 버전의 Installer.exe 파일을 기존 설치된 디렉터리에 덮어 쓴다.

  2. Installer.exe 파일을 실행해서 새롭게 등록한다.

  3. 이미 모니터링 중인 프로세스(EXE)가 있다면 종료하고 다시 실행해야 새 버전의 에이전트가 적용된다. (예를 들어, IIS의 경우 Recycle을 해야 한다.)

이전 버전으로 롤백하는 방법

/bin 폴더에는 시스템에 설치된 적이 있는 에이전트 설치 파일들이 Installer.[버전번호].exe 형식으로 저장되어 있다. 예를 들어, 5.0.7.0 버전의 제니퍼 닷넷 에이전트를 설치한 적이 있다면 /bin/Installer.5.0.7.0.exe 파일이 있으므로 그 exe 파일을 다시 실행해 주기만 하면 5.0.7.0 버전의 에이전트가 시스템에 등록된다.

등록이 완료되면 반영을 위해 기존 프로세스를 중지하고 다시 실행한다. (예를 들어, IIS의 경우 Recycle을 해야 한다.)

모니터링을 위한 설정 파일 구성

닷넷 에이전트 설치 후 모니터링을 원하는 닷넷 응용 프로그램을 선택해야 한다. 만약 응용 프로그램 유형이 IIS 웹, NT 서비스, COM+에 속한다면 /bin/IISConfigHelper.exe 도구를 이용하여 쉽게 설정할 수 있다. 반면, 그 이외의 독립 실행 응용 프로그램이라면 수작업으로 직접 설정 파일을 구성해야 한다.

IIS 웹 응용 프로그램을 위한 구성 방법

IIS 웹 응용 프로그램은 응용 프로그램 풀(Application Pool) 단위로 작업자 프로세스(w3wp.exe)가 관리된다. 제니퍼 닷넷 에이전트는 w3wp.exe 내부에 활성화되기 때문에 IIS와 마찬가지로 응용 프로그램 풀별로 모니터링 단위를 관리한다.

예를 들어, 다음 화면에는 ".NET 웹 응용 프로그램"이 있는 응용 프로그램 풀이 "cshtml_web", "DefaultAppPool", "Jennifer40.WebSiteTest4"가 등록된 것을 보여준다.

IIS에 등록된 응용 프로그램 풀(Application Pool) 목록

그림에서 보면, ".NET v4.5", ".NET v4.5 Classic"은 등록된 웹 응용 프로그램이 없으므로 제니퍼 닷넷이 설치될 수 없다.

이런 환경에서 /bin/IISConfigHelper.exe 도구를 실행하면 다음과 같이 제니퍼 닷넷이 활성화 가능한 3개의 응용 프로그램 풀 이름을 "IIS" 노드에 보여준다.

제니퍼 닷넷이 설치 가능한 응용 프로그램 풀 목록

설치를 원하는 응용 프로그램 풀을 마우스로 선택하고 우측 버튼을 누르면 "Install" 메뉴가 나오고, 그 메뉴를 선택해서 실행하면 다음 화면과 같이 필수 설정 값들을 채울 수 있는 화면이 나온다.

선택된 응용 프로그램 풀에 제니퍼 닷넷 에이전트를 적용

각각의 값 설정은 다음의 기준을 따른다.

필수 입력 값 설명

필드 명

설명

Jennifer Server

제니퍼 데이터 서버가 설치된 컴퓨터의 IP 주소 또는 DNS 명

Server Port

제니퍼 데이터 서버의 listen_port 값

Domain Id

제니퍼 데이터 서버에 등록된 Domain ID


유효범위: 1 ~ 32767까지의 정수

Start Instance Id

제니퍼 에이전트가 활성화되는 응용 프로그램에 대한 고유 식별자.


데이터 서버에 연결된 모든 에이전트들의 ID는 고유해야 하며 1개의 Domain 당 최대 100개의 Instance 접속이 가능. (100개 이후의 Instance가 설정된 경우 새로운 에이전트는 접속이 거부된다.)


IIS 웹 응용 프로그램의 경우 "Web Garden(웹 가든)" 설정에 따라 여러 개의 w3wp.exe 프로세스가 활성화 될 수 있으므로 범위를 지정하게 된다.

Auto ID

설정하면 에이전트의 Instance ID를 서버로부터 자동 할당이 된다.

Auto Select

IIS 웹 응용 프로그램인 경우에만 옵션이 활성화되며, 이를 선택해 두면 해당 응용 프로그램 풀(Application Pool)에 속한 모든 웹 애플리케이션을 모니터링한다.


이 설정을 해제하면, 하단의 목록 상자에 나열된 웹 애플리케이션 중 원하는 항목을 선택해 모니터링하는 것이 가능하다.

원하는 값을 설정하면 이를 반영하기 위해 반드시 "저장(Save)" 버튼을 눌러준다. 설정된 값은 [에이전트 설치폴더]\config\iis 폴더 하위에 [응용 프로그램 풀].conf 파일로 저장된다.

COM+ 응용 프로그램을 위한 구성 방법

구성 요소 서비스(Component Services)에 등록된 COM+ 응용 프로그램은 크게 2가지 활성화 유형으로 나뉜다.

  1. 라이브러리 활성화: 해당 COM+ 응용 프로그램을 호출하는 프로세스 내에 활성화되는 COM+ 응용 프로그램

  2. 서버 활성화: dllhost.exe 호스팅 프로세스 내에 활성화되는 COM+ 응용 프로그램

라이브러리 활성화는 호출하는 프로세스 내에서 활성화되므로 이런 유형의 COM+ 응용 프로그램을 위한 구성은 필요하지 않다. 하지만, 서버 활성화는 호출 프로세스가 아닌 별도의 dllhost.exe 프로세스 내에서 활성화되므로 이를 모니터링하려면 제니퍼 닷넷 구성 파일을 설정해야 한다.

/bin/IISConfigHelper.exe 도구를 실행하면 자동으로 "서버 활성화"에 속한 COM+ 응용 프로그램 목록만 보여지므로 이 중에서 원하는 항목만 "Install" 메뉴를 통해 구성 파일을 만들어 주면 된다. 가령, 다음의 화면에서는 "MyComponentServer" COM+ 응용 프로그램에 대한 구성 예를 보여준다.

서버 활성화 유형의 COM+ 응용 프로그램에 대한 구성 파일 설정

각 필드에 대한 입력 값은 필수 입력 값 설명에서 설명한 내용과 같다.

서비스 응용 프로그램을 위한 구성 방법

/bin/IISConfigHelper.exe 도구를 실행하면 "NT Service" 노드 하위로 운영체제에 등록된 서비스 프로그램 중 .NET Framework 기반으로 만들어진 응용 프로그램 목록을 나열한다.

아래의 화면은 5개의 (닷넷으로 만들어진) 서비스 프로그램 중에 "RemoteTestService40" 항목에 대해 "Install" 메뉴를 이용하여 구성 파일을 생성한 예를 보여준다.

서비스 응용 프로그램에 대한 구성 파일 설정

역시 각 필드에 대한 입력 값은 필수 입력 값 설명에서 설명한 내용과 같다.

독립 실행형 응용 프로그램을 위한 구성 방법

응용 프로그램이 IIS, COM+, 서비스에 속하지 않고 독립적으로 실행되는 EXE 프로그램이라면 수작업으로 구성 파일을 만들어야 한다. [에이전트설치폴더]/config 폴더에 있는 app_pool.conf 파일을 복사해 [EXE파일명].exe.conf 파일명으로 저장한다.

AOT(Ahead-of-time) 빌드한 바이너리인 경우에는 에이전트가 동작하지 않는다.

저장 후, 필수 입력 값 설명을 참고해 구성 설정을 메모장(notepad.exe)등의 편집기를 이용해 변경한다.

환경 변수 구성

독립 실행형 응용 프로그램을 모니터링하는 경우, 해당 EXE 파일을 실행하기 위한 배치 파일을 만들어 줄 수 있다.

SET COR_ENABLE_PROFILING=1
SET COR_PROFILER={6C7CAF0F-D0E5-4274-A71B-6551761BBDC8}
test.exe

위와 같이 배치 파일을 만드는 것이 가능하다면 전역적으로 설정된 환경 변수를 제거하는 것을 권장한다.

서비스 시작점 등록

독립 실행형 응용 프로그램은 대개의 경우 독자적인 서비스 시작점을 갖게 되는데 이를 모니터링하기 위해서는 관련 설정을 등록해야 한다. 이를 위해 다음과 같은 옵션들을 이용해 .conf 파일에 직접 등록해야 한다.

# TestName.ThreadTest 타입의 threadFunc 메서드를 서비스 시작점으로 선택
profile_service_class = TestName.ThreadTest threadFunc 

# ThisClass 타입의 OneWithArray 메서드를 서비스 시작점으로 선택
# 단, 메서드의 시그니처가 반환값은 없고 인자는 object 배열만 받는 경우로 한정
profile_service_class = ThisClass OneWithArray(System.Object[])System.Void

# TxServerRootNamespace 네임스페이스 하위에 정의된 모든 타입의 메서드 
profile_service_pattern = TxServerRootNamespace.* 

# WebSiteTest.TxServerPMSuper 타입을 상속받은 모든 자식 타입의 메서드
profile_service_super = WebSiteTest.TxServerPMSuper 

# SiteTest.ITxServerProfileTarget 인터페이스를 상속받은 모든 자식 타입의 메서드
profile_service_interface = SiteTest.ITxServerProfileTarget

위의 옵션들은 관리 메뉴에서 서비스 시작점을 등록하는 경우 실제로 에이전트 측에 .conf.server 파일로 저장되는 옵션이며 설정 형식 또한 동일하다.

서비스 시작점을 파악하는 방법은 크게 다음의 3가지로 나뉜다.

배치 잡 유형의 응용 프로그램을 위한 구성 방법

배치 잡(Job) 프로세스는 기본적으로 "독립 실행형 응용 프로그램을 위한 구성 방법"과 같다. 단지, 부가적으로 데이터 서버에 배치 잡을 위한 "도메인"을 구성해야 하고 그 도메인으로 에이전트 측의 .conf 파일을 구성해야 한다.

server_address = ... 데이터 서버 IP 또는 DNS ...
server_port = ... 데이터 서버 포트 ...
domain_id = ... 데이터 서버에 구성한 배치 잡 도메인 ID ...
inst_id = ... 에이전트 ID ...
inst_id_pool = 1

이와 함께 배치 잡 특유의 모니터링을 가능하게 만들기 위한 send_transaction_in_application_thread 옵션 설정 및 서비스 시작 메서드를 application_start_point 옵션에 지정하면 된다.

server_address = 192.168.0.100
server_port = 5000
domain_id = 1000
inst_id = 200
inst_id_pool = 1

send_transaction_in_application_thread = true
application_start_point = ConsoleApp.Program Main

application_start_point 옵션의 구성 방식은 "[네임스페이스.클래스명] [메서드명]"의 형식을 따른다.

설정 파일 없이 모니터링 환경 구성

근래 Kubernetes 등의 컨테이너 운영환경에서는 설치를 하거나 별도의 config 파일을 운영하는 것이 번거롭기 때문에 설정 파일 없이 순수 "환경변수"만으로 동작하는 방식을 에이전트 5.6.2.7 버전부터 지원한다.

이를 위해 환경변수 ARIES_IGNORE_CONF_FILE 값을 "1"로 설정하면 되고, 그외 모든 옵션은 접두사로 "ARIES_"를 붙여 설정하는 것이 가능하다. 따라서 이 모드를 따르는 경우 최소한 다음과 같은 환경변수 설정만으로 에이전트를 적용할 수 있다.

ARIES_SERVER_ADDRESS = 192.168.0.100
ARIES_SERVER_PORT = 5000
ARIES_DOMAIN_ID = 1000
ARIES_INST_ID = 200
ARIES_IGNORE_CONF_FILE = 1

CORECLR_ENABLE_PROFILING = 1
CORECLR_PROFILER = {6C7CAF0F-D0E5-4274-A71B-6551761BBDC8}
CORECLR_PROFILER_PATH = /netagent/bin/libAriesProfiler.so

이렇게 ARIES_IGNORE_CONF_FILE 옵션을 적용하면 이후 제니퍼 콘솔 화면에서 고급 옵션 메뉴를 통해 설정하는 모든 옵션들은 로컬에 config 파일이 없으므로 프로세스 재시작 시 적용되지 않는다.

닷넷 에이전트 적용 및 해제 방법

에이전트 설치를 하고 모니터링을 원하는 응용 프로그램에 대해 설정 파일을 만들었다면 이후 EXE 프로세스를 다시 실행할 때부터 모니터링이 진행된다. (예를 들어, IIS 웹 사이트라면 "iisreset" 명령으로 w3wp.exe를 재시작해준다.)

반대로 닷넷 에이전트 적용을 해제하고 싶다면 설정 파일을 제거한 후 EXE 프로세스를 다시 실행한다. (IISConfigHelper 응용 프로그램에서 제공되는 "Uninstall" 메뉴는 설정 파일만 제거하므로 프로세스 재시작은 별도로 수행해야 한다.)

제니퍼 닷넷 4.x 버전과 달라진 점

제니퍼 닷넷 4.x 버전에서도 IISConfigHelper.exe를 이용해 설치를 했으나 다음과 같은 변경 사항이 있다.

제니퍼 닷넷 4.x 버전에서 마이그레이션 하는 방법

다음의 순서로 마이그레이션을 진행한다.

  1. [제니퍼4.x 설치 폴더]의 uninstall_jennifer.bat 파일을 실행해 4.x 버전을 제거

  2. [제니퍼5 설치 폴더]의 installer.exe 파일을 실행해 5.0 버전을 설치

  3. 구성 정보 파일이 호환되지 않으므로, 기존 4.x 버전의 구성 정보에 따르는 새로운 구성 파일을 IISConfigHelper.exe를 이용해 생성.

리눅스 - .NET Core/5+ 환경

설치

제니퍼 닷넷 에이전트의 압축 파일(jennifer-agent-dotnet-[version].zip)을 해제하면 다음의 파일이 생성된다.

리눅스 환경에서 설치 명령은 agent-setup을 실행하기만 하면 된다.

$ ls -l agent-setup 
-rw-rw-rw-. 1 kevin kevin 3556464 Dec 15 16:21 agent-setup

$ chmode u+x agent-setup

$ ls -l agent-setup
-rwxrw-rw-. 1 kevin kevin 3556464 Dec 15 16:21 agent-setup

[x86_64 환경인 경우]
$ sudo ./agent-setup

[ARM64 환경인 경우]
$ sudo ./agent-setup-arm64

닷넷 에이전트 버전이 5.6.2.1 이하라면 .NET Core 2.2와 3 버전을 기준으로 다음과 같은 명령어를 수행한다.


[.NET Core 2.2 이하]

$ sudo dotnet agent-installer.dll


[.NET Core 3.0 이상]

$ sudo dotnet agent-installer3.dll


(향후 agent-install.dll과 agent-installer3.dll은 삭제될 예정임)

정상적으로 설치된 경우 하위에 다음의 디렉터리들이 생성된다.

디렉터리 설명

디렉터리

설명

bin/

에이전트 실행 파일이 있는 디렉터리

config/

에이전트가 적용되는 응용 프로그램들의 구성 설정 파일을 보관하는 디렉터리

logs/

에이전트 로그 파일이 있는 디렉터리

utility/

유틸리티 실행 파일이 있는 디렉터리

제거

agent-setup 실행 시 "/u" 인자를 주면 제거가 된다.

$ sudo ./agent-setup /u

닷넷 에이전트 버전이 5.6.2.1 이하라면 "dotnet agent-installer.dll" 실행 시 "/u" 인자를 주면 제거가 된다.


[.NET Core 2.2 이하]

$ sudo dotnet agent-installer.dll /u


[.NET Core 3.0 이상]

$ sudo dotnet agent-installer3.dll /u

이는 시스템에 등록된 정보만 제거하는 것으로 현재 모니터링 중인 프로세스는 여전히 제니퍼 에이전트의 모듈을 사용하고 있는 중이다.

따라서, 기존에 모니터링되고 있는 프로그램이 있다면 프로세스 종료 후 다시 실행해야 제니퍼 모듈이 완전하게 내려간다.

새 버전 패치 및 기존 버전으로 롤백

새로운 버전 적용하는 방법

새 버전의 닷넷 에이전트는 제니퍼 콘솔의 "에이전트 업그레이드(http://docs.jennifersoft.com/r/viewer/book/030835299a0ceff3#mng_agentUpgrade)" 메뉴를 이용하면 쉽게 적용할 수 있다. 또는, 다음과 같은 방법으로 직접 설치하는 것도 가능하다.

  1. 새 버전의 jennifer-agent-dotnet-[version].zip에 포함된 내용을 기존 설치된 디렉터리에 덮어 쓴다.

  2. agent-setup 파일을 실행해서 새롭게 등록한다.

  3. 이미 모니터링 중인 프로세스가 있다면 종료하고 다시 실행해야 새 버전의 에이전트가 적용된다.

이전 버전으로 롤백하는 방법

설치 폴더에는 시스템에 설치된 적이 있는 에이전트 설치 파일들이 ./bin.[버전번호] 형식으로 저장되어 있다. 예를 들어, 5.0.7.0 버전의 제니퍼 닷넷 에이전트를 설치한 적이 있다면 /bin.5.0.7.0 디렉터리가 있으므로 bin을 삭제하고 5.0.7.0 버전의 디렉터리를 bin으로 이름 변경하면 된다.

등록이 완료되면 반영을 위해 기존 프로세스를 중지하고 다시 실행한다.

모니터링을 위한 설정 파일 구성

응용 프로그램 모니터링을 위해서는 2가지 작업을 해야 한다. 첫 번째는 conf 파일을 생성하는 것이고, 두 번째는 해당 응용 프로그램에 적용할 환경 변수를 구성하는 것이다.

./config 디렉터리에 conf 파일 생성

이제 어떤 응용 프로그램을 모니터링해야 할지 결정하고 그에 대해 config 디렉터리 내에 응용 프로그램 이름과 대응하는 conf 구성 정보 파일을 만들어야만 제니퍼 닷넷 에이전트가 동작하게 된다. 이때 conf 파일명은 응용 프로그램의 실행 유형에 따라 정해진다. 대표적으로 .NET Core 응용 프로그램은 2가지 유형으로 나뉘는데,

[dotnet 실행 파일에 호스팅되는 경우]
$ dotnet [...net.dll...]

예)
$ dotnet CoreCoreLin.dll
[ELF 실행 파일에 호스팅되는 경우]
$ [...net_elf...]

예)
$ .\CoreCoreLin

첫 번째 유형의 경우 CoreCoreLin.dll.conf 파일로, 두 번째라면 CoreCoreLin.conf 파일로 지정한다. conf 파일의 내용은 app_pool.conf의 내용을 복사해 제니퍼 데이터 서버의 환경에 따른 설정으로 변경해 준다.

server_address = ... 데이터 서버 IP 또는 DNS ...
server_port = ... 데이터 서버 포트 ...
domain_id = ... 데이터 서버에 구성한 배치 잡 도메인 ID ...
inst_id = ... 에이전트 ID ...
inst_id_pool = 1

환경 변수 구성

프로세스에 다음의 환경 변수가 적용되어야 한다.

CORECLR_ENABLE_PROFILING=1
CORECLR_PROFILER={6C7CAF0F-D0E5-4274-A71B-6551761BBDC8}
CORECLR_PROFILER_PATH=libAriesProfiler.so

[ARM64 환경]

CORECLR_PROFILER_PATH=libAriesProfilerARM64.so

만약 shell 파일을 통해 실행하는 닷넷 응용 프로그램이라면 .sh 파일 내에 다음과 같이 export 명령어를 포함한다.

export CORECLR_ENABLE_PROFILING=1
export CORECLR_PROFILER={6C7CAF0F-D0E5-4274-A71B-6551761BBDC8}
export CORECLR_PROFILER_PATH=libAriesProfiler.so

[ARM64 환경]

export CORECLR_PROFILER_PATH=libAriesProfilerARM64.so

대개의 경우 리눅스에서 구동하는 .NET Core 웹 응용 프로그램은 /etc/systemd/system 디렉터리에 service 파일로 등록되었을 텐데, 이런 경우에는 service 파일 내에 다음과 같이 환경 변수 구성을 추가한다.

[Service]
WorkingDirectory=/home/tusr/corecorelin
ExecStart=/usr/share/dotnet/dotnet /home/tusr/corecorelin/CoreCoreLin.dll
KillSignal=SIGINT
SyslogIdentifier=dotnet-corecorelin
Environment=CORECLR_ENABLE_PROFILING=1
Environment=CORECLR_PROFILER={6C7CAF0F-D0E5-4274-A71B-6551761BBDC8}
Environment=CORECLR_PROFILER_PATH=libAriesProfiler.so

데몬으로 실행되는 경우, 데몬이 구동되는 서비스 계정이 닷넷 에이전트의 설치 디렉터리를 접근할 수 있는 권한이 있어야 한다.


또한 ARM64 환경에서는 so 파일의 경로를 다음과 같이 설정한다.


Environment=CORECLR_PROFILER_PATH=libAriesProfilerARM64.so

리눅스 Docker의 .NET Core/5+ 환경

설치

설치 방법은 크게 다음의 2가지로 나뉜다.

  1. 실행 시 .NET Agent 바이너리가 있는 볼륨과 환경 변수를 지정하는 방법

  2. 기존 .NET Core/5+ 컨테이너들의 Dockerfile에 .NET Agent 바이너리와 환경 변수를 포함하는 방법

첫 번째 방법은 기존 서비스를 위해 구성한 Dockerfile을 변경할 필요가 없다는 장점이 있지만 수작업으로 실행하는 경우가 발생하면 매우 번거로운 명령행을 요구하게 된다. 반면 두 번째 방법을 선택하면 컨테이너를 실행하는 명령어는 간결하지만 기존 배포 프로세스에서 구성한 Dockerfile을 사용자 측에서 수정해야 한다는 단점이 있다.

따라서, 고객사의 상황에 맞게 두 가지 방법 중 하나를 적절하게 선택해 적용해야 한다.

실행 시 docker run에 인자를 추가하는 방법

이를 위해 우선 에이전트의 바이너리가 필요한데 압축 파일(jennifer-agent-dotnet-[version].zip)을 해제해 나온 파일에서,

docker 호스트 머신에 설치할 필요는 없으므로 이번에는 "--unzip" 옵션을 줘 실행한다.

[x86_64 환경인 경우]
$ ./agent-setup --unzip

[ARM64 환경인 경우
$ ./agent-setup-arm64 --unzip

닷넷 에이전트 버전이 5.6.2.1 이하라면 .NET Core 2.2와 3 버전을 기준으로 다음과 같은 명령어를 수행한다.


[.NET Core 2.2 이하]

$ dotnet agent-installer.dll --unzip


[.NET Core 3.0 이상]

$ dotnet agent-installer3.dll --unzip

예를 들어, /opt/jennifer/dotnet 폴더에 압축을 풀었다고 가정하면 다음과 같은 디렉터리 구조를 가진다.

/opt/jennifer/dotnet
├───bin
│   └───net40
├───config
├───extension
│   ├───netcore
│   └───sample
|───logs
|───service_dump
└───utility
    ├───net40
    │   ├───x64
    │   └───x86
    ├───x64
    └───x86

이제 해당 경로를 docker 컨테이너 내에 실행될 닷넷 프로세스에서 사용할 수 있도록 다음과 같은 볼륨 및 환경 변수 설정을 추가해야 한다.

호스트 측에서 컨테이너로 연결해야 할 볼륨

호스트 측 경로

컨테이너 측 경로

설명

/opt/jennifer/dotnet

netagent

호스트 측의 경로는 바뀔 수 있지만 컨테이너 측의 경로는 반드시 "netagent"로 지정

컨테이너로 설정해야 할 환경 변수

환경 변수 이름

값

설명

CORECLR_ENABLE_PROFILING

1

고정값

CORECLR_PROFILER

{6C7CAF0F-D0E5-4274-A71B-6551761BBDC8}

고정값

CORECLR_PROFILER_PATH

/netagent/bin/libAriesProfiler.so

또는,

/netagent/bin/libAriesProfilerARM64.so

고정값

ARIES_DEFAULT_CONF

app_pool.conf

/opt/jennifer/dotnet/conf 디렉터리에 있는 conf 파일 중의 하나를 지정

IgnoreAgentConfigFile

1

만약 여러 개의 컨테이너가 하나의 볼륨을 공유해 모니터링을 한다면 설정

이 방법을 사용하면 기존 docker image를 변경할 필요가 없고 단지 컨테이너를 실행하기 위한 docker run 명령행에 볼륨과 환경 변수를 설정만 하면 된다. 다음은 이에 대한 예제 코드를 보여 준다.

[x86_64 환경인 경우]
$ docker run -v /opt/jennifer/dotnet:/netagent -e CORECLR_ENABLE_PROFILING=1 -e CORECLR_PROFILER={6C7CAF0F-D0E5-4274-A71B-6551761BBDC8} -e CORECLR_PROFILER_PATH=/netagent/bin/libAriesProfiler.so -e ARIES_DEFAULT_CONF=app_pool.conf ...[생략]...

[ARM64 환경인 경우]
$ docker run -v /opt/jennifer/dotnet:/netagent -e CORECLR_ENABLE_PROFILING=1 -e CORECLR_PROFILER={6C7CAF0F-D0E5-4274-A71B-6551761BBDC8} -e CORECLR_PROFILER_PATH=/netagent/bin/libAriesProfilerARM64.so -e ARIES_DEFAULT_CONF=app_pool.conf ...[생략]...

또는, conf 파일을 사용하지 않고 모든 설정을 환경 변수를 통해 전달하는 것도 가능하다.

[x86_64 환경인 경우]
$ docker run -v /opt/jennifer/dotnet:/netagent -e ARIES_DOMAIN_ID=1000 -e ARIES_SERVER_ADDRESS=127.0.0.1 -e IgnoreAgentConfigFile=1 -e ARIES_SERVER_PORT=5000 -e CORECLR_ENABLE_PROFILING=1 -e CORECLR_PROFILER={6C7CAF0F-D0E5-4274-A71B-6551761BBDC8} -e CORECLR_PROFILER_PATH=/netagent/bin/libAriesProfiler.so ...[생략]...

[ARM64 환경인 경우]
$ docker run -v /opt/jennifer/dotnet:/netagent -e ARIES_DOMAIN_ID=1000 -e ARIES_SERVER_ADDRESS=127.0.0.1 -e IgnoreAgentConfigFile=1 -e ARIES_SERVER_PORT=5000 -e CORECLR_ENABLE_PROFILING=1 -e CORECLR_PROFILER={6C7CAF0F-D0E5-4274-A71B-6551761BBDC8} -e CORECLR_PROFILER_PATH=/netagent/bin/libAriesProfilerARM64.so ...[생략]...

.NET Agent가 추가된 container image 파일을 만드는 방법

"docker run"에 인자를 복잡하게 사용하고 싶지 않다면 container image 자체에 .NET Agent를 추가해 만드는 것도 가능하다.

첫 번째 작업으로 에이전트 파일을 container image 내에 복사해야 하는데, 예를 들어 닷넷 설치 모듈을 ZIP 파일로 받은 경우 다음과 같은 절차를 거쳐 image 내에 복사할 수 있다.

RUN apt-get update \
    && apt-get install -y --no-install-recommends unzip \
    && rm -rf /var/lib/apt/lists/*
ADD http://...url.../jennifer-agent-dotnet-5.5.1.5.zip /tmp/agent_latest.zip
WORKDIR /tmp
RUN unzip agent_latest.zip -d extracted
WORKDIR /tmp/extracted

RUN unzip Binaries.zip

RUN cp -r /tmp/extracted /netagent

에이전트 파일이 복사되었으면 이제 남은 작업은 환경 변수만 추가하면 된다.

ENV CORECLR_ENABLE_PROFILING 1
ENV CORECLR_PROFILER {6C7CAF0F-D0E5-4274-A71B-6551761BBDC8}
ENV CORECLR_PROFILER_PATH /netagent/bin/libAriesProfiler.so
ENV ARIES_SERVER_ADDRESS 127.0.0.1
ENV ARIES_SERVER_PORT 5000
ENV ARIES_DOMAIN_ID 1000
ENV ARIES_DEFAULT_CONF app_pool.conf

ARM64 환경의 경우, CORECLR_PROFILER_PATH의 값을 "/netagent/bin/libAriesProfilerARM64.so"로 변경

위와 같이 설정하면 동적으로 인스턴스 ID를 부여받는 반면, 만약 특정 ID를 지정하고 싶다면 ARIES_INST_ID 환경 변수를 하나 더 추가하면 된다.

ENV ARIES_INST_ID 121

AKS(Azure Kubernetes Service) 환경

에이전트 버전 5.6.2.7부터 지원한다.

설치

k8s가 Container에 대한 Orchestrator 도구이기 때문에 설치 방법은 Container 환경과 유사하게 다음의 2가지로 나뉜다.

  1. 실행 시 .NET Agent 바이너리가 있는 PV와 Pod를 연결하고 환경 변수를 지정하는 방법

  2. 기존 .NET Core 컨테이너들의 Dockerfile에 .NET Agent 바이너리와 환경 변수를 포함하는 방법

첫 번째 방법은 기존 서비스를 위해 구성한 Dockerfile을 변경할 필요가 없다는 장점이 있지만 PV/PVC를 준비하고 이를 연결하기 위해 deployment/pod의 yaml 파일을 변경해야 한다. 반면 두 번째 방법을 선택하면 다른 구성은 필요 없지만 기존 배포 프로세스에서 구성한 Dockerfile을 사용자 측에서 수정해야 한다는 단점이 있다.

따라서, 고객사의 상황에 맞게 두 가지 방법 중 하나를 적절하게 선택해 적용해야 한다.

실행 시 PV와 Pod를 연결하고 환경 변수를 지정하는 방법

이를 위해 우선 에이전트의 바이너리가 필요한데 압축 파일(jennifer-agent-dotnet-[version].zip)을 해제해 나온 파일에서,

로컬에 설치할 필요는 없으므로 unzip으로 압축만 해제한다.

$ unzip Binaries.zip

닷넷 에이전트 버전이 5.6.2.1 이하라면 .NET Core 2.2와 3 버전을 기준으로 다음과 같은 명령어를 수행한다.


[.NET Core 2.2 이하]

$ dotnet agent-installer.dll --unzip


[.NET Core 3.0 이상]

$ dotnet agent-installer3.dll --unzip

예를 들어, /opt/jennifer/dotnet 폴더에 압축을 풀었다고 가정하면 다음과 같은 디렉터리 구조를 가진다.

/opt/jennifer/dotnet
├───bin
│   └───net40
├───config
├───extension
│   ├───netcore
│   └───sample
|───logs
|───service_dump
└───utility
    ├───net40
    │   ├───x64
    │   └───x86
    ├───x64
    └───x86

이제 해당 파일을 PV에 복사해야 하는데, 이를 위해 우선 PV 먼저 생성한다.

$ kubectl apply -f https://raw.githubusercontent.com/jennifersoft/jennifer5-aks/main/agent_pv.yaml

위의 yaml 파일은 예제일 뿐, 고객사 환경에 맞게 yaml 파일의 내용을 변경해 적용할 수 있다.

PV가 생성되었으면 "kubectl get pv" 명령을 이용해 "NAME"을 알아내고,

C:\temp> kubectl get pv
NAME                             CAPACITY   ACCESS MODES   ...[생략]...  AGE
pvc-5cef2cb5-a37b-483e-9138-d08ff1ef74d4   1Gi        RWX  ...[생략]...  20h

출력된 NAME을 이용해 PV가 속한 Storage Account를 알아낸 다음,

C:\temp> kubectl describe pv pvc-5cef2cb5-a37b-483e-9138-d08ff1ef74d4
Name: pvc-5cef2cb5-a37b-483e-9138-d08ff1ef74d4
Labels: <none>
...[생략]...
Capacity: 1Gi
Node Affinity: <none>
Message:
Source:
Type: CSI (a Container Storage Interface (CSI) volume source)
Driver: file.csi.azure.com
FSType:
VolumeHandle: mc_testaks_aks-jennifer-demo_koreacentral#f0ae5f59e9e7a4036b1d8cb#pvc-5cef2cb5-a37b-483e-9138-d08ff1ef74d4#
...[생략]...

Azure Storage Explorer와 같은 도구를 이용해 로컬의 "/opt/jennifer/dotnet" 디렉터리를 복사해 둔다.

이곳에서는 "/opt/jennifer/dotnet" 디렉터리에 압축 해제한 내용을 PV로 복사 시 "/extracted" 디렉터리를 만들어 그 하위에 복사한 것으로 가정하고 설명한다.

이제 남은 작업은 deployment를 수행하는 yaml 파일 내에 등록한 container에서 volume을 이용해 연결하고 이때 환경 변수도 함께 구성한다.

apiVersion: apps/v1
kind: Deployment
...[생략]...
spec:
  ...[생략]...
  template:
    ...[생략]...
    spec:
      containers:
        ...[생략]...
        env:
        - name: CORECLR_ENABLE_PROFILING
          value: "1"
        - name: CORECLR_PROFILER
          value: "{6C7CAF0F-D0E5-4274-A71B-6551761BBDC8}"
        - name: CORECLR_PROFILER_PATH
          value: "/extracted/bin/libAriesProfiler.so"
        - name: ARIES_IGNORE_CONF_FILE
          value: "1" 
        - name: ARIES_SERVER_ADDRESS
          value: "127.0.0.1"
        - name: ARIES_SERVER_PORT
          value: "5000"
        - name: ARIES_DOMAIN_ID
          value: "1000"
        - name: ARIES_INST_ID
          value: "-1"
        volumeMounts:
        - mountPath: "/extracted"
          name: volume
      volumes:
        - name: volume
          persistentVolumeClaim:
            claimName: jennifer5-agent-file

ARM64 환경의 경우, CORECLR_PROFILER_PATH의 값을 "/extracted/bin/libAriesProfilerARM64.so"로 변경

Azure App Services 환경

App Services에 올릴 수 있는 .NET Web Application은 크게 다음의 유형으로 나눌 수 있다.

이 중에서 5.4.0.3 버전부터 지원되는 유형은 1번과 2번이고, 3번 유형은 5.5.0.10 버전부터 지원한다.

설치

Azure의 App Services 관리 화면에서 다음과 같이 "Extensions" 메뉴를 선택해 "Add" 버튼을 누른다.

Azure 확장 설치 메뉴

설치할 수 있는 확장 목록 중 "JENNIFER .NET Agent" 항목을 선택해 설치를 진행한다.

JENNIFER .NET Agent 확장 선택

설치가 완료된 후 다시 "App Services" 관리 화면의 "Application Settings" 화면에서 다음의 환경 변수를 등록한다.

환경 변수 설정

변수 이름

값

설명

ARIES_SERVER_ADDRESS

[제니퍼 데이터 서버의 접속 주소]

가변값 (예: 192.168.0.100)

ARIES_SERVER_PORT

[제니퍼 데이터 서버의 접속 포트]

가변값 (예: 5000)

ARIES_DOMAIN_ID

[제니퍼 데이터 서버의 관리 도메인 ID]

가변값 (예: 1000)

ARIES_INST_ID

-1

제니퍼 서버에서 자동 결정

ARIES_IGNORE_CONF_FILE

1

conf 파일 설정 없이 동작

설정 후 App Services를 재시작하면 설정이 반영되어 모니터링이 시작된다.

만약 Azure Web App의 "Scale-Out"을 이용해 인스턴스를 2개 이상 운용하는 경우라면 데이터 서버의 도메인 설정에서 "Instance ID 중복 시 신규 ID 자동 발급" 옵션을 설정한다.

삭제

Azure 관리 화면에서 해당 App Service의 "Extension" 메뉴를 누르면 설치된 제니퍼 에이전트 확장을 선택할 수 있고 "삭제(Delete)" 메뉴를 통해 삭제할 수 있다.

에이전트 삭제 메뉴

단, 이것은 파일만 삭제한 것일 뿐 실행 중인 웹 애플리케이션의 프로세스에서 이를 반영하려면 반드시 App Service를 재시작해야 한다.

업데이트

APM의 제품은 App Service 프로세스에 함께 올라가는 모듈이 있어 파일이 잠기므로 업데이트를 위해서는 기존 버전을 먼저 삭제 후 새로 설치해야 한다. 또한, 삭제 후 새로운 버전으로 설치한 경우에도 반드시 App Service 재시작이 필요하다.

Azure App Service의 "Extensions" 목록에서 "Update" 메뉴를 제공하긴 하지만 모듈이 잠겨 있어 업데이트가 되지 않는다. 반드시 삭제 후 새로 설치해야 한다.

배포 슬롯(Deployment Slot)이 있는 경우

Azure에서 배포 슬롯은 "AppService"와 동일하게 취급된다. 따라서 배포 슬롯을 만들었다면 그곳에도 제니퍼 에이전트를 설치하고 환경 변수를 추가해야 한다.

단지, 그렇게 되면 배포 슬롯의 인스턴스도 활성화되는 부작용이 있는데 이를 막기 위해 "ARIES_ENABLE" 환경 변수를 "0" 값으로 "Deployment slot setting"과 함께 설정해 줄 수 있다.