Running Your Backend Server with SeaLights

The SeaLights agent loads inside the Python process at startup to capture code coverage. It needs SL_TOKEN, SL_BUILDSESSIONIDFILE, and SL_LABID to report that coverage correctly.

TL;DR — which method should I use?

Method

Situation

Launch method

Method 1: Python startup hook

You control the runtime environment; use it by default because it's non-intrusive (needs no code changes).

python app.py, custom runner, Uvicorn (standalone)

Method 2: sl-python wrapper

You cannot change the image or PYTHONPATH; it requires modifying the launch command.

Any

Method 3: Server-specific integration

You run Gunicorn or uWSG servers that fork workers after startup.

uWSGI, Gunicorn

Required SeaLights Configuration

Before starting the application, provide these three runtime values:

SeaLights reads these variables only when the process starts. Restart or redeploy after changing them.

SL_TOKEN — the SeaLights agent token. Supply it from a secret store.
SL_BUILDSESSIONIDFILE — the path to the generated build session ID file. A prior SeaLights CLI or CI step generates the build session ID.
- Keep it alongside the application when possible.
- Use ./buildSessionId.txt locally or /app/buildSessionId.txt in an image.
- Kubernetes injection uses /sealights/buildSessionId.txt.
SL_LABID — identifies the test environment, such as staging or uat where this run's coverage rolls up.
- Every process, container, worker, and replica in that testing environment must use the same value.
- In addition, SeaLights assigns each runtime instance a unique Agent ID.

For a quick local check, install the agent:

pip install sealights-python-agent

The examples below use quick-install commands. For production deployments, follow the instructions in "Downloading the Python Agent" and your organization's delivery practices.

Method 1 — Python startup hook (recommended)

Create a sitecustomize.py file containing:

import python_agent.init

Python automatically imports sitecustomize.py during startup. Its directory must be discoverable through PYTHONPATH or Python's site search path.

sitecustomize.py
  ↓
PYTHONPATH points to its directory
  ↓
Python imports sitecustomize.py
  ↓
SeaLights agent loads

This is the recommended default. It requires no application code changes.

Local validation or POC

Use this approach to validate instrumentation locally. It suits proof-of-concept work and troubleshooting. Do not use it as production installation guidance.

Bash

SEALIGHTS_TOKEN must already be exported from your secret store. This script reads it; it does not provide it.

pip install sealights-python-agent
mkdir -p .sealights
printf 'import python_agent.init\n' > .sealights/sitecustomize.py

export PYTHONPATH="$PWD/.sealights${PYTHONPATH:+:$PYTHONPATH}"
export SL_TOKEN="$SEALIGHTS_TOKEN"
export SL_BUILDSESSIONIDFILE="$PWD/buildSessionId.txt"
export SL_LABID="local-validation"

python app.py

PowerShell

SEALIGHTS_TOKEN must already be exported from your secret store. This script reads it; it does not provide it.

pip install sealights-python-agent
New-Item -ItemType Directory -Force .sealights | Out-Null
Set-Content .sealights/sitecustomize.py "import python_agent.init"

$env:PYTHONPATH = "$PWD/.sealights"
$env:SL_TOKEN = $env:SEALIGHTS_TOKEN
$env:SL_BUILDSESSIONIDFILE = "$PWD/buildSessionId.txt"
$env:SL_LABID = "local-validation"

python app.py

Prefer Kubernetes injection over the Dockerfile approach when you do not own the image build.

Use this when you already have an application image. The init container writes the agent and sitecustomize.py to a shared volume. The application loads them through PYTHONPATH.

spec:
  volumes:
    - name: sealights
      emptyDir: {}
  initContainers:
    - name: inject-sealights
      image: python:3.11.9-slim
      command:
        - sh
        - -c
        - |
          pip install --no-cache-dir --target /sealights sealights-python-agent
          printf 'import python_agent.init\n' > /sealights/sitecustomize.py
      volumeMounts:
        - name: sealights
          mountPath: /sealights
  containers:
    - name: app
      image: registry.example/myapp:latest
      env:
        # Path to `sitecustomize.py` file created above
        - name: PYTHONPATH
          value: /sealights
        # Token from Kubernetes secret
        - name: SL_TOKEN
          valueFrom:
            secretKeyRef:
              name: sealights
              key: token
        # File containing the Build Session ID (BSID)
        # Recommended: package and deploy this file as part of the application artifact
        # Alternatively, BSID can be supplied directly via corresponding Env var
        - name: SL_BUILDSESSIONIDFILE
          value: /app/buildSessionId.txt
        # Test Environment Identifier
        - name: SL_LABID
          value: uat1
        # Logging (Optional)
        #- name: SL_DEBUG
        #  value: true
  volumeMounts:
    - name: sealights
      mountPath: /sealights
      readOnly: true

This pattern is recommended when you own the image build. The image contains the SeaLights agent configuration and artifact-specific settings (such as the BSID file location), while the deployment supplies environment-specific configuration such as the token and Lab ID.

Dockerfile

FROM python:3.11.9-slim
WORKDIR /app
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt \
    && pip install --no-cache-dir sealights-python-agent
COPY . .
RUN mkdir /opt/sealights \
    && printf 'import python_agent.init\n' > /opt/sealights/sitecustomize.py

# SeaLights bootstrap path
ENV PYTHONPATH=/opt/sealights
# BSID file packaged with the app
ENV SL_BUILDSESSIONIDFILE=/app/buildSessionId.txt

CMD ["python", "app.py"]

Kubernetes runtime configuration

env:
  # SeaLights token from K8s secrets
  - name: SL_TOKEN
    valueFrom:
      secretKeyRef:
        name: sealights
        key: token
  # Test environment identifier
  - name: SL_LABID
    value: uat1
  # Logging (Optional)
  #- name: SL_DEBUG
  #  value: true

Method 2 — `sl-python` wrapper

The agent ships with an sl-python CLI that wraps any Python invocation. Use this when you cannot modify the application source or PYTHONPATH, but you can change the launch command.

The first argument after run must be an executable.

TODO: confirm signal-forwarding behavior of sl-python run.

export SL_TOKEN="$SEALIGHTS_TOKEN"
export SL_BUILDSESSIONIDFILE="$PWD/buildSessionId.txt"
export SL_LABID="local-validation"

sl-python run --labId "$SL_LABID" -- python app.py

$env:SL_TOKEN = $env:SEALIGHTS_TOKEN
$env:SL_BUILDSESSIONIDFILE = "$PWD/buildSessionId.txt"
$env:SL_LABID = "local-validation"

sl-python run --labId $env:SL_LABID -- python app.py

See Command Reference - `run` command

Method 3 — Server-specific integration

Use this method only for Gunicorn or uWSGI. These servers fork workers after startup. Each worker must load the agent after it forks.

Load the agent from Gunicorn's post_fork hook:

# gunicorn.conf.py
import os

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

Gunicorn runs post_fork for every worker. This ensures each worker loads the agent.

Provide SL_TOKEN, SL_BUILDSESSIONIDFILE, and SL_LABID through the Gunicorn process environment.

Load the agent in every worker:

# sealights.ini
[uwsgi]
# Enables agent reporting threads
enable-threads = true
# Uses one interpreter per worker
single-interpreter = true
# Loads the application after worker fork
lazy-apps = true
# Loads the agent in every worker
import = python_agent.init

Provide SL_TOKEN, SL_BUILDSESSIONIDFILE, and SL_LABID through the uWSGI process environment.

Troubleshooting & FAQ

See these checks when coverage does not appear.

Coverage not appearing?

General checks

Confirm the agent and SL_TOKEN are available.
Confirm SL_BUILDSESSIONIDFILE points to an existing file.
Verify the runtime through the Live Agents API.

Method 1 — Python startup hook

Confirm sitecustomize.py exists.
Confirm PYTHONPATH points to its directory.

Method 3 — Gunicorn and uWSGI

For Gunicorn, confirm post_fork imports python_agent.init.
For uWSGI, confirm lazy-apps, single-interpreter, and enable-threads are enabled.

Kubernetes runtime and permission checks

Match the init container's Python version to the application runtime.

For non-root containers, ensure the application can read the shared volume:

securityContext:
  fsGroup: 1001

Good morning

Running Your Backend Server with SeaLights

TL;DR — which method should I use?

Required SeaLights Configuration

Method 1 — Python startup hook (recommended)

Method 2 — `sl-python` wrapper

Method 3 — Server-specific integration

Troubleshooting & FAQ

See also

Good morning

TL;DR — which method should I use?

Required SeaLights Configuration

Method 1 — Python startup hook (recommended)

Method 2 — sl-python wrapper

Method 3 — Server-specific integration

Troubleshooting & FAQ

See also

Method 2 — `sl-python` wrapper