> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hyperprobe.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Python SDK Setup Guide

> Install, initialize, and optimize the HyperProbe Python SDK inside in-process Python applications.

The HyperProbe 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:

```bash pip theme={null}
pip install hyperprobe-agent
```

```bash poetry theme={null}
poetry add hyperprobe-agent
```

```bash pipenv theme={null}
pipenv install hyperprobe-agent
```

```bash uv theme={null}
uv add hyperprobe-agent
```

***

## Initialization Walkthrough

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

**1. Create your initialization file**

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

```python hyperprobe_init.py theme={null}
import os

from hyperprobe import HyperProbe

HyperProbe.start({
    "service_id": "<service-uuid-from-dashboard>",
    "environment": os.getenv("HYPERPROBE_ENVIRONMENT") or os.getenv("PYTHON_ENV"),
    "broker_url": "https://logger.app.hyperprobe.co",
    "commit_sha": os.getenv("HYPERPROBE_COMMIT_SHA") or os.getenv("GIT_COMMIT"),
})
```

**2. Import it in your entrypoint**

In your main application file, import `hyperprobe_init` **as early as possible** before starting your application:

```python main.py theme={null}
import hyperprobe_init

from app import create_app

app = create_app()
```

> [!WARNING]
>
> **Environment Variables Loading Order:** If `hyperprobe_init.py` reads variables loaded by a library such as `python-dotenv`, load those variables before importing `hyperprobe_init`.

**3. 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:

```bash theme={null}
export HYPERPROBE_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`.

**4. Configure your Dockerfile**

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

```dockerfile Dockerfile theme={null}
ARG GIT_COMMIT=unknown
ENV GIT_COMMIT=${GIT_COMMIT}
```

**5. Run local Docker builds**

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

```bash theme={null}
docker build --build-arg GIT_COMMIT=$(git rev-parse HEAD) -t api:latest .
```

**6. Inject the correct SHA in CI/CD**

HyperProbe 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` |

> [!WARNING]
>
> 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 `HyperProbe.start()` options object, or by using **environment variables**.

The following example includes the available programmatic options and their corresponding environment variables:

```python hyperprobe_init.py theme={null}
import os

from hyperprobe import HyperProbe

HyperProbe.start({
    # --- CORE OPTIONS ---
    "service_id": "<service-uuid-from-dashboard>",
    "environment": os.getenv("HYPERPROBE_ENVIRONMENT") or os.getenv("PYTHON_ENV"),
    "broker_url": "https://logger.app.hyperprobe.co",
    "commit_sha": os.getenv("HYPERPROBE_COMMIT_SHA") or os.getenv("GIT_COMMIT"),

    # --- BUFFERING & PERFORMANCE ---
    "max_queue_size": 100,      # Env: HYPERPROBE_MAX_QUEUE_SIZE
    "flush_interval_ms": 1000,  # Env: HYPERPROBE_FLUSH_INTERVAL_MS
    "sync_interval_ms": 60000,  # Env: HYPERPROBE_SYNC_INTERVAL_MS

    # --- SAFETY GUARDRAILS ---
    "hits_per_sec": 10,         # Env: HYPERPROBE_HITS_PER_SEC
    "bandwidth_kb_per_sec": 1024, # Env: HYPERPROBE_BANDWIDTH_KB_PER_SEC
    "hyperprobe_max_lag_ms": 50, # Env: HYPERPROBE_MAX_LAG_MS
    "hyperprobe_pause_budget_ms": 15, # Env: HYPERPROBE_PAUSE_BUDGET_MS
    "hyperprobe_cooldown_sec": 10, # Env: HYPERPROBE_COOLDOWN_SEC
    "hyperprobe_rpc_timeout_sec": 10, # Env: HYPERPROBE_RPC_TIMEOUT_SEC

    # --- DATA & REDACTION CONTROLS ---
    "redact_keys": [            # Env: HYPERPROBE_REDACT_KEYS
        "password", "secret", "token", "authorization", "cookie", "key", "signature"
    ],
    "redact_values": [],        # Env: HYPERPROBE_REDACT_VALUES
    "max_object_depth": 3,      # Env: HYPERPROBE_MAX_OBJECT_DEPTH
    "max_array_length": 3,      # Env: HYPERPROBE_MAX_ARRAY_LENGTH
    "max_object_properties": 50, # Env: HYPERPROBE_MAX_OBJECT_PROPERTIES
    "max_string_length": 1024,  # Env: HYPERPROBE_MAX_STRING_LENGTH
    "stack_frame_depth": 3,     # Env: HYPERPROBE_STACK_FRAME_DEPTH
})
```

> [!TIP]
>
> * **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 `HYPERPROBE_SERVICE_ID`, `HYPERPROBE_ENVIRONMENT`, `HYPERPROBE_BROKER_URL`, and `HYPERPROBE_COMMIT_SHA` or `GIT_COMMIT`. If initialization fails, the application continues without the agent.
> * **Disabling the agent:** Set `HYPERPROBE_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.

> [!WARNING]
>
> 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 `HYPERPROBE_DISABLE_SAFE_EVALUATION=true` or pass `"disable_safe_evaluation": True` to `HyperProbe.start()`.

> [!WARNING]
>
> 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=hyperprobe:agent` before startup to see safety logs.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.