본문으로 건너뛰기

Python Agent 설치

1. 모듈 설명​

exem-python-agent는 Python 기반 애플리케이션(Django, Flask, FastAPI 등)에서 실행되는 트랜잭션, SQL, Call Tree, 예외 데이터를 수집하여 ExemONE 수집 서버(Receiver)로 전송하는 모니터링 에이전트입니다.

2. 지원 환경​

항목내용
OSLinux
Arch64bit
RuntimePython 3.7 이상
PlatformOn-premise
Docker
Kubernetes
FrameworkDjango WSGI
Django ASGI
Flask
FastAPI (0.95.2 이상 — 지원 가이드 기준)
DBSQLite (sqlite3, pysqlite3)
MySQL (pymysql, MySQLdb)
Oracle (cx_Oracle)
PostgreSQL (psycopg2)
MongoDB (pymongo, motor)
Redis
redis-om
HTTPhttplib (http.client)
urllib3
requests
aiohttp
HTTPX
MessagingKafka (kafka_python, confluent_kafka) — producer · consumer (decorator)
ProtocolTCP 9010 → Receiver
Prereqpip 사용 가능
Django / Flask / FastAPI 중 하나
OtherAPScheduler

3. 통신 포트​

출발지도착지프로토콜포트용도
모니터링 대상 서버 (Python App)ExemONE 수집 서버 (Receiver)TCP9010에이전트-수집서버 통신
노트

모니터링 대상 서버에서 ExemONE 수집 서버 방향으로 9010 포트가 개방되어 있어야 합니다. ver 3.0.7부터 Java Agent와 동일한 TCP 9010 포트를 사용합니다.

4. 설치 방법​

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

설치 방식적합 환경특징
On-Premise 설치물리 서버, VMtar.gz 압축 해제 후 pip 설치
InitContainer 방식Kubernetes애플리케이션 재빌드 없이 initContainer로 설치 (v3.0.18.1+)
Dockerfile Rebuild 방식Kubernetes, DockerDockerfile에 에이전트를 포함하여 이미지 빌드

4-1. On-Premise 설치​

1. 패키지 다운로드​

설치 패키지(EXEM-PYTHON-AGENT-X.X.X.tar.gz)를 서버에 다운로드하거나 직접 업로드합니다.

EXEM-PYTHON-AGENT-[version].tar.gz

2. 압축 해제​

tar -zxvf EXEM-PYTHON-AGENT-[version].tar.gz

압축 해제 후 디렉토리 구조는 아래와 같습니다.

exem/python/
├── cfg/
│ └── agent/
│ ├── pymon.ini # 에이전트 기본 설정 파일
│ └── pymon_extend.ini
├── lib/
│ ├── dependency/ # grpcio, protobuf, psutil 의존 패키지
│ └── exem-python-agent-[version].tar.gz
└── data/

3. 모듈 설치​

exem/python/lib/ 디렉토리의 에이전트 패키지를 pip으로 설치합니다.

cd exem/python/lib
pip install exem-python-agent-[version].tar.gz

의존 패키지(grpcio, grpcio-tools, protobuf, psutil)가 없는 오프라인 환경에서는 dependency/ 폴더의 패키지를 먼저 설치합니다.

pip install dependency/grpcio-1.53.0.tar.gz
pip install dependency/grpcio-tools-1.53.0.tar.gz
pip install dependency/protobuf-4.21.6.tar.gz
pip install dependency/psutil-5.9.8.tar.gz

4. 필수 옵션 설정​

에이전트 기동에 아래 4가지 옵션이 필수입니다.

옵션설명
EXEM_PYTHON_HOME에이전트 설치 경로 (압축 해제한 exem/python 디렉토리)
EXEM_PYTHON_AGENT_NAMEExemONE 화면에 표시될 에이전트 이름
EXEM_GROUP_IDWAS 그룹 ID
EXEM_RECEIVER_ADDRExemONE 수집 서버 주소 (IP:포트)
노트

CURR_TRACE_TXN 옵션의 기본값은 *:3000으로, 3,000ms(3초) 미만 트랜잭션은 수집되지 않습니다. 모든 트랜잭션을 수집하려면 *:0으로 설정하세요.

옵션은 환경변수 또는 기동 옵션 + 설정 파일 두 가지 방식으로 설정합니다.

방법 1 — 환경변수​

4개의 옵션을 모두 환경변수로 설정합니다.

export EXEM_PYTHON_HOME=/exem/python
export EXEM_PYTHON_AGENT_NAME=python-agent
export EXEM_GROUP_ID=python
export EXEM_RECEIVER_ADDR=<수집서버 IP>:9010

방법 2 — 기동 옵션 + 설정 파일​

EXEM_PYTHON_HOME과 EXEM_PYTHON_AGENT_NAME은 에이전트 기동 시 옵션으로 전달하고, EXEM_RECEIVER_ADDR과 EXEM_GROUP_ID는 pymon.ini 설정 파일에 작성합니다.

# exem/python/cfg/agent/pymon.ini
EXEM_GROUP_ID=python
RECEIVER_ADDR=<수집서버 IP>:9010

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

모듈 설치 시 start_agent 실행 파일이 Python PATH에 추가됩니다. start_agent로 애플리케이션을 기동하면 에이전트가 함께 적용됩니다.

환경변수로 옵션을 설정한 경우:

start_agent uvicorn app:app

기동 옵션으로 설정하는 경우:

start_agent --python_home /exem/python --agent_name python-agent uvicorn app:app

정상 기동 시 애플리케이션 로그와 함께 서버가 시작됩니다.

4-2. InitContainer 방식 (Kubernetes)​

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

에이전트 이미지 명명 규칙: exem-python-agent:inst_[버전]

에이전트 이미지에는 아래 내용이 포함되어 있습니다.

경로내용
/pkg/exem/python에이전트 기동에 필요한 설정, 로그 디렉토리
/pkg/exem/exem-python에이전트 패키지, 모듈, 기동 스크립트
노트

CURR_TRACE_TXN 옵션의 기본값은 *:3000으로, 3,000ms(3초) 미만 트랜잭션은 수집되지 않습니다. 모든 트랜잭션을 수집하려면 *:0으로 설정하세요.

1. ConfigMap 생성​

콜트리 추가가 필요한 경우 local.advice를 ConfigMap으로 정의합니다. 설정이 불필요하면 빈 값으로 두어도 됩니다.

apiVersion: v1
kind: ConfigMap
metadata:
name: exem-python-agent-config
namespace: <네임스페이스>
data:
local.advice: |
### 작성 형식
# [패키지명]
# 클래스명:메소드명
### 작성 예시
# [redis]
# * : *
# [mysql]
# PyMySQL : *

2. Deployment YAML 수정​

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

전체 예시:

apiVersion: apps/v1
kind: Deployment
metadata:
name: python-k8s-init-fastapi
namespace: <네임스페이스>
spec:
replicas: 1
selector:
matchLabels:
app: python-k8s-init-fastapi
template:
metadata:
labels:
app: python-k8s-init-fastapi
spec:
volumes:
# exem-python-agent 설치 대상 볼륨
- name: exem-volume
emptyDir: {}
# exem-python-agent 설정 파일 볼륨
- name: config-volume-python-agent
configMap:
name: exem-python-agent-config
initContainers:
- name: install-exem-python-agent
image: exem/exem-python-agent:inst_[버전]
imagePullPolicy: IfNotPresent
volumeMounts:
- name: exem-volume
mountPath: /exem
- name: config-volume-python-agent
mountPath: "/exem-config"
readOnly: true
containers:
- name: python-k8s-init-fastapi
image: <애플리케이션 이미지>
imagePullPolicy: Always
volumeMounts:
- name: exem-volume
mountPath: /exem
env:
# 기존 PYTHONPATH가 있는 경우 아래 두 경로를 기존 값 뒤에 추가해야 합니다.
# 추가하지 않으면 기존 PYTHONPATH가 덮어씌워집니다.
- name: PYTHONPATH
value: "/exem/exem-python:/exem/exem-python/pymon/bootstrap"
- name: EXEM_PYTHON_HOME
value: "/exem/python"
- name: EXEM_PYTHON_AGENT_NAME
valueFrom:
fieldRef:
fieldPath: metadata.name
- name: EXEM_GROUP_ID
value: "python"
- name: EXEM_RECEIVER_ADDR
value: "<수집서버 IP>:9010"
- name: EXEM_RUN_ON_CONTAINER
value: "true"
- name: EXEMWID
valueFrom:
fieldRef:
fieldPath: metadata.uid
ports:
- containerPort: 8000

각 항목 설명:

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

환경변수 설명:

환경변수설명비고
PYTHONPATH에이전트 적용을 위한 필수 경로. 고정값: /exem/exem-python:/exem/exem-python/pymon/bootstrap기존 경로가 있으면 뒤에 추가
EXEM_PYTHON_HOME에이전트 HOME 경로. 고정값: /exem/python
EXEM_PYTHON_AGENT_NAMEExemONE 화면에 표시될 WAS 이름
EXEM_GROUP_IDWAS 그룹 ID. 미설정 시 default
EXEM_RECEIVER_ADDR수집 서버 주소 (IP:포트)
EXEM_RUN_ON_CONTAINER컨테이너 환경 동작 여부. 컨테이너: true, On-Premise: false(기본값)
EXEMWID컨테이너 연계를 위한 키. EXEM_RUN_ON_CONTAINER=true 설정 시에만 적용

4-3. Dockerfile Rebuild 방식​

설치 대상 애플리케이션의 Dockerfile에 에이전트를 포함하여 이미지를 빌드하는 방식입니다.

노트

CURR_TRACE_TXN 옵션의 기본값은 *:3000으로, 3,000ms(3초) 미만 트랜잭션은 수집되지 않습니다. 모든 트랜잭션을 수집하려면 *:0으로 설정하세요.

1. Dockerfile 수정​

기존 Dockerfile에 아래 내용을 추가합니다.

전체 예시:

# FROM python:3.10
# ... (기존 Dockerfile 내용)

# 1. 설치 폴더가 없는 경우 생성
RUN mkdir -p /home/exemone

# 2. 패키지 복사 및 압축 해제
COPY EXEM-PYTHON-AGENT-[version].tar.gz /home/exemone
RUN tar -zxvf /home/exemone/EXEM-PYTHON-AGENT-[version].tar.gz -C /home/exemone

# 3. 모듈 설치
RUN pip install /home/exemone/exem/python/lib/exem-python-agent-[version].tar.gz

# 4. ENTRYPOINT 설정
ENTRYPOINT ["start_agent", "<기존 Python 애플리케이션 실행 명령어>"]

ENTRYPOINT 작성 예시:

유형예시
프레임워크 명령어["start_agent", "uvicorn", "--app-dir", "/app", "app:app", "--host", "0.0.0.0"]
Python 스크립트 직접 실행["start_agent", "python", "/app/consumer.py"]
실행 스크립트["start_agent", "/app/start.sh"]
실행 스크립트 + 인자["start_agent", "/app/start.sh", "arg1", "arg2"]

콜트리 추가가 필요한 경우 local.advice 파일을 아래와 같이 Dockerfile에서 직접 작성할 수 있습니다. ConfigMap을 사용하는 방법도 가능하며 다음 단계를 참고하세요.

RUN printf '[redis]\nStrictRedis:*\n' > /home/exemone/exem/python/cfg/agent/local.advice.ini

2. Deployment YAML 수정​

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

전체 예시:

apiVersion: v1
kind: ConfigMap
metadata:
name: exem-python-agent-config
namespace: <네임스페이스>
data:
local.advice: |
### 작성 형식
# [패키지명]
# 클래스명:메소드명
### 작성 예시
# [redis]
# * : *
# [mysql]
# PyMySQL : *
---
apiVersion: apps/v1
kind: Deployment
metadata:
name: python-k8s-fastapi
namespace: <네임스페이스>
spec:
replicas: 1
selector:
matchLabels:
app: python-k8s-fastapi
template:
metadata:
labels:
app: python-k8s-fastapi
spec:
volumes:
- name: exem-python-agent-config
configMap:
name: exem-python-agent-config
containers:
- name: python-k8s-fastapi
image: <에이전트를 포함하여 재빌드한 이미지>
imagePullPolicy: Always
volumeMounts:
- name: exem-python-agent-config
mountPath: /home/exemone/exem/python/cfg/agent/local.advice
subPath: local.advice
readOnly: true
env:
- name: EXEM_PYTHON_HOME
value: "/home/exemone/exem/python"
- name: EXEM_PYTHON_AGENT_NAME
valueFrom:
fieldRef:
fieldPath: metadata.name
- name: EXEM_GROUP_ID
value: "python"
- name: EXEM_RECEIVER_ADDR
value: "<수집서버 IP>:9010"
- name: EXEM_RUN_ON_CONTAINER
value: "true"
- name: EXEMWID
valueFrom:
fieldRef:
fieldPath: metadata.uid
ports:
- containerPort: 8000

환경변수 설명:

환경변수설명
EXEM_PYTHON_HOME에이전트 HOME 경로. 패키지 압축 해제 경로 아래의 exem/python
EXEM_PYTHON_AGENT_NAMEExemONE 화면에 표시될 WAS 이름
EXEM_GROUP_IDWAS 그룹 ID. 미설정 시 default
EXEM_RECEIVER_ADDR수집 서버 주소 (IP:포트)
EXEM_RUN_ON_CONTAINER컨테이너 환경 동작 여부. 컨테이너: true, On-Premise: false(기본값)
EXEMWID컨테이너 연계를 위한 키. EXEM_RUN_ON_CONTAINER=true 설정 시에만 적용