본문으로 건너뛰기

.NET Framework Agent

  • exem-dotnetfw-agent는 .NET Framework 애플리케이션의 트랜잭션, SQL, 예외, 외부 호출, 성능 정보를 수집하여 서버로 전송하는 에이전트입니다.

  • 이 에이전트는 애플리케이션 코드에 별도 SDK 초기화 코드를 넣는 방식이 아니라, CLR Profiler를 통해 대상 프로세스에 자동으로 진입하는 구조를 사용합니다. 여기서 profiler는 실제 배포 및 등록 기준으로 Exem.DotNetFw.Profiler.x86.dll, Exem.DotNetFw.Profiler.x64.dll을 의미합니다. 설치 후 대상 서비스가 시작되면 profiler가 자동으로 로드되고, 런타임에 모니터링 대상 메서드가 실행될 때 에이전트 메서드가 호출되도록 연결됩니다.

  • 핵심적으로 보면 이 에이전트는 다음 두 단계로 이해할 수 있습니다.

  1. 프로세스 시작 시 profiler가 자동으로 붙는다.
  2. 이후 Exem.DotNetFw.Agent가 이벤트를 받아 데이터를 수집하고 서버로 전송합니다.
  • Exem.DotNetFw.Agent 의 실제 시작 시점이 첫 유효 모니터링 이벤트 이후로 지연될 수 있습니다. 그래서 사용자 입장에서는 "프로세스에는 이미 붙어 있지만, 특정 메서드가 호출되어야 본격 동작하는 것처럼" 보일 수 있고, 이 부분은 java agent와 차이가 있습니다.
  • 이유는 profiler가 붙는 시점이 agent를 바로 실행하기에는 너무 빠르기 때문입니다. profiler는 CLR 초기 구간에 먼저 로드되지만, 이 시점에는 아직 어플리케이션이 런타임 컨텍스트가 완전히 형성되지 않았을 수 있습니다. java agent의 경우 premain() 에서 바로 초기화가 시작되는데 이 때에는 이미 java 로직을 실행 시킬 수 있습니다.
  • 따라서 실제 트랜잭션이나 유효한 모니터링 이벤트가 한 번 발생해 agent 메서드가 호출될 때, Exem.DotNetFw.Agent 를 초기화하도록 되어 있습니다.

지원 환경​

  • 윈도우에서 .NET Framework 4.5 이상으로 동작하는 ASP.NET 어플리케이션

한눈에 보는 구조​

.NET Framework 에이전트는 크게 3개 구성 요소로 나뉜다.

구성 요소역할동작 시점
Exem.DotNetFw.Service설치, 운영 제어, 대상 서비스 환경변수 설정설치/적용 시
Exem.DotNet.ProfilerExem.DotNetFw.Profiler.x86.dll, Exem.DotNetFw.Profiler.x64.dll로 배포되며, CLR 진입, 메서드 IL 수정, 에이전트 메서드 호출 연결 담당대상 프로세스 시작 시
Exem.DotNetFw.AgentExem.DotNetFw.Agent.dll로 배포되며, 트랜잭션/SQL/예외/성능 수집 및 서버 전송 담당첫 유효 모니터링 이벤트 이후
  • profiler는 프로세스 시작 시 붙어서 메서드 실행 흐름에 진입할 준비를 합니다.
  • Exem.DotNetFw.Agent는 실제 데이터를 만들고 서버로 보낸다.

구성 요소​

1. Exem.DotNetFw.Service​

설치와 운영 제어를 담당하는 Windows Service입니다.

주요 역할:

  • profiler DLL 등록
  • 대상 서비스 목록 로드
  • 대상 서비스 레지스트리에 profiler 환경변수 설정
  • agent 적용/해제 시 운영 설정 반영

2. Exem.DotNet.Profiler​

CLR이 로드하는 profiler입니다. 실제 DLL은 Exem.DotNetFw.Profiler.x86.dll, Exem.DotNetFw.Profiler.x64.dll입니다.

주요 역할:

  • 대상 프로세스 시작 시 CLR profiler로 진입
  • 설정 파일을 읽어 모니터링 대상 메서드 결정
  • 메서드 IL 수정
  • 메서드 시작, 종료, 예외 시점에 에이전트 메서드가 호출되도록 연결

3. Exem.DotNetFw.Agent​

실제 수집과 전송을 담당하는 컴포넌트입니다. 실제 DLL은 Exem.DotNetFw.Agent.dll입니다.

주요 역할:

  • HTTP, SQL, 예외, 외부 호출 이벤트 처리
  • Agent ID 식별
  • 설정 로드 및 리로드
  • 서버 연결 및 송수신
  • 주기적 상태/성능 전송

설치 및 적용 절차​

설치 과정은 단순 파일 복사가 아니라, 대상 .NET Framework 서비스가 다음 기동부터 profiler를 자동 로드하도록 운영 환경을 구성하는 과정입니다.

1. 에이전트 파일 배치​

일반적으로 다음 항목이 포함됩니다.

  • Exem.DotNetFw.Agent.dll
  • Exem.DotNetFw.Profiler.x86.dll
  • Exem.DotNetFw.Profiler.x64.dll
  • 설정 파일(cfg)
  • 설치 스크립트 및 운영 도구

2. 에이전트 서비스 실행​

Exem.DotNetFw.Service가 실행되면 agent 홈 경로를 기준으로 필요한 파일을 준비하고 profiler 등록 여부를 확인합니다.

3. profiler DLL 등록​

서비스는 regsvr32를 통해 Exem.DotNetFw.Profiler.x86.dll, Exem.DotNetFw.Profiler.x64.dll을 등록합니다. 이 단계는 CLR이 profiler COM 객체를 인식하기 위해 필요합니다.

4. 대상 서비스 지정​

cfg/service.target 파일에 profiler를 적용할 대상 Windows Service 목록을 기록합니다.

5. profiler 환경변수 설정​

대상 서비스 레지스트리 Environment 항목에 아래 값을 추가합니다.

  • COR_ENABLE_PROFILING
  • COR_PROFILER

이 설정이 있어야 대상 서비스가 다음 시작 시 profiler를 자동 로드합니다.

6. 대상 서비스 재기동​

이미 실행 중인 프로세스에는 새 설정이 즉시 반영되지 않으므로, 보통 대상 서비스 재시작이 필요합니다.

동작 원리​

이 에이전트의 기본 원리는 아래와 같습니다.

  1. 대상 프로세스 시작 시 profiler 자동 부착
  2. profiler가 메서드 IL 수정
  3. 수정된 메서드가 실행되면서 에이전트 메서드 호출
  4. Exem.DotNetFw.Agent가 이벤트를 받아 데이터 수집 및 서버 전송

1. profiler 자동 부착​

대상 .NET Framework 프로세스가 시작되면 CLR은 환경변수를 확인하고 등록된 profiler DLL(Exem.DotNetFw.Profiler.x86.dll 또는 Exem.DotNetFw.Profiler.x64.dll)을 로드합니다.

2. 메서드 IL 수정​

profiler는 설정 파일(x.advice, x.advice.callback)을 읽고 모니터링 대상 메서드를 결정한 뒤, 해당 메서드의 IL을 수정합니다.

이 수정의 목적은 다음과 같습니다.

  • 메서드 시작 시 에이전트 메서드 호출
  • 메서드 종료 시 에이전트 메서드 호출
  • 예외 발생 시 에이전트 메서드 호출

3. agent 메서드 호출로 연결​

삽입된 호출은 런타임에 agent 메서드를 호출하는 방식으로 연결됩니다. 이 단계에서 profiler가 감지한 메서드 실행 이벤트가 Exem.DotNetFw.Agent로 전달됩니다.

4. Exem.DotNetFw.Agent 동작​

agent 메서드가 호출되면 현재 프로세스가 수집 대상인지, Exem.DotNetFw.Agent를 초기화할 수 있는 상태인지, 초기 설정 교환 중인지 등을 확인한 뒤 실제 수집 로직을 수행합니다.

조건이 맞으면 Exem.DotNetFw.Agent가 초기화되고, 이때부터 설정 로드, 서버 연결, 주기 작업 시작이 진행됩니다.

운영 시 유의사항​

  • 설정 반영 후 대상 서비스 재기동이 필요할 수 있습니다.
  • 프로세스 시작 직후에는 profiler는 붙어 있어도 서버 연결이 아직 보이지 않을 수 있습니다.

FAQ​

  • Q. 애플리케이션 코드 수정이 필요한가?

    • 일반적으로 직접 SDK 초기화 코드를 넣지 않아도 됩니다. profiler 기반으로 자동 부착됩니다.

  • Q. 이 에이전트는 언제부터 서버로 데이터를 보내는가?

    • 현재 구조상 첫 유효 모니터링 이벤트 이후 Exem.DotNetFw.Agent가 시작되면서 서버 연결과 데이터 전송이 본격화될 수 있습니다.

  • Q. profiler가 붙었다는 것과 agent가 바로 전송을 시작한다는 것은 같은 의미인가?

    • 아닙니다. profiler 부착이 먼저이고, 실제 Exem.DotNetFw.Agent 시작은 그보다 늦을 수 있습니다.

  • Q. IIS 관리자 화면에서 다시 시작하면 안 되는 이유는 무엇인가?

    • 현재 구조에서 profiler 관련 환경변수는 w3wp.exe에 직접 주입되는 것이 아니라cfg/service.target 대상 서비스(WAS, W3SVC)의 Environment에 기록됩니다.
    • 따라서 IIS 관리자 화면의 다시 시작이 실제로 WAS/W3SVC 서비스 재시작이 아니라앱풀 recycle 또는 worker process(w3wp.exe) 재생성 수준으로만 동작하면,서비스가 환경변수를 다시 읽지 않아 profiler가 기대대로 붙지 않을 수 있습니다.
    • 즉 이 프로젝트에서 중요한 것은 w3wp.exe만 다시 뜨는 것이 아니라 profiler 환경변수를 보유한 대상 서비스가 다시 시작되어 새 w3wp.exe가 그 환경을 상속받는 것입니다.
    • 운영 중 profiler 재부착이 필요하면 단순 앱풀 recycle보다 iisreset,IIS 관리자 서버 노드의 전체 다시 시작, 또는 WAS/W3SVC 서비스 재시작을 우선적으로 고려하는 것이 안전합니다.