hyperprobe-agent 1.2.24

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

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.

Probe	Configuration	Emitted metric_value
Counter	metric_name and one runtime location	1 per matching hit
Metric	metric_name, metric_expression, and one runtime location	The finite numerical expression result
Duration	metric_name, primary and secondary runtime locations, and optional correlation_expression	Monotonic elapsed milliseconds

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:

Variable	Description	Default
HYPERPROBE_BROKER_URL	The URL of the HyperProbe Telemetry Broker.	Required
HYPERPROBE_SERVICE_ID	A unique name identifying this service.	Required
HYPERPROBE_ENVIRONMENT	Deployment environment name (e.g., production, staging).	Required
HYPERPROBE_COMMIT_SHA or GIT_COMMIT	Git commit SHA of the running application version.	Required
HYPERPROBE_DISABLED	Set to YES to explicitly disable the agent.	(unset)
HYPERPROBE_SYNC_INTERVAL_MS	Rate at which the agent syncs probe definitions from the broker.	60000 (1 min)
HYPERPROBE_FLUSH_INTERVAL_MS	Delay before sending telemetry events to the broker.	1000 (1 sec)
HYPERPROBE_MAX_QUEUE_SIZE	Maximum number of telemetry events held before flush.	100
HYPERPROBE_HITS_PER_SEC	Max snapshot capture requests per second (quota).	10
HYPERPROBE_BANDWIDTH_KB_PER_SEC	Max bandwidth limit for telemetry transmissions (quota).	1024 (1 MB)
HYPERPROBE_RPC_TIMEOUT_SEC	Deadline for broker RPCs.	10
HYPERPROBE_COOLDOWN_SEC	Tracing suspension duration after a RED safety state.	10
HYPERPROBE_MAX_LAG_MS	Execution-thread lag threshold for the safety monitor.	50
HYPERPROBE_PAUSE_BUDGET_MS	Per-second capture pause budget for the safety monitor.	15
HYPERPROBE_REDACT_KEYS	Comma-separated key patterns to redact.	password,secret,token,authorization,cookie,key,signature
HYPERPROBE_REDACT_VALUES	Comma-separated value patterns to redact.	(empty)
HYPERPROBE_MAX_OBJECT_DEPTH	Maximum serialized object depth.	3
HYPERPROBE_MAX_ARRAY_LENGTH	Maximum serialized array length.	3
HYPERPROBE_STACK_FRAME_DEPTH	Maximum captured stack-frame depth.	3
HYPERPROBE_MAX_OBJECT_PROPERTIES	Maximum serialized properties per object.	50
HYPERPROBE_MAX_STRING_LENGTH	Maximum serialized string length.	1024

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()