Running Backend Server Using SeaLights Agent

In order to capture code coverage on your backend server, you need to run it using our Python test listener agent. Below you’ll find several options depending on your server type.

The below commands assume the token and session id are located in the working directory. If not, you can provide the file locations using the sl.tokenFile and sl.buildSessionIdFile environment variables

uWSGI

When working with uWSGI, you need to run it with the following flags either in the command line or in the uwsgi configuration file: --enable-threads --single-interpreter --lazy-apps --import python_agent.init

If you need to pass the parameters via the CLI, the command line will be similar to this

uwsgi ... --enable-threads  --single-interpreter --import python_agent.init

If using the uWSGI config file option, the content should look like the sample below

[uwsgi] 
... 
enable-threads = true 
single-interpreter = true 
import = python_agent.init

Gunicorn WSGI

When working with Gunicorn WSGI you need to run it with the following a configuration file which contains an import of the SeaLights Python agent in the post_fork section

... 
def post_fork(server, worker): 
    import python_agent.init 
...

Uvicorn ASGI

Uvicorn does not support importing module to be run before the app is started (as in uwsgi). in order to overcome this there is a code change need to be done at the source code in order to init Sealights when Uvicorn is loading

... 
# Check for an environment variable and import accordingly 
if os.getenv('ENABLE_SEALIGHTS', 'false') == 'true': 
    import python_agent.init     
...

Running the app:

export ENABLE_SEALIGHTS=true
uvicorn app:APP --host 0.0.0.0 --port 9092 --workers 1 --reload

Sample code for dynamic update of files

If you don’t want to update your source code, you may evaluate adding these few script lines (or equivalent) in your CI/CD. Usage: ./myscript.sh mypythonfile.py

#!/bin/bash
 
[[ $1 == *.py && -f $1 ]] || { echo "Error: Provide a valid Python file (.py)"; exit 1; }

# Lines to add as an environment variable
LINES_TO_ADD=$(cat <<'EOF'
Check for an environment variable and import accordingly
if os.getenv('ENABLE_SEALIGHTS', 'false') == 'true':
import python_agent.init
EOF
)

# Create a backup and modify the file
cp "$1" "$1.bak" && sed -i "/^import|^from /a\$LINES_TO_ADD" "$1" && echo "[Sealights] Lines inserted into $1, backup created at $1.bak." 

Other servers (Generic solution)

For other servers, run with the SeaLights Python agent and the run flags

sl-python run {--cov-report /path/to/report.xml --labid Lab1} python <your server and args...>

The first parameter after the run command should be an executable file

Containers: Runtime Integration Without Modifying the ENTRYPOINT

spec:
  volumes:
    - name: sealights
      emptyDir: {} # Shared volume for the installed `sl-python` binary
  initContainers:
    - name: install-sl-python
      image: python:3.9-slim
      command: ["sh", "-c", "pip install sealights-python-agent && cp $(which sl-python) /sealights/"]
      volumeMounts:
        - name: sealights
          mountPath: /sealights
  containers:
    - name: app-container
      image: python:3.9-slim
      env:
        - name: SEALIGHTS_AGENT_TOKEN
          valueFrom:
            secretKeyRef:
              name: sealights-token-secret
              key: agent-token
        - name: PYTHON_EXE
          value: "/sealights/sl-python run --token \"$SEALIGHTS_AGENT_TOKEN\" -- python"
      command:
        - sh
        - "-c"
        - "$PYTHON_EXE app.py"
      volumeMounts:
        - name: sealights
          mountPath: /sealights
      # Other initialization sections required (e.g. ports, livenessProbe, readinessProbe, etc.)

Using a sitecustomize.py file

sitecustomize.py is a standard Python startup hook that is automatically imported during interpreter initialization (unless Python is started with -S). Placing a top-level sitecustomize.py on sys.path allows to preload the Sealights agent before any application code is imported, without modifying the application entrypoint.

Steps to set up

1. Create the sitecustomize.py with the following content: import python_agent.init

2. Place the file in a folder, for example: /opt/python-startup

3. Update the PYTHONPATH to include the above folder first, for example: export PYTHONPATH="/opt/python-startup:${PYTHONPATH}"

4. Set any additional environment variables, for example: SL_LAB_ID

5. Start your python application as you have till this point

Here is a sample docker file:

FROM python:3.9-slim

...

RUN mkdir -p /opt/python-startup
RUN cat > /opt/python-startup/sitecustomize.py <<'PY'
import python_agent.init
PY

EXPOSE 8080
ENTRYPOINT ["python", "server.py" ]

Here's a sample k8s yaml env snippet of setting the environment variables:

env:
  - name: PYTHONPATH
    value: /opt/python-startup
  - name: SL_LABID
    value: Lab1