Python SDK Setup Guide

The InSitu Python SDK runs as an in-process agent. It captures variables, stack frames, metrics, and logs without stopping your application in a debugger. Capture runs on the application thread, so overhead depends on your probes and workload.

Technical Prerequisites

Runtime: CPython 3.7 and later. Python 3.12 and later uses sys.monitoring; Python 3.7–3.11 uses bytecode instrumentation.
Metadata: Access to the active git commit SHA (mandatory for matching local source coordinates to production builds).

Installation

Add the SDK as a dependency using your package manager:

pip install InSitu-agent

poetry add InSitu-agent

pipenv install InSitu-agent

uv add InSitu-agent

Initialization Walkthrough

Follow these steps to initialize the InSitu agent inside your application:

Create your initialization file

Create a dedicated file named InSitu_init.py in your project source root:

InSitu_init.py

import os

from InSitu import InSitu

InSitu.start({
    "service_id": "<service-uuid-from-dashboard>",
    "environment": os.getenv("InSitu_ENVIRONMENT") or os.getenv("PYTHON_ENV"),
    "broker_url": "https://logger.app.useinsitu.com",
    "commit_sha": os.getenv("InSitu_COMMIT_SHA") or os.getenv("GIT_COMMIT"),
})

Import it in your entrypoint

In your main application file, import InSitu_init as early as possible before starting your application:

main.py

import InSitu_init

from app import create_app

app = create_app()

Environment Variables Loading Order: If InSitu_init.py reads variables loaded by a library such as python-dotenv, load those variables before importing InSitu_init.

Configure preloaded workers (Gunicorn)

If your server loads the application before forking workers, such as Gunicorn with --preload, set this variable before starting the server:

export InSitu_FORK_MODE=worker

The parent defers initialization and each worker starts its own agent. Use this setting only when the application is loaded before workers fork. Inside the workers, use the spawn process start method instead of creating additional children with fork.

Configure your Dockerfile

To enable Docker-based deployments, define a GIT_COMMIT build argument inside your Dockerfile with a default value of unknown:

Dockerfile

ARG GIT_COMMIT=unknown
ENV GIT_COMMIT=${GIT_COMMIT}

Run local Docker builds

For building and testing Docker containers locally, inject your active git commit:

docker build --build-arg GIT_COMMIT=$(git rev-parse HEAD) -t api:latest .

Inject the correct SHA in CI/CD

InSitu does not start if commit_sha is missing or unknown. Pass the commit SHA of the source used to build the application to GIT_COMMIT during deployment.You can use your CI/CD platform’s commit SHA variable when it matches the checked-out source:

Platform / Engine	Configuration Option	Build Argument Syntax
GitHub Actions	Default checkout	`--build-arg GIT_COMMIT=${{ github.sha }}`
GitLab CI/CD	GitLab Variable	`--build-arg GIT_COMMIT=$CI_COMMIT_SHA`
CircleCI	CircleCI Variable	`--build-arg GIT_COMMIT=$CIRCLE_SHA1`

On a pull_request workflow, GitHub Actions checks out a merge commit by default. If you build that checkout, use its SHA. If you explicitly check out the PR head, use the head SHA instead. git rev-parse HEAD reports the checked-out commit.

Configuration & Environment Variables Reference

You can configure the agent by passing properties inside your InSitu.start() options object, or by using environment variables. The following example includes the available programmatic options and their corresponding environment variables:

InSitu_init.py

import os

from InSitu import InSitu

InSitu.start({
    # --- CORE OPTIONS ---
    "service_id": "<service-uuid-from-dashboard>",
    "environment": os.getenv("InSitu_ENVIRONMENT") or os.getenv("PYTHON_ENV"),
    "broker_url": "https://logger.app.useinsitu.com",
    "commit_sha": os.getenv("InSitu_COMMIT_SHA") or os.getenv("GIT_COMMIT"),

    # --- BUFFERING & PERFORMANCE ---
    "max_queue_size": 100,      # Env: InSitu_MAX_QUEUE_SIZE
    "flush_interval_ms": 1000,  # Env: InSitu_FLUSH_INTERVAL_MS
    "sync_interval_ms": 60000,  # Env: InSitu_SYNC_INTERVAL_MS

    # --- SAFETY GUARDRAILS ---
    "hits_per_sec": 10,         # Env: InSitu_HITS_PER_SEC
    "bandwidth_kb_per_sec": 1024, # Env: InSitu_BANDWIDTH_KB_PER_SEC
    "InSitu_max_lag_ms": 50, # Env: InSitu_MAX_LAG_MS
    "InSitu_pause_budget_ms": 15, # Env: InSitu_PAUSE_BUDGET_MS
    "InSitu_cooldown_sec": 10, # Env: InSitu_COOLDOWN_SEC
    "InSitu_rpc_timeout_sec": 10, # Env: InSitu_RPC_TIMEOUT_SEC

    # --- DATA & REDACTION CONTROLS ---
    "redact_keys": [            # Env: InSitu_REDACT_KEYS
        "password", "secret", "token", "authorization", "cookie", "key", "signature"
    ],
    "redact_values": [],        # Env: InSitu_REDACT_VALUES
    "max_object_depth": 3,      # Env: InSitu_MAX_OBJECT_DEPTH
    "max_array_length": 3,      # Env: InSitu_MAX_ARRAY_LENGTH
    "max_object_properties": 50, # Env: InSitu_MAX_OBJECT_PROPERTIES
    "max_string_length": 1024,  # Env: InSitu_MAX_STRING_LENGTH
    "stack_frame_depth": 3,     # Env: InSitu_STACK_FRAME_DEPTH
})

Option precedence: Nonempty options in this example take precedence over their environment variables. Omit an option to configure it through the environment.
Required settings: Provide a UUIDv4 service ID, environment, broker URL, and commit SHA. They can also be supplied through InSitu_SERVICE_ID, InSitu_ENVIRONMENT, InSitu_BROKER_URL, and InSitu_COMMIT_SHA or GIT_COMMIT. If initialization fails, the application continues without the agent.
Disabling the agent: Set InSitu_DISABLED=YES to disable startup.

Redaction

redact_keys and redact_values are lists of case-insensitive regular expressions. Their environment variables accept comma-separated patterns. A custom key list replaces the defaults, so include the defaults when adding keys.

Key redaction does not protect the result of a scalar watch expression such as password. Avoid watching sensitive values, and configure value-redaction patterns for secrets that may appear in captured strings.

Safe evaluation

Safe evaluation is enabled by default and restricts calls in probe expressions. It is not a security sandbox: properties and operators can still run application code. Use trusted probes. To allow arbitrary function and method calls, set InSitu_DISABLE_SAFE_EVALUATION=true or pass "disable_safe_evaluation": True to InSitu.start().

Disabling safe evaluation allows expressions to change application state or block execution. The agent cannot safely interrupt an expression that is already running.

Safety shields

The Python agent monitors scheduler lag and the time spent handling probes:

Yellow threshold: The pause budget exceeds 50%, four of the last ten lag readings exceed 50 ms, or one of the last five readings exceeds 200 ms.
Red threshold: The pause budget exceeds 15 ms per second, seven of the last ten lag readings exceed 50 ms, or three of the last five readings exceed 200 ms. The agent suspends instrumentation.
Auto-recovery: Resumes probes after the cooldown period (default 10 seconds), once health returns to GREEN.

These thresholds use the defaults above. Set DEBUG=InSitu:agent before startup to see safety logs.

Get Started

AI-Native Debugging

VS Code Extension

SDK Integration

Probe Types

Guides

Troubleshooting

Self-Hosting

Python SDK Setup Guide

Technical Prerequisites

Installation

Initialization Walkthrough

Configuration & Environment Variables Reference

Redaction

Safe evaluation

Safety shields