Python SDK Setup Guide

The HyperProbe Python SDK runs as an extremely lightweight in-process agent. It uses Python’s sys.monitoring APIs to capture variables, stack frames, and logs without blocking your application.

Technical Prerequisites

Runtime: Python 3.12 and later.
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 hyperprobe-agent

poetry add hyperprobe-agent

pipenv install hyperprobe-agent

uv add hyperprobe-agent

Initialization Walkthrough

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

Choose an initialization method

Select one of the following initialization methods:

Code Initialization
Auto Initialization

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

hyperprobe_init.py

import os

from hyperprobe import HyperProbe

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

Prepend your normal application startup command with the hyperprobe-run launcher:

export GIT_COMMIT=$(git rev-parse HEAD)
export HYPERPROBE_SERVICE_ID=<service-uuid-from-dashboard>
export HYPERPROBE_ENVIRONMENT=production
export HYPERPROBE_BROKER_URL=https://logger.app.hyperprobe.co

hyperprobe-run python main.py

This method works with standard Python scripts and WSGI/ASGI runners, such as gunicorn and uvicorn.

Import it in your entrypoint

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

main.py

import hyperprobe_init

from app import create_app

app = create_app()

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.

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 correct SHA in CI/CD (The PR Merge Trap)

To protect source alignment, HyperProbe refuses to start if commit_sha resolves to unknown. Pass the real commit SHA to GIT_COMMIT during deployment.Always use your CI/CD platform’s native commit SHA variable:

Platform / Engine	Configuration Option	Build Argument Syntax
GitHub Actions	PR-Safe HEAD Check (Recommended)	`--build-arg GIT_COMMIT=${{ github.event.pull_request.head.sha \|\| github.sha }}`
GitHub Actions (Push)	Standard Branch Push	`--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`

Beware of the PR Merge Commit Trap: By default, GitHub Actions checks out a virtual merge commit for a pull_request trigger instead of the commit from your branch.If you use git rev-parse HEAD or ${{ github.sha }} in a pull request workflow, source mapping can fail. Use ${{ github.event.pull_request.head.sha || github.sha }} for pull request builds.

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:

hyperprobe_init.py

import os

from hyperprobe import HyperProbe

HyperProbe.start({
    # --- CORE OPTIONS ---
    "service_id": "<service-uuid-from-dashboard>",
    "environment": os.getenv("PYTHON_ENV"),
    "broker_url": "https://logger.app.hyperprobe.co",
    "commit_sha": 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

    # --- 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
})

Safety Shields

Because dynamic monitoring could affect application performance during heavy execution spikes, the Python Agent includes active Safety Shields:

Yellow Threshold: Logs a warning when execution lag or cumulative pause time reaches 50% of its limit.
Red Threshold: Suspends tracing when execution lag exceeds 50 ms or cumulative pause time exceeds 15 ms.
Auto-Recovery: Resumes instrumentation after the cooldown period when application performance stabilizes.

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

Safety Shields

​Technical Prerequisites

​Installation

​Initialization Walkthrough

​Configuration & Environment Variables Reference

​Safety Shields

Technical Prerequisites

Installation

Initialization Walkthrough

Configuration & Environment Variables Reference

Safety Shields