Metadata-Version: 2.4
Name: hyperprobe-agent
Version: 1.2.24
Summary: Production-grade, non-breaking live debugger and telemetry agent for Python.
Home-page: https://www.hyperprobe.co
Author: Arif, Saksham, Karan
Author-email: arif@hypertest.co, saksham@hypertest.co, karan@hypertest.co
License: Hyperprobe Proprietary License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Operating System :: OS Independent
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: protobuf<6.0.0,>=4.25.3
Requires-Dist: grpcio>=1.62.2
Provides-Extra: dev
Requires-Dist: grpcio>=1.50.0; extra == "dev"
Requires-Dist: grpcio-tools>=1.50.0; extra == "dev"
Requires-Dist: protobuf>=4.21.0; extra == "dev"
Requires-Dist: pytest>=7.0.0; extra == "dev"
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: license
Dynamic: license-file
Dynamic: provides-extra
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

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

```bash
pip install hyperprobe-agent
```

## Usage

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

```bash
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 `-`:

```bash
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:

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