본문으로 건너뛰기

Python Agent 설치하기

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

지원 환경​

Python 버전​

항목지원 버전
Python3.7 이상

지원 프레임워크​

프레임워크비고
Django
Flask
FastAPI
Kafkakafka_python, confluent_kafka
노트

위 목록 이외의 Python 웹 프레임워크는 지원되지 않습니다. 다른 프레임워크 지원이 필요한 경우 제품기술팀에 문의하세요.

SQL 추적 지원 데이터베이스​

데이터베이스지원 라이브러리
SQLitesqlite3, pysqlite3
MySQLpymysql, MySQLdb
Oraclecx_Oracle
PostgreSQLpsycopg2
Redisredis, redis-om
MongoDBpymongo, motor

통신 포트​

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

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

설치 방법​

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

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

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

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

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 설정 시에만 적용

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 설정 시에만 적용