Python SDK 설치

AI Agent Observability Python SDK는 pip install whatap-python[llm] 명령으로 설치하며, 서버 환경에 맞춰 실행 명령어 앞에 whatap-start-agent를 추가하여 적용합니다. 이 문서는 가상 환경 활성화부터 서비스 실행 확인까지 설치 전 과정을 안내합니다.

설치 전 확인사항

SDK를 설치하기 전에 다음을 확인하세요.

시작하기 문서에서 프로젝트 생성과 액세스 키 발급을 완료했는지 확인하세요.
지원 환경에서 애플리케이션 환경이 지원 범위에 해당하는지 확인하세요.

가상 환경 활성화

애플리케이션이 virtualenv를 사용 중이라면 bin/activate 파일을 실행해 가상 환경을 활성화하세요.

SDK 다운로드

액세스 키를 발급받은 후, SDK 다운로드 섹션으로 이동하세요. 다음 코드를 실행해 SDK를 설치하세요.

pip install whatap-python[llm]

팁

pip 명령으로 설치할 수 없다면 pypi 와탭 페이지에서 설치 파일을 다운로드하세요. 다운로드한 파일을 압축 해제한 다음 설치하세요.

tar xzvf whatap_python-2.x.x.tar.gz
cd whatap_python-2.X.Y.Z
python setup.py install

노트

whatap-python[llm] 패키지는 datasketches>=5.2.0, genai-prices 외부 라이브러리를 필요로 합니다. 의존성을 누락하면 일부 데이터 수집이 빠질 수 있으니, 수동 설치 시에도 해당 의존성을 포함하세요.

SDK 구성 파일

Python SDK 파일은 애플리케이션 모니터링에 필요한 정보를 추출해 와탭 수집 서버로 전달하는 트레이서와 이를 지원하는 요소로 구성되어 있습니다. SDK 파일 구성은 다음을 참조하세요.

SDK 설정

WHATAP_HOME 경로 설정

로그와 설정 파일 경로를 위한 $WHATAP_HOME 경로를 지정하세요. whatap 디렉터리를 새로 생성하는 것을 권장합니다.

$ export WHATAP_HOME=[PATH]

액세스 키 및 수집 서버 IP 설정

액세스 키 및 수집 서버 IP 설정을 위해 whatap-llm-setting-config 명령어를 실행하세요.

$ whatap-llm-setting-config \
--host [ COLLECTION_SERVER_IP ] \
--license [ ACCESS_KEY ] \
--app_name [ USER_DEFINED_AGENT_NAME ] \
--app_process_name [ APPLICATION_PROCESS_NAME(uwsgi, gunicorn etc..) ]

설정 확인

$WHATAP_HOME에 지정한 경로로 whatap.conf 파일이 생성되고 설정됩니다. 다음 명령어를 실행해 whatap.conf 파일이 생성됐는지 확인하세요.

$ cat $WHATAP_HOME/whatap.conf

whatap.conf
llm_license=[ACCESS_KEY]
llm.whatap.server.host=[COLLECTION_SERVER_IP]

llm_enabled=true

# application name
app_name=[ USER_DEFINED_AGENT_NAME ]

# middleware process name ex)uwsgi, gunicorn ..
app_process_name=[ APPLICATION_PROCESS_NAME(uwsgi, gunicorn etc..) ]

LLM 전용 모듈 설치

Python SDK로 AI Agent Observability를 사용하려면 와탭이 LLM 전용으로 개발한 Go 모듈을 추가로 설치해야 합니다.

cd $WHATAP_HOME

curl -fsSL -O https://repo.whatap.io/python/llm/whatap-python-llm.tar.gz

tar -xzf whatap-python-llm.tar.gz

압축을 해제하면 생성되는 whatap-python-llm 폴더는 앞서 설정한 $WHATAP_HOME 경로 아래에 위치해야 합니다.

노트

권한 문제가 발생하는 경우

와탭 설정을 위한 $WHATAP_HOME/whatap.conf 파일의 읽기 및 쓰기 권한
와탭 로그를 위한 $WHATAP_HOME/logs 경로와 하위 파일의 읽기 및 쓰기 권한

$WHATAP_HOME 경로에 대한 권한 문제가 발생하다면 다음 명령어를 실행해 권한을 부여하세요.

echo `sudo chmod -R 777 $WHATAP_HOME`

서버 환경별 적용

서버 환경에 맞는 방법을 선택하세요.

Command 환경에서는 다음과 같이 whatap-start-agent 명령어를 애플리케이션 시작 명령어(Application start command) 앞에 추가하세요.

BASH
# $ whatap-start-agent [Application start command]
$ whatap-start-agent python manage.py runserver

uWSGI 환경에서는 다음과 같이 whatap-start-agent 명령어를 uwsgi 명령어 앞에 추가하세요.

BASH
$ whatap-start-agent uwsgi --ini myapp.ini

서비스에 uWSGI를 등록해 애플리케이션을 실행하는 경우 다음 예제 코드를 참고하세요.

/etc/init.d/uwsgi
description "uWSGI application server handling myapp"
start on runlevel [2345]
stop on runlevel [!2345]
exec whatap-start-agent [YOUR_APPLICATION_START_COMMAND]
# or if you are using a virtual environment
exec env WHATAP_HOME=[PATH] [ABSOLUTE_PATH]/whatap-start-agent [YOUR_APPLICATION_START_COMMAND]

/etc/init/uwsgi.conf
...
NAME="uwsgi"
PATH=/usr/local/bin:/sbin:/bin:/usr/sbin:/usr/bin
DAEMON=/usr/local/bin/uwsgi
PID=$RUN/$NAME.pid
INI_PATH=/etc/$NAME/$NAME.ini

########## WHATAP_AGENT_CONF ##########
WHATAP_HOME=[PATH]
WHATAP_AGENT=[ABSOLUTE_PATH]/whatap-start-agent
...
do_start(){
  env WHATAP_HOME=$WHATAP_HOME $WHATAP_AGENT [YOUR_APPLICATION_START_COMMAND]
}

노트

사용자(User)를 변경한다면 WHATAP_HOME 환경 변수를 추가하세요.
가상 환경을 사용한다면 SDK 시작 명령어를 절대 경로로 추가하세요.
서비스 실행 파일(/etc/init/uwsgi.conf)을 수정하여 SDK 시작 명령어와 함께 애플리케이션을 시작하세요.
사용자 환경에 따라 서비스 실행 파일의 경로는 다를 수 있습니다.

Gunicorn 환경에서는 다음과 같이 whatap-start-agent 명령어를 Gunicorn 명령어 앞에 추가하세요.

BASH
$ whatap-start-agent gunicorn myapp.wsgi

서비스에 Gunicorn를 등록해 애플리케이션을 실행하는 경우 다음 예제 코드를 참고하세요.

/etc/init.d/gunicorn
description "gunicorn application server handling myapp"
start on runlevel [2345]
stop on runlevel [!2345]
exec whatap-start-agent [YOUR_APPLICATION_START_COMMAND]
# or if you are using a virtual environment
exec env WHATAP_HOME=[PATH] [ABSOLUTE_PATH]/whatap-start-agent [YOUR_APPLICATION_START_COMMAND]

/etc/init/gunicorn.conf
...
NAME="gunicorn"
PATH=/usr/local/bin:/sbin:/bin:/usr/sbin:/usr/bin
DAEMON=/usr/local/bin/gunicorn
PID=$RUN/$NAME.pid
INI_PATH=/etc/$NAME/$NAME.ini

########## WHATAP_AGENT_CONF ##########
WHATAP_HOME=[PATH]
WHATAP_AGENT=[ABSOLUTE_PATH]/whatap-start-agent

...
do_start(){
  env WHATAP_HOME=$WHATAP_HOME $WHATAP_AGENT [YOUR_APPLICATION_START_COMMAND]
}

노트

사용자(User)를 변경한다면 WHATAP_HOME 환경 변수를 추가하세요.
가상 환경을 사용한다면 SDK 시작 명령어를 절대 경로로 추가하세요.
서비스 실행 파일(/etc/init/gunicorn.conf)을 수정하여 SDK 시작 명령어와 함께 애플리케이션을 시작하세요.
사용자 환경에 따라 서비스 실행 파일의 경로는 다를 수 있습니다.

Supervisor 환경에서는 적용하기 위해 supervisor.conf 파일에 다음 설정을 추가하세요.

supervisor.conf
[program:app-uwsgi]
environment = WHATAP_HOME=[PATH]
command = [ABSOLUTE_PATH]/whatap-start-agent /usr/local/bin/uwsgi --ini /home/blog/backend/config/uwsgi.ini

[program:nginx-app]
command = /usr/sbin/nginx

노트

사용자(User)를 변경한다면 WHATAP_HOME 환경 변수를 추가하세요.
가상 환경을 사용한다면 SDK 시작 명령어를 절대 경로로 추가하세요.
서비스 실행 파일(/etc/supervisor/conf.d/supervisor.conf)을 수정하여 SDK 시작 명령어와 함께 애플리케이션을 시작하세요.
사용자 환경에 따라 서비스 실행 파일의 경로는 다를 수 있습니다.

WSGI 애플리케이션을 직접 구현하는 방법을 안내합니다. 다음을 참조하세요.

PYTHON
import whatap

@whatap.register_app
def simple_app(environ, start_response):
    """Simplest possible application object"""
    status = '200 OK'
    response_headers = [('Content-type', 'text/plain')]
    start_response(status, response_headers)
    return ['Hello world!\n']

Docker 컨테이너로 서비스되는 애플리케이션의 경우 다음 내용을 Dockerfile에 추가하세요.

Python SDK를 설치하세요.
Dockerfile
```
ENV WHATAP_HOME /whatap
RUN mkdir -p /whatap
RUN pip install whatap-python[llm]
```
노트
requirements.txt를 사용한다면 해당 파일에 whatap-python[llm]을 추가하세요.

액세스 키 및 수집 서버 IP 설정을 등록하세요.

Dockerfile
RUN touch /whatap/whatap.conf
RUN echo "llm_license=[ ACCESS_KEY ]" > /whatap/whatap.conf
RUN echo "llm.whatap.server.host=[ COLLECTION_SERVER_IP ]" >> /whatap/whatap.conf
RUN echo "app_name=[ AGENT_NAME ]" >> /whatap/whatap.conf
RUN echo "app_process_name=[ APPLICATION_PROCESS_NAME(uwsgi, gunicorn etc..) ]" >> /whatap/whatap.conf

기존 실행 커맨드 python manage.py runserver 앞에 whatap-start-agent를 추가하세요.
Dockerfile
```
CMD ["whatap-start-agent", "python", "manage.py", "runserver", "0.0.0.0:8000"]
```

코드 가장 윗줄에 API를 직접 호출하는 코드를 다음과 같이 추가해 SDK를 적용할 수 있습니다.

코드를 통해 SDK를 실행하는 경우 whatap.conf에 다음 옵션을 추가하세요.

whatap.conf
whatap_code_start=true

코드 가장 윗줄에 다음과 같이 추가하세요.

PYTHON
import whatap
whatap.agent()

애플리케이션 서버를 실행하면 SDK가 모니터링 데이터를 수집하기 시작합니다.

서비스 실행 확인

다음 명령어를 실행해 와탭 Python 서비스가 정상 실행되는지 확인하세요.

ps -ef | grep whatap_python

설치 전 확인사항​

가상 환경 활성화​

SDK 다운로드​

SDK 구성 파일​

SDK 설정​

WHATAP_HOME 경로 설정​

액세스 키 및 수집 서버 IP 설정​

설정 확인​

LLM 전용 모듈 설치​

서버 환경별 적용​

서비스 실행 확인​