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.
• 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

Start the agent programmatically at your application's entrypoint:

import os
from hyperprobe import HyperProbe

agent = 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"),
})

Required identity values may also be supplied through the environment variables below. Explicit options take precedence. Initialization failures are reported and the application continues without instrumentation.

Configuration Environment Variables

Configure the agent using the following environment variables:

Programmatic integrations can set allow_non_uuid=True for the same legacy bypass. Without an explicit bypass, a non-UUIDv4 service ID prevents agent startup while the host application continues normally.

Safe Evaluation & Security Considerations

By default, safe evaluation is enabled (HYPERPROBE_DISABLE_SAFE_EVALUATION=false). In safe mode:

• Method and function calls are strictly restricted to a narrow allowlist of side-effect free standard operations.
• State mutations, assignments, and arbitrary function invocations (such as database calls, network I/O, file operations, or state modifications) are prevented.

Disabling Safe Evaluation (HYPERPROBE_DISABLE_SAFE_EVALUATION=true):

⚠️ Security Warning: Setting HYPERPROBE_DISABLE_SAFE_EVALUATION=true allows conditions, watch expressions, and log templates to execute arbitrary functions and methods in the host application process. This may lead to unintended side effects, state mutations, performance degradation, or security risks if expressions invoke mutating or blocking operations. Only disable safe evaluation in trusted environments where dynamic method evaluation is strictly required.

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.

Shutdown

Call HyperProbe.shutdown() when the application process stops to close monitoring, workers, and the broker connection cleanly.

For servers that import the application before forking workers, such as Gunicorn with --preload, enable worker fork mode:

agent = 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"),
    "fork_mode": "worker",
})

The prefork parent remains agent-free. Every worker receives a unique agent ID, telemetry queue, gRPC channel, monitoring engine, and set of background threads. Application code running inside those workers must use the spawn process start method rather than creating additional children with fork.