hyperprobe-agent 1.2.24__tar.gz

hyperprobe_agent-1.2.24/LICENSE

@@ -0,0 +1,13 @@
+Hyperprobe Proprietary License
+
+Copyright (c) 2026 Hyperprobe. All rights reserved.
+
+This software and its associated documentation are proprietary to Hyperprobe.
+No permission is granted to use, copy, modify, distribute, sublicense, or
+create derivative works except as expressly authorized under a written
+commercial license agreement with Hyperprobe.
+
+A valid commercial license from Hyperprobe is required to operate this
+software.
+
+For licensing inquiries, visit https://hyperprobe.co/.

hyperprobe_agent-1.2.24/PKG-INFO

@@ -0,0 +1,154 @@
+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()
+```

hyperprobe_agent-1.2.24/README.md

@@ -0,0 +1,119 @@
+# 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()
+```

hyperprobe_agent-1.2.24/hyperprobe/__init__.py

@@ -0,0 +1,7 @@
+__all__ = ["HyperProbe"]
+
+def __getattr__(name):
+    if name == "HyperProbe":
+        from hyperprobe.agent import HyperProbeAgent
+        return HyperProbeAgent
+    raise AttributeError(f"module '{__name__}' has no attribute '{name}'")