LLM Python SDK Installation

The AI Agent Observability Python SDK is installed via pip install whatap-python[llm] and applied by adding whatap-start-agent before your application's run command. This document guides you through the entire installation process, from activating a virtual environment to verifying the service.

Pre-installation checklist

Before installing the agent, verify the following:

• Confirm that you have completed project creation and access key issuance in Getting Started.

• Check that your application environment falls within the supported range in Supported Environment.

Activate virtual environment

If your application uses virtualenv, run the bin/activate file to activate the virtual environment.

Download agent

After issuing an access key, go to the Download agent section. Run the following command to install the agent.

pip install whatap-python[llm]

Tip

If you cannot install via the pip command, download the installation file from the pypi WhaTap page. Extract the downloaded file and proceed with installation.

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

Note

The whatap-python[llm] package requires the external libraries datasketches>=5.2.0 and genai-prices. Missing dependencies may cause some data collection to be skipped. Include these dependencies even when installing manually.

SDK configuration files

The Python SDK files consist of a tracer that extracts information required for application monitoring and sends it to the WhaTap collection server, along with supporting elements. See the following for the agent file structure.

Configure agent

Set WHATAP_HOME path

Specify the $WHATAP_HOME path for log and configuration file paths. Creating a new whatap directory is recommended.

$ export WHATAP_HOME=[PATH]

Set access key and collection server IP

Run the whatap-llm-setting-config command to set the access key and collection server IP.

$ 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..) ]

Verify configuration

The whatap.conf file is created and configured at the path specified in $WHATAP_HOME. Run the following command to verify the whatap.conf file was created.

$ 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..) ]

Install the LLM-only module

To use Python AI Agent Observability, you must additionally install the Go module that WhaTap developed for LLM.

cd $WHATAP_HOME

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

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

The whatap-python-llm directory created by extracting the archive must be located under the $WHATAP_HOME path you set earlier.

Note

If permission issues occur

• Read and write permissions for the $WHATAP_HOME/whatap.conf file for WhaTap configuration

• Read and write permissions for the $WHATAP_HOME/logs path and its sub-files for WhaTap logs

If permission issues occur for the $WHATAP_HOME path, run the following command to grant permissions.

echo `sudo chmod -R 777 $WHATAP_HOME`

Apply per server environment

Select the method that matches your server environment.

Command

In a Command environment, add the whatap-start-agent command before the application start command as follows.

BASH

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

uWSGI

In a uWSGI environment, add the whatap-start-agent command before the uwsgi command as follows.

BASH

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

If running the application by registering uWSGI as a service, refer to the following example code.

/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]
}

Note

• If changing the user, add the WHATAP_HOME environment variable.

• If using a virtual environment, add the agent start command as an absolute path.

• Modify the service execution file (/etc/init/uwsgi.conf) to start the application with the agent start command.

• The service execution file path may differ depending on your environment.

Gunicorn

In a Gunicorn environment, add the whatap-start-agent command before the Gunicorn command as follows.

BASH

$ whatap-start-agent gunicorn myapp.wsgi

If running the application by registering Gunicorn as a service, refer to the following example code.

/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]
}

Note

• If changing the user, add the WHATAP_HOME environment variable.

• If using a virtual environment, add the agent start command as an absolute path.

• Modify the service execution file (/etc/init/gunicorn.conf) to start the application with the agent start command.

• The service execution file path may differ depending on your environment.

Supervisor

In a Supervisor environment, add the following settings to the supervisor.conf file.

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

Note

• If changing the user, add the WHATAP_HOME environment variable.

• If using a virtual environment, add the agent start command as an absolute path.

• Modify the service execution file (/etc/supervisor/conf.d/supervisor.conf) to start the application with the agent start command.

• The service execution file path may differ depending on your environment.

WSGI

The following guides how to directly implement a WSGI application.

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

For applications served as Docker containers, add the following to the Dockerfile.

1. Install the Python SDK.

   Dockerfile

   ENV WHATAP_HOME /whatap
   RUN mkdir -p /whatap
   RUN pip install whatap-python[llm]

   Note

   If using requirements.txt, add whatap-python[llm] to the file.

2. Register the access key and collection server IP settings.

   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

3. Add whatap-start-agent before the existing run command python manage.py runserver.

   Dockerfile

   CMD ["whatap-start-agent", "python", "manage.py", "runserver", "0.0.0.0:8000"]

Code

You can apply the agent by adding API call code at the top of your code as follows.

When running the agent via code, add the following option to whatap.conf.

whatap.conf

whatap_code_start=true

Add the following at the top of your code.

PYTHON

import whatap
whatap.agent()

Once you start the application server, the agent begins collecting monitoring data.

Verify service execution

Run the following command to verify the WhaTap Python service is running properly.

ps -ef | grep whatap_python