hyperprobe-agent 1.2.30b4__tar.gz → 1.2.31__tar.gz

{hyperprobe_agent-1.2.30b4/hyperprobe_agent.egg-info → hyperprobe_agent-1.2.31}/PKG-INFO

@@ -1,20 +1,30 @@
 Metadata-Version: 2.4
 Name: hyperprobe-agent
-Version: 1.2.30b4
+Version: 1.2.31
 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.7
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
 Classifier: Operating System :: OS Independent
-Requires-Python: >=3.12
+Requires-Python: >=3.7
 Description-Content-Type: text/markdown
 License-File: LICENSE
-Requires-Dist: protobuf<6.0.0,>=4.25.3
-Requires-Dist: grpcio>=1.62.2
+Requires-Dist: protobuf<4.25,>=4.24.4; python_version < "3.8"
+Requires-Dist: protobuf<6.0.0,>=4.25.3; python_version >= "3.8"
+Requires-Dist: grpcio<1.63,>=1.62.2; python_version < "3.8"
+Requires-Dist: grpcio>=1.62.2; python_version >= "3.8"
+Requires-Dist: importlib-metadata<7,>=6; python_version < "3.8"
+Requires-Dist: bytecode==0.13.0; python_version < "3.8"
+Requires-Dist: bytecode==0.16.2; python_version >= "3.8" and python_version < "3.12"
 Provides-Extra: dev
 Requires-Dist: grpcio>=1.50.0; extra == "dev"
 Requires-Dist: grpcio-tools>=1.50.0; extra == "dev"
@@ -37,17 +47,64 @@ Dynamic: summary
 
 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.
+HyperProbe captures stack frames, local variables, and logs at selected source
+lines without stopping the application in a debugger. At agent initialization,
+Python 3.12+ selects the `sys.monitoring` backend. CPython 3.7–3.11 selects the
+bytecode backend. Both support snapshot, log, counter, metric, and duration
+probes and use the same broker, evaluator, serializer, quotas, safety monitor,
+and output pipeline.
+Only the selected backend is imported; `bytecode` is not a dependency on 3.12+.
 
 ## 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.
+- **Metric Probes:** 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.
+- **Safety Guard:** Suspends instrumentation when scheduler lag or the capture pause budget crosses its configured threshold.
+
+## Bytecode backend (CPython 3.7–3.11)
+
+The broker still supplies `runtime_location` and `runtime_line`. The backend
+uses the existing path resolver, locates functions through their loaded modules,
+and replaces only the selected functions' code objects. It does not use
+`sys.settrace`, `threading.settrace`, or a heap-wide `gc.get_objects()` scan.
+Pending probes can watch standard file imports; the normal loader executes the
+module after the SDK prepares its code. Loaded factories can register and
+instrument nested functions they create later. Conditions, watches, redaction,
+trace IDs, hit limits, and telemetry use the shared services. Duration probes
+index both source locations, including an end line in a later-imported module.
+
+This backend also selects its own agent lifecycle controller at startup; the
+Python 3.12+ lifecycle and `sys.monitoring` implementation remain separate.
+Broker responses are compared against stable local definition records. An
+unchanged response (including reordered probes) does no module discovery,
+function planning, or bytecode rewriting. Condition, watch, and template changes
+replace evaluation state without rebuilding bytecode. Location changes discover
+the new target and replan affected functions; removal uses tracked functions.
+Callback-site tokens are held weakly, so short-lived nested functions do not
+accumulate permanent lookup entries.
+Broker-confirmed completed probes stay disabled until the broker removes them.
+
+On RED, the backend closes its capture gate and synchronously restores the
+saved original code for functions it still owns, including factories. Pending
+import work cannot install new probes while suspended. Restoration runs before
+agent bookkeeping or logging, and recovery builds bytecode without holding the
+agent lock. Capture delivery checks the original definition identity and
+activation generation before queue admission, so an old capture cannot be
+accepted under an updated definition or after RED/recovery. A frame already running
+keeps its existing code, but its callbacks become no-ops. An expression already
+running cannot be forcibly interrupted safely. Instrumentation failures are
+reported through bounded engine diagnostics and best-effort error logging;
+normal exceptions from the application's own function or module still propagate.
+
+Discovery supports module/class namespaces and bounded built-in containers.
+Arbitrary generated code, custom loaders, hidden pre-existing closures, and
+automatic reload coverage are not guaranteed. Function prologues are not probe
+locations. Performance, including a 2% overhead target, requires workload-based
+measurement; the shared evaluator is not a security sandbox.
 
 ## Metric-family probes
 
@@ -59,9 +116,9 @@ Counter, metric, and duration probes are created through HyperProbe in the same
 | 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`.
+Conditions are evaluated at every configured location. Metric expressions use the same restricted Python evaluator as conditions and watches. Numerical strings follow Node SDK `parseFloat` prefix behavior for compatibility; invalid or non-finite values are exported with `metric_value` set to `0` and a populated `capture_error`. The bytecode backend examines at most the first 1,024 characters of a metric string.
 
-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.
+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. On CPython 3.7–3.11, correlation keys are limited to 256 characters and at most 4,096 starts are kept per process; the oldest start is evicted if that limit is reached. Duration starts never consume a probe hit. A matching end consumes the hit when its event is admitted to the telemetry queue.
 
 ## Installation
 
@@ -106,7 +163,7 @@ Configure the agent using the following environment variables:
 | `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_HITS_PER_SEC` | Max quota-charged probe evaluations per second. | `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` |
@@ -128,9 +185,20 @@ 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.
+Captured strings are checked against configured value-redaction patterns before
+truncation. When value rules are configured, a string longer than 16,384
+characters is masked rather than scanned partially. Log substitutions use the
+bounded serializer, so nested sensitive keys are masked before an object becomes
+log text. Telemetry errors carry categories rather than raw runtime values or
+exception messages. These rules do not infer the origin of an arbitrary watch
+result: a scalar watch expression such as `password` can still expose its value
+when no value pattern matches it.
+
+By default, **safe evaluation is enabled** (`HYPERPROBE_DISABLE_SAFE_EVALUATION=false`).
+The existing evaluator checks function and method names against an allowlist.
+This reduces available operations but is not a sandbox: properties, overloaded
+operators, or allowed method names on custom objects can still execute
+application code. There is no hard timeout that can interrupt such code safely.
 
 **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.

hyperprobe_agent-1.2.30b4/PKG-INFO → hyperprobe_agent-1.2.31/README.md

@@ -1,53 +1,65 @@
-Metadata-Version: 2.4
-Name: hyperprobe-agent
-Version: 1.2.30b4
-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.
+HyperProbe captures stack frames, local variables, and logs at selected source
+lines without stopping the application in a debugger. At agent initialization,
+Python 3.12+ selects the `sys.monitoring` backend. CPython 3.7–3.11 selects the
+bytecode backend. Both support snapshot, log, counter, metric, and duration
+probes and use the same broker, evaluator, serializer, quotas, safety monitor,
+and output pipeline.
+Only the selected backend is imported; `bytecode` is not a dependency on 3.12+.
 
 ## 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.
+- **Metric Probes:** 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.
+- **Safety Guard:** Suspends instrumentation when scheduler lag or the capture pause budget crosses its configured threshold.
+
+## Bytecode backend (CPython 3.7–3.11)
+
+The broker still supplies `runtime_location` and `runtime_line`. The backend
+uses the existing path resolver, locates functions through their loaded modules,
+and replaces only the selected functions' code objects. It does not use
+`sys.settrace`, `threading.settrace`, or a heap-wide `gc.get_objects()` scan.
+Pending probes can watch standard file imports; the normal loader executes the
+module after the SDK prepares its code. Loaded factories can register and
+instrument nested functions they create later. Conditions, watches, redaction,
+trace IDs, hit limits, and telemetry use the shared services. Duration probes
+index both source locations, including an end line in a later-imported module.
+
+This backend also selects its own agent lifecycle controller at startup; the
+Python 3.12+ lifecycle and `sys.monitoring` implementation remain separate.
+Broker responses are compared against stable local definition records. An
+unchanged response (including reordered probes) does no module discovery,
+function planning, or bytecode rewriting. Condition, watch, and template changes
+replace evaluation state without rebuilding bytecode. Location changes discover
+the new target and replan affected functions; removal uses tracked functions.
+Callback-site tokens are held weakly, so short-lived nested functions do not
+accumulate permanent lookup entries.
+Broker-confirmed completed probes stay disabled until the broker removes them.
+
+On RED, the backend closes its capture gate and synchronously restores the
+saved original code for functions it still owns, including factories. Pending
+import work cannot install new probes while suspended. Restoration runs before
+agent bookkeeping or logging, and recovery builds bytecode without holding the
+agent lock. Capture delivery checks the original definition identity and
+activation generation before queue admission, so an old capture cannot be
+accepted under an updated definition or after RED/recovery. A frame already running
+keeps its existing code, but its callbacks become no-ops. An expression already
+running cannot be forcibly interrupted safely. Instrumentation failures are
+reported through bounded engine diagnostics and best-effort error logging;
+normal exceptions from the application's own function or module still propagate.
+
+Discovery supports module/class namespaces and bounded built-in containers.
+Arbitrary generated code, custom loaders, hidden pre-existing closures, and
+automatic reload coverage are not guaranteed. Function prologues are not probe
+locations. Performance, including a 2% overhead target, requires workload-based
+measurement; the shared evaluator is not a security sandbox.
 
 ## Metric-family probes
 
@@ -59,9 +71,9 @@ Counter, metric, and duration probes are created through HyperProbe in the same
 | 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`.
+Conditions are evaluated at every configured location. Metric expressions use the same restricted Python evaluator as conditions and watches. Numerical strings follow Node SDK `parseFloat` prefix behavior for compatibility; invalid or non-finite values are exported with `metric_value` set to `0` and a populated `capture_error`. The bytecode backend examines at most the first 1,024 characters of a metric string.
 
-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.
+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. On CPython 3.7–3.11, correlation keys are limited to 256 characters and at most 4,096 starts are kept per process; the oldest start is evicted if that limit is reached. Duration starts never consume a probe hit. A matching end consumes the hit when its event is admitted to the telemetry queue.
 
 ## Installation
 
@@ -106,7 +118,7 @@ Configure the agent using the following environment variables:
 | `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_HITS_PER_SEC` | Max quota-charged probe evaluations per second. | `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` |
@@ -128,9 +140,20 @@ 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.
+Captured strings are checked against configured value-redaction patterns before
+truncation. When value rules are configured, a string longer than 16,384
+characters is masked rather than scanned partially. Log substitutions use the
+bounded serializer, so nested sensitive keys are masked before an object becomes
+log text. Telemetry errors carry categories rather than raw runtime values or
+exception messages. These rules do not infer the origin of an arbitrary watch
+result: a scalar watch expression such as `password` can still expose its value
+when no value pattern matches it.
+
+By default, **safe evaluation is enabled** (`HYPERPROBE_DISABLE_SAFE_EVALUATION=false`).
+The existing evaluator checks function and method names against an allowlist.
+This reduces available operations but is not a sandbox: properties, overloaded
+operators, or allowed method names on custom objects can still execute
+application code. There is no hard timeout that can interrupt such code safely.
 
 **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.

{hyperprobe_agent-1.2.30b4 → hyperprobe_agent-1.2.31}/hyperprobe/agent.py

@@ -5,6 +5,7 @@ import time
 import threading
 import queue
 import re
+import math
 from urllib.parse import urlparse
 
 from hyperprobe.core.quota import QuotaManager
@@ -28,6 +29,48 @@ class _TelemetryItem:
         self.bandwidth_reservation = bandwidth_reservation
 
 
+def _numeric_option(
+    options, option_name, env_name, default, *, integer=False,
+    allow_zero=False, scale=1.0, max_value=None,
+):
+    """Validate an option or environment value before allocating SDK resources."""
+    value = options.get(option_name)
+    if value is None:
+        value = os.getenv(env_name, default)
+
+    requirement = "a positive integer" if integer else (
+        "a non-negative finite number" if allow_zero else "a positive finite number"
+    )
+    if max_value is not None:
+        requirement += " within the platform's timeout range"
+
+    try:
+        if isinstance(value, bool):
+            raise ValueError("Boolean configuration is not numeric")
+        if integer:
+            if not isinstance(value, (int, str)):
+                raise ValueError("Integer configuration must not be fractional")
+            parsed = int(value)
+        else:
+            parsed = float(value)
+            if not math.isfinite(parsed):
+                raise ValueError("Configuration must be finite")
+            parsed *= scale
+            if not math.isfinite(parsed):
+                raise ValueError("Converted configuration must be finite")
+        if parsed < 0 or (not allow_zero and parsed == 0):
+            raise ValueError("Configuration is outside its allowed range")
+        if max_value is not None and parsed > max_value:
+            raise ValueError("Configuration exceeds the platform's timeout range")
+        return parsed
+    except (TypeError, ValueError, OverflowError):
+        message = "[HyperProbe] Invalid configuration: %s (%s) must be %s." % (
+            option_name, env_name, requirement,
+        )
+        logger.forceError(message)
+        raise ValueError("Invalid numeric configuration: " + option_name) from None
+
+
 def is_valid_broker_url(url):
     if not url or not str(url).strip():
         return False
@@ -66,17 +109,39 @@ class HyperProbeAgent:
         if self.fork_mode not in {"none", "worker"}:
             raise ValueError('fork_mode must be either "none" or "worker"')
 
-        # Options & Envs Parsing
-        self.sync_interval_sec = (options.get("sync_interval_ms") or int(os.getenv("HYPERPROBE_SYNC_INTERVAL_MS", 60000))) / 1000.0
-        self.flush_interval_sec = (options.get("flush_interval_ms") or int(os.getenv("HYPERPROBE_FLUSH_INTERVAL_MS", 1000))) / 1000.0
-        self.max_queue_size = options.get("max_queue_size") or int(os.getenv("HYPERPROBE_MAX_QUEUE_SIZE", 100))
-        self._cooldown_sec = options.get("hyperprobe_cooldown_sec") or int(os.getenv("HYPERPROBE_COOLDOWN_SEC", 10))
-
-        hits_per_sec = options.get("hits_per_sec") or int(os.getenv("HYPERPROBE_HITS_PER_SEC", 10))
-        bandwidth_kb = options.get("bandwidth_kb_per_sec") or int(os.getenv("HYPERPROBE_BANDWIDTH_KB_PER_SEC", 1024))
-        rpc_timeout_sec = options.get("hyperprobe_rpc_timeout_sec") or float(os.getenv("HYPERPROBE_RPC_TIMEOUT_SEC", 10.0))
-        max_lag_ms = options.get("hyperprobe_max_lag_ms") or float(os.getenv("HYPERPROBE_MAX_LAG_MS", 50.0))
-        pause_budget_ms = options.get("hyperprobe_pause_budget_ms") or float(os.getenv("HYPERPROBE_PAUSE_BUDGET_MS", 15.0))
+        # Validate operational settings before creating process resources.
+        self.sync_interval_sec = _numeric_option(
+            options, "sync_interval_ms", "HYPERPROBE_SYNC_INTERVAL_MS", 60000,
+            scale=0.001, max_value=threading.TIMEOUT_MAX,
+        )
+        self.flush_interval_sec = _numeric_option(
+            options, "flush_interval_ms", "HYPERPROBE_FLUSH_INTERVAL_MS", 1000,
+            scale=0.001, max_value=threading.TIMEOUT_MAX,
+        )
+        self.max_queue_size = _numeric_option(
+            options, "max_queue_size", "HYPERPROBE_MAX_QUEUE_SIZE", 100,
+            integer=True,
+        )
+        self._cooldown_sec = _numeric_option(
+            options, "hyperprobe_cooldown_sec", "HYPERPROBE_COOLDOWN_SEC", 10,
+            allow_zero=True, max_value=threading.TIMEOUT_MAX,
+        )
+        hits_per_sec = _numeric_option(
+            options, "hits_per_sec", "HYPERPROBE_HITS_PER_SEC", 10,
+        )
+        bandwidth_bytes = _numeric_option(
+            options, "bandwidth_kb_per_sec", "HYPERPROBE_BANDWIDTH_KB_PER_SEC", 1024,
+            scale=1024.0,
+        )
+        rpc_timeout_sec = _numeric_option(
+            options, "hyperprobe_rpc_timeout_sec", "HYPERPROBE_RPC_TIMEOUT_SEC", 10.0,
+        )
+        max_lag_ms = _numeric_option(
+            options, "hyperprobe_max_lag_ms", "HYPERPROBE_MAX_LAG_MS", 50.0,
+        )
+        pause_budget_ms = _numeric_option(
+            options, "hyperprobe_pause_budget_ms", "HYPERPROBE_PAUSE_BUDGET_MS", 15.0,
+        )
 
         opt_disable_safe_eval = options.get("disable_safe_evaluation", False)
         disable_safe_eval = (
@@ -110,7 +175,7 @@ class HyperProbeAgent:
         self.global_config["redact_values"] = [v.strip() for v in self.global_config["redact_values"] if v.strip()]
 
         # Initialize core telemetry components
-        self.quota_manager = QuotaManager(hits_per_sec, bandwidth_kb * 1024)
+        self.quota_manager = QuotaManager(hits_per_sec, bandwidth_bytes)
         self.safety_monitor = SafetyMonitor(
             self._handle_health_change,
             max_lag_ms=max_lag_ms,
@@ -140,7 +205,9 @@ class HyperProbeAgent:
 
         # Determine and initialize dynamic instrumentation engine
         self.engine = self._init_instrumentation_engine()
-        self.engine.set_global_config(self.global_config)
+        self.supported_probe_types = self.engine.supported_probe_types
+        if not self.engine.set_global_config(self.global_config):
+            raise ValueError("Initial capture configuration could not be applied")
 
         # Background worker threads
         self.sync_thread = None
@@ -150,7 +217,11 @@ class HyperProbeAgent:
     @classmethod
     def start(cls, options):
         """Starts the global HyperProbe Agent singleton."""
-        options = dict(options or {})
+        try:
+            options = dict(options or {})
+        except Exception:
+            logger.forceError("[HyperProbe] Agent options must be a mapping. Running application uninstrumented.")
+            return None
         with cls._lock:
             if (
                 cls._fork_owner_pid == os.getpid()
@@ -241,7 +312,7 @@ class HyperProbeAgent:
                 cls._instance = None
                 logger.forceError(
                     f"[HyperProbe] Agent failed to initialize "
-                    f"({type(exc).__name__}: {exc}). "
+                    f"({type(exc).__name__}). "
                     "Running application uninstrumented."
                 )
                 return None
@@ -335,7 +406,7 @@ class HyperProbeAgent:
             instance._cleanup_failed_start()
             cls._instance = None
             logger.forceError(
-                f"[HyperProbe] Failed to restart the agent after fork: {exc}"
+                f"[HyperProbe] Failed to restart the agent after fork ({type(exc).__name__})."
             )
             return
 
@@ -360,7 +431,7 @@ class HyperProbeAgent:
             cls._instance = None
             if cls._fork_owner_pid == os.getpid():
                 cls._clear_fork_state_locked()
-            print("[HyperProbe] Python agent successfully shut down.")
+            logger.forceInfo("[HyperProbe] Python agent successfully shut down.")
 
     @classmethod
     def _clear_fork_state_locked(cls):
@@ -370,8 +441,20 @@ class HyperProbeAgent:
         cls._fork_pending = False
 
     def _init_instrumentation_engine(self):
-        from hyperprobe.core.monitoring_engine import MonitoringEngine
-        return MonitoringEngine(
+        if sys.version_info >= (3, 12):
+            from hyperprobe.core.monitoring_engine import MonitoringEngine
+            engine_class = MonitoringEngine
+        elif sys.version_info >= (3, 7):
+            from hyperprobe.core.bytecode.controller import BytecodeController
+            from hyperprobe.core.bytecode.engine import BytecodeEngine
+            # Select lifecycle handlers once. Python 3.12+ keeps the existing
+            # monitoring handlers, without runtime branches on captures/polls.
+            self._bytecode_controller = BytecodeController(self)
+            self._bytecode_controller.bind()
+            engine_class = BytecodeEngine
+        else:
+            raise RuntimeError("HyperProbe requires Python 3.7 or newer")
+        return engine_class(
             self.quota_manager,
             self.safety_monitor,
             self._handle_capture,
@@ -531,7 +614,7 @@ class HyperProbeAgent:
         # Only activate probe types implemented by this SDK.
         server_probes = {}
         for probe in response.probes:
-            if probe.type in SUPPORTED_PROBE_TYPES:
+            if probe.type in getattr(self, "supported_probe_types", SUPPORTED_PROBE_TYPES):
                 server_probes[probe.id] = probe
             else:
                 msg = f"[HyperProbe] Ignoring unsupported probe type {probe.type} for probe {probe.id}."
@@ -582,8 +665,8 @@ class HyperProbeAgent:
         batch = self._inflight_batch
         if batch is None:
             batch = []
-            # Pull all currently queued events up to capacity. Keep the batch
-            # in-flight until the broker call succeeds so retries cannot lose it.
+            # Concurrent producers can keep this drain going beyond queue capacity.
+            # Keep the batch in flight until the broker confirms delivery.
             while not self.telemetry_queue.empty():
                 try:
                     item = self.telemetry_queue.get_nowait()
@@ -670,18 +753,37 @@ class HyperProbeAgent:
             return list(self.active_probes.values())
 
     def _handle_capture(self, event):
+        try:
+            return self._handle_capture_impl(event)
+        except BaseException as error:
+            # This callback runs inside an application frame via either backend.
+            # Even a broken diagnostic stream must not let SDK errors escape.
+            try:
+                report = getattr(self.engine, "_record_failure", None)
+                if report is not None:
+                    report("capture admission", error)
+                    return
+                logger.forceError(
+                    "[HyperProbe] Capture admission failed (%s)." % type(error).__name__
+                )
+            except BaseException:
+                pass
+
+    def _handle_capture_impl(self, event):
         if (
             getattr(self, "owner_pid", os.getpid()) != os.getpid()
             or getattr(self, "is_shutdown", False)
+            or getattr(self.engine, "is_suspended", False)
         ):
             return
+        generation = getattr(self.engine, "_generation", None)
         probe_id = event["probe_id"]
         with self._agent_lock:
             probe = self.active_probes.get(probe_id)
             if not probe:
                 return
 
-            if probe.type not in SUPPORTED_PROBE_TYPES:
+            if probe.type not in getattr(self, "supported_probe_types", SUPPORTED_PROBE_TYPES):
                 return
 
         if not self._reserve_hit_slot(probe_id, probe):
@@ -697,7 +799,11 @@ class HyperProbeAgent:
             self._release_hit_slot(probe_id)
             return
 
-        bandwidth_reservation = self.quota_manager.reserve_bandwidth(event_size)
+        try:
+            bandwidth_reservation = self.quota_manager.reserve_bandwidth(event_size)
+        except BaseException:
+            self._release_hit_slot(probe_id)
+            raise
         if bandwidth_reservation is None:
             msg = f"[HyperProbe] Bandwidth quota exceeded; dropping event for probe {probe_id} , event size was : {event_size} bytes."
             logger.error(msg)
@@ -706,14 +812,24 @@ class HyperProbeAgent:
 
         # Hold the bandwidth reservation with the event until the broker
         # confirms the batch. Release it if local queue admission fails.
-        item = _TelemetryItem(event, bandwidth_reservation)
         try:
-            self.telemetry_queue.put_nowait(item)
+            item = _TelemetryItem(event, bandwidth_reservation)
+            with self._agent_lock:
+                if (
+                    getattr(self, "is_shutdown", False)
+                    or getattr(self.engine, "is_suspended", False)
+                    or generation != getattr(self.engine, "_generation", None)
+                    or self.active_probes.get(probe_id) is not probe
+                ):
+                    bandwidth_reservation.release()
+                    self._release_hit_slot(probe_id)
+                    return
+                self.telemetry_queue.put_nowait(item)
         except queue.Full:
             bandwidth_reservation.release()
             self._release_hit_slot(probe_id)
             return
-        except Exception as exc:
+        except BaseException as exc:
             bandwidth_reservation.release()
             self._release_hit_slot(probe_id)
             logger.error(

{hyperprobe_agent-1.2.30b4 → hyperprobe_agent-1.2.31}/hyperprobe/core/broker.py

@@ -1,6 +1,4 @@
 import os
-import sys
-import time
 
 try:
     # Shaded/vendored fallback
@@ -11,9 +9,6 @@ except ImportError:
 # Import our generated protos
 from hyperprobe.protos import agent_pb2
 from hyperprobe.protos import agent_pb2_grpc
-from hyperprobe.core.logger import get_logger
-
-logger = get_logger("hyperprobe:broker")
 
 
 class BrokerTransportError(RuntimeError):
@@ -37,7 +32,10 @@ class BrokerClient:
         self.agent_id = agent_id
         if agent_version is None:
             try:
-                from importlib.metadata import version
+                try:
+                    from importlib.metadata import version
+                except ImportError:
+                    from importlib_metadata import version
                 agent_version = version("hyperprobe-agent")
             except Exception:
                 agent_version = "unknown"

hyperprobe_agent-1.2.31/hyperprobe/core/bytecode/__init__.py

@@ -0,0 +1 @@
+"""CPython 3.7–3.11 instrumentation; imported only by the startup selector."""