본문으로 건너뛰기

.NET Agent 설치하기

exem-dotnet-agent는 Linux 환경의 .NET(CoreCLR) 기반 프로세스의 트랜잭션, SQL, Call Tree, 예외 데이터를 수집하여 ExemONE으로 전송하는 모니터링 에이전트입니다.

지원 환경​

항목지원 범위
OSLinux
런타임.NET Core / .NET 5 이상 (CoreCLR 기반)

설치 방법​

환경에 따라 2가지 설치 방식을 지원합니다.

설치 방식적합 환경특징
On-Premise 설치물리 서버, VM패키지 압축 해제 후 환경 변수 설정
InitContainer 방식Kubernetes애플리케이션 재빌드 없이 initContainer로 설치

On-Premise 설치​

1. 패키지 압축 해제​

패키지(EXEM-DOTNET-AGENT-x.x.x.x)를 서버에 업로드한 후 압축을 해제합니다.

tar.gz인 경우:

tar -xzf EXEM-DOTNET-AGENT-x.x.x.x.tar.gz

zip인 경우:

unzip EXEM-DOTNET-AGENT-x.x.x.x.zip

2. 설정 파일 구성​

압축 해제 후 아래 경로에 설정 파일이 위치합니다.

파일경로용도
net.confexem/dotnet/cfg/agent/net.confReceiver 연결 주소, WAS 이름 등 기본 설정
profile.confexem/dotnet/cfg/profile.conf프로파일러 동작 설정
x.adviceexem/dotnet/cfg/x.advice트랜잭션 시작점 수집을 위한 메서드 weave 설정
x.callback.confexem/dotnet/cfg/x.callback.conf콜백 메서드 설정

net.conf 주요 설정 항목:

설정 항목설명비고
EXEM_GROUP_IDWAS 그룹 ID. 미설정 시 default환경 변수로도 지정 가능
EXEM_RECEIVER_ADDR수집 서버 주소 (IP:포트)환경 변수로도 지정 가능
EXEM_DOTNET_AGENT_NAMEExemONE 화면에 표시될 WAS 이름환경 변수로도 지정 가능

3. 필수 환경 변수 설정​

CoreCLR 프로파일러 활성화를 위해 아래 환경 변수를 설정합니다.

환경 변수설명값 예시
EXEM_DOTNET_HOME에이전트 홈 경로 (exem/dotnet 디렉토리)/opt/exem/dotnet
CORECLR_ENABLE_PROFILINGCoreCLR 프로파일러 활성화 여부1
CORECLR_PROFILER로드할 프로파일러 CLSID{cf0d821e-299b-5307-a3d8-b283c03916dd}
CORECLR_PROFILER_PATHExem.DotNet.Profiler.so 절대 경로$EXEM_DOTNET_HOME/binary/Exem.DotNet.Profiler.so
DOTNET_STARTUP_HOOKS시작 시 선로딩할 Startup Hook DLL 경로$EXEM_DOTNET_HOME/binary/startup/Exem.DotNet.Startup.Hook.dll
EXEM_DOTNET_PROFILE_TARGET_PROCESS모니터링 대상 프로세스(DLL) 이름MyService.dll

방법 1 — 직접 export:

export EXEM_DOTNET_HOME=/opt/exem/dotnet
export CORECLR_ENABLE_PROFILING=1
export CORECLR_PROFILER='{cf0d821e-299b-5307-a3d8-b283c03916dd}'
export CORECLR_PROFILER_PATH="$EXEM_DOTNET_HOME/binary/Exem.DotNet.Profiler.so"
export DOTNET_STARTUP_HOOKS="$EXEM_DOTNET_HOME/binary/startup/Exem.DotNet.Startup.Hook.dll"
export EXEM_DOTNET_PROFILE_TARGET_PROCESS='MyService.dll'

방법 2 — setenv.sh 사용:

패키지에 포함된 setenv.sh에 모니터링 대상 프로세스 이름을 인자로 전달하여 환경 변수를 일괄 적용합니다.

source ./setenv.sh MyService.dll

4. 에이전트 적용 및 기동​

환경 변수를 설정한 상태에서 애플리케이션을 기동합니다. 에이전트는 CoreCLR 프로파일러를 통해 자동 적용됩니다.

cd /opt/apps/myapp
dotnet MyService.dll

InitContainer 방식 (Kubernetes)​

애플리케이션을 재빌드하지 않고 Pod의 initContainer로 에이전트를 설치하는 방법입니다.

에이전트 이미지 명명 규칙: exem-dotnet-agent-inst:x.x.x.x

에이전트 이미지의 /exem 경로에 바이너리, 설정, 로그 디렉토리가 포함되어 있습니다.

1. ConfigMap 생성​

에이전트 설정 파일을 ConfigMap으로 정의합니다.

apiVersion: v1
kind: ConfigMap
metadata:
  name: exem-dotnet-agent-config
  namespace: <네임스페이스>
data:
  net.conf: |
    # 환경 변수로도 지정 가능
    EXEM_RECEIVER_ADDR=<수집서버 IP>:9010

    # 미설정 시 "exem-dotnet-agent"
    # 환경 변수로도 지정 가능
    EXEM_DOTNET_AGENT_NAME=

    # 미설정 시 "default"
    # 환경 변수로도 지정 가능
    EXEM_GROUP_ID=
  calltree.advice: |
    # 추가 콜트리 수집이 필요한 경우 아래 형식으로 작성합니다.
    # classFullName:method signature name

2. Deployment YAML 수정​

기존 Deployment YAML에 아래 항목을 추가합니다.

전체 예시:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: dotnet-k8s-app
  namespace: <네임스페이스>
spec:
  replicas: 1
  selector:
    matchLabels:
      app: dotnet-k8s-app
  template:
    metadata:
      labels:
        app: dotnet-k8s-app
    spec:
      volumes:
        # exem-dotnet-agent 설치 대상 볼륨
        - name: exem-volume
          emptyDir: {}
        # exem-dotnet-agent 설정 파일 볼륨
        - name: config-volume-dotnet-agent
          configMap:
            name: exem-dotnet-agent-config
      initContainers:
        - name: install-exem-dotnet-agent
          image: exem/exem-dotnet-agent-inst:[버전]
          imagePullPolicy: IfNotPresent
          volumeMounts:
            - name: exem-volume
              mountPath: /exem
            - name: config-volume-dotnet-agent
              mountPath: "/exem-config"
              readOnly: true
      containers:
        - name: dotnet-k8s-app
          image: <애플리케이션 이미지>
          imagePullPolicy: Always
          volumeMounts:
            - name: exem-volume
              mountPath: /exem
          env:
            - name: EXEM_DOTNET_HOME
              value: "/exem/dotnet"
            - name: CORECLR_ENABLE_PROFILING
              value: "1"
            - name: CORECLR_PROFILER
              value: "{cf0d821e-299b-5307-a3d8-b283c03916dd}"
            - name: CORECLR_PROFILER_PATH
              value: "$(EXEM_DOTNET_HOME)/binary/Exem.DotNet.Profiler.so"
            - name: DOTNET_STARTUP_HOOKS
              value: "$(EXEM_DOTNET_HOME)/binary/startup/Exem.DotNet.Startup.Hook.dll"
            - name: EXEM_DOTNET_PROFILE_TARGET_PROCESS
              value: "<모니터링 대상 DLL 이름>"
            - name: EXEM_DOTNET_AGENT_NAME
              valueFrom:
                fieldRef:
                  fieldPath: metadata.name
            - name: EXEM_GROUP_ID
              value: "dotnet"
            - name: EXEM_RECEIVER_ADDR
              value: "<수집서버 IP>:9010"
            - name: EXEM_RUN_ON_CONTAINER
              value: "true"
            - name: EXEMWID
              valueFrom:
                fieldRef:
                  fieldPath: metadata.uid

각 항목 설명:

항목설명
volumes.exem-volumeinitContainer와 애플리케이션 컨테이너가 공유하는 Pod 스토리지. 에이전트 파일이 이 볼륨에 복사됩니다
volumes.config-volume-dotnet-agentConfigMap을 볼륨으로 마운트하여 net.conf, calltree.advice 설정을 외부에서 주입합니다
initContainers에이전트 이미지를 initContainer로 기동하여 에이전트 파일을 exem-volume에 복사합니다
containers.volumeMounts애플리케이션 컨테이너가 exem-volume에 마운트하여 에이전트에 접근할 수 있도록 합니다

환경 변수 설명:

환경 변수설명비고
EXEM_DOTNET_HOME에이전트 홈 경로. 고정값: /exem/dotnet
CORECLR_ENABLE_PROFILINGCoreCLR 프로파일러 활성화. 고정값: 1
CORECLR_PROFILER프로파일러 CLSID. 고정값: {cf0d821e-299b-5307-a3d8-b283c03916dd}
CORECLR_PROFILER_PATHExem.DotNet.Profiler.so 경로. $(EXEM_DOTNET_HOME) 참조
DOTNET_STARTUP_HOOKSStartup Hook DLL 경로. $(EXEM_DOTNET_HOME) 참조
EXEM_DOTNET_PROFILE_TARGET_PROCESS모니터링 대상 프로세스(DLL) 이름
EXEM_DOTNET_AGENT_NAMEExemONE 화면에 표시될 WAS 이름
EXEM_GROUP_IDWAS 그룹 ID. 미설정 시 default
EXEM_RECEIVER_ADDR수집 서버 주소 (IP:포트)
EXEM_RUN_ON_CONTAINER컨테이너 환경 동작 여부. 컨테이너: true
EXEMWID컨테이너 연계를 위한 키. EXEM_RUN_ON_CONTAINER=true 설정 시에만 적용