hyperprobe-agent 1.2.25b9__tar.gz → 1.2.26__tar.gz

{hyperprobe_agent-1.2.25b9 → hyperprobe_agent-1.2.26}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: hyperprobe-agent
-Version: 1.2.25b9
+Version: 1.2.26
 Summary: Production-grade, non-breaking live debugger and telemetry agent for Python.
 Home-page: https://www.hyperprobe.co
 Author: Arif, Saksham, Karan
@@ -46,7 +46,6 @@ HyperProbe allows you to debug running Python applications in real-time without
 - **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.
 
@@ -74,16 +73,24 @@ pip install hyperprobe-agent
 
 ## Usage
 
-Run your application using the `hyperprobe-run` launcher. This automatically injects the live-debugging runtime before your code executes:
+Start the agent programmatically at your application's entrypoint:
 
-```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
+```python
+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:
@@ -102,7 +109,7 @@ Configure the agent using the following environment variables:
 | `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_MAX_LAG_MS` | Per-reading scheduler-lag threshold. YELLOW requires 4/10 breaches; RED requires 7/10 breaches or 3/5 readings above 4x the threshold. | `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)* |
@@ -111,6 +118,7 @@ Configure the agent using the following environment variables:
 | `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` |
+| `HYPERPROBE_FORK_MODE` | Set to `worker` for preloaded, prefork servers. The parent defers agent initialization and every worker starts fresh process-local state. | `none` |
 
 ### Debug logging
 
@@ -118,9 +126,9 @@ 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:*                               # all HyperProbe SDK logs
 DEBUG=hyperprobe:broker,hyperprobe:monitor      # selected components
-DEBUG=hyperprobe*,-hyperprobe:evaluator         # exclude a component
+DEBUG=hyperprobe:*,-hyperprobe:evaluator         # exclude a component
 DEBUG_COLORS=1                                  # force ANSI colors
 ```
 
@@ -129,26 +137,25 @@ Without `*`, a selector is exact: `DEBUG=hyperprobe` does not match
 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)
+## Shutdown
 
-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.
+Call `HyperProbe.shutdown()` when the application process stops to close
+monitoring, workers, and the broker connection cleanly.
 
-This is useful for applications where you want to control exactly when the agent boots up or configure the agent dynamically at runtime:
+For servers that import the application before forking workers, such as
+Gunicorn with `--preload`, enable worker fork mode:
 
 ```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.
+    "environment": os.getenv("PYTHON_ENV"),
     "broker_url": "https://logger.app.hyperprobe.co",
-    "commit_sha": os.getenv("GIT_COMMIT"),  # CI-injected commit SHA (reads os.getenv("GIT_COMMIT") by default)
+    "commit_sha": os.getenv("GIT_COMMIT"),
+    "fork_mode": "worker",
 })
-
-# Your application code goes here...
-
-# To cleanly shut down the agent when your app stops:
-HyperProbe.shutdown()
 ```
+
+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`.

{hyperprobe_agent-1.2.25b9 → hyperprobe_agent-1.2.26}/README.md

@@ -11,7 +11,6 @@ HyperProbe allows you to debug running Python applications in real-time without
 - **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.
 
@@ -39,16 +38,24 @@ pip install hyperprobe-agent
 
 ## Usage
 
-Run your application using the `hyperprobe-run` launcher. This automatically injects the live-debugging runtime before your code executes:
+Start the agent programmatically at your application's entrypoint:
 
-```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
+```python
+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:
@@ -67,7 +74,7 @@ Configure the agent using the following environment variables:
 | `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_MAX_LAG_MS` | Per-reading scheduler-lag threshold. YELLOW requires 4/10 breaches; RED requires 7/10 breaches or 3/5 readings above 4x the threshold. | `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)* |
@@ -76,6 +83,7 @@ Configure the agent using the following environment variables:
 | `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` |
+| `HYPERPROBE_FORK_MODE` | Set to `worker` for preloaded, prefork servers. The parent defers agent initialization and every worker starts fresh process-local state. | `none` |
 
 ### Debug logging
 
@@ -83,9 +91,9 @@ 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:*                               # all HyperProbe SDK logs
 DEBUG=hyperprobe:broker,hyperprobe:monitor      # selected components
-DEBUG=hyperprobe*,-hyperprobe:evaluator         # exclude a component
+DEBUG=hyperprobe:*,-hyperprobe:evaluator         # exclude a component
 DEBUG_COLORS=1                                  # force ANSI colors
 ```
 
@@ -94,26 +102,25 @@ Without `*`, a selector is exact: `DEBUG=hyperprobe` does not match
 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)
+## Shutdown
 
-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.
+Call `HyperProbe.shutdown()` when the application process stops to close
+monitoring, workers, and the broker connection cleanly.
 
-This is useful for applications where you want to control exactly when the agent boots up or configure the agent dynamically at runtime:
+For servers that import the application before forking workers, such as
+Gunicorn with `--preload`, enable worker fork mode:
 
 ```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.
+    "environment": os.getenv("PYTHON_ENV"),
     "broker_url": "https://logger.app.hyperprobe.co",
-    "commit_sha": os.getenv("GIT_COMMIT"),  # CI-injected commit SHA (reads os.getenv("GIT_COMMIT") by default)
+    "commit_sha": os.getenv("GIT_COMMIT"),
+    "fork_mode": "worker",
 })
-
-# Your application code goes here...
-
-# To cleanly shut down the agent when your app stops:
-HyperProbe.shutdown()
 ```
+
+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`.