HyperProbe Python Agent

Production-grade, non-breaking live debugger and telemetry agent for Python.

HyperProbe allows you to debug running Python applications in real-time without breaking them, restarting them, or altering production traffic. It leverages modern Python's fast, low-overhead monitoring APIs (sys.monitoring) to securely and dynamically extract stack frames, local variables, and logs at targeted lines.

Features

• Non-Breaking Snapshot Probes: Capture local variables and stack traces dynamically at any line of code.
• Dynamic Log Probes: Inject live log templates to print formatted output without redeploying code.
• Counter Probes: Emit a value of 1 whenever a configured source line is reached.
• Metric Probes: Safely evaluate a numerical Python expression and emit its value.
• Duration Probes: Measure elapsed monotonic time in milliseconds between two source lines, with optional request correlation.
• Zero-Code-Change Auto-Instrumentation: Prepend our bootstrap runtime to any Python process without editing your application's code.
• Circular Reference & Deep Object Protection: Memory-safe serialization of deeply nested or cyclic variables.
• High-Performance Safety Guard: Automatically pauses monitoring and goes idle if CPU/memory boundaries or pause budgets are exceeded.

Metric-family probes

Counter, metric, and duration probes are created through HyperProbe in the same way as snapshot and log probes. No application code changes or additional public SDK calls are required.

Conditions are evaluated at every configured location. Metric expressions use the same restricted, read-only Python evaluator as conditions and watches. Numerical strings follow Node SDK parseFloat behavior for compatibility; invalid or non-finite values are exported with metric_value set to 0 and a populated capture_error.

Duration correlation expressions must evaluate to a string or number. When omitted or when they evaluate to None, a singleton correlation key is used. Unmatched duration ends are ignored, and pending starts expire after 60 seconds.

Installation

Install the package via pip (or testpypi for testing):

pip install hyperprobe-agent

Usage

Run your application using the hyperprobe-run launcher. This automatically injects the live-debugging runtime before your code executes:

HYPERPROBE_BROKER_URL="https://logger.app.hyperprobe.co" \
HYPERPROBE_SERVICE_ID="<service-uuid-from-dashboard>" \
HYPERPROBE_ENVIRONMENT="development" \
GIT_COMMIT=$(git rev-parse HEAD) \
hyperprobe-run python app.py

Configuration Environment Variables

Configure the agent using the following environment variables:

Debug logging

Set DEBUG to a comma- or space-separated list of namespaces. Patterns accept *, and exclusions begin with -:

DEBUG=hyperprobe*                               # all HyperProbe SDK logs
DEBUG=hyperprobe:broker,hyperprobe:monitor      # selected components
DEBUG=hyperprobe*,-hyperprobe:evaluator         # exclude a component
DEBUG_COLORS=1                                  # force ANSI colors

Without *, a selector is exact: DEBUG=hyperprobe does not match hyperprobe:agent. Use DEBUG=hyperprobe* to enable every component. Set DEBUG_COLORS=0 to disable colors. Logging configuration is read during SDK initialization, so set these variables before starting the process.

Programmatic Usage (Inside Your Code)

If you prefer to start the agent directly inside your Python script instead of using the hyperprobe-run launcher, you can do so by importing the package and calling HyperProbe.start() programmatically.

This is useful for applications where you want to control exactly when the agent boots up or configure the agent dynamically at runtime:

import os
from hyperprobe import HyperProbe

# Start the agent programmatically at your application's entrypoint
agent = HyperProbe.start({
    "service_id": "<service-uuid-from-dashboard>",
    "environment": os.getenv("PYTHON_ENV"),  # Your environment name (e.g. dev, staging, production). Use whatever variable contains the env value.
    "broker_url": "https://logger.app.hyperprobe.co",
    "commit_sha": os.getenv("GIT_COMMIT"),  # CI-injected commit SHA (reads os.getenv("GIT_COMMIT") by default)
})

# Your application code goes here...

# To cleanly shut down the agent when your app stops:
HyperProbe.shutdown()