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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: hyperprobe-agent
-Version: 1.2.25b9
+Version: 1.2.26b2
 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:
@@ -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.26b2}/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:
@@ -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`.

{hyperprobe_agent-1.2.25b9 → hyperprobe_agent-1.2.26b2}/hyperprobe/agent.py

@@ -14,6 +14,7 @@ from hyperprobe.core.logger import get_logger
 from hyperprobe.core.probe_output import ProbeLogWriter
 
 logger = get_logger("hyperprobe:agent")
+broker_logger = get_logger("hyperprobe:broker")
 from hyperprobe.protos.agent_pb2 import PROBE_TYPE_UNSPECIFIED,PROBE_TYPE_SNAPSHOT,PROBE_TYPE_LOG,PROBE_TYPE_COUNTER,PROBE_TYPE_METRIC,PROBE_TYPE_DURATION
 
 UUID_REGEX = re.compile(r"^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", re.IGNORECASE)
@@ -45,13 +46,26 @@ def is_valid_broker_url(url):
 class HyperProbeAgent:
     _instance = None
     _lock = threading.Lock()
+    _fork_handlers_registered = False
+    _fork_owner_pid = None
+    _fork_options = None
+    _fork_agent = None
+    _fork_pending = False
 
     def __init__(self, options):
-        self.options = options
+        self.options = dict(options)
+        self.owner_pid = os.getpid()
         self.agent_id = str(uuid.uuid4())
         self.is_shutdown = False
         self.stop_event = threading.Event()
 
+        self.fork_mode = str(
+            self.options.get("fork_mode")
+            or os.getenv("HYPERPROBE_FORK_MODE", "none")
+        ).strip().lower()
+        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
@@ -118,8 +132,21 @@ class HyperProbeAgent:
     @classmethod
     def start(cls, options):
         """Starts the global HyperProbe Agent singleton."""
+        options = dict(options or {})
         with cls._lock:
+            if (
+                cls._fork_owner_pid == os.getpid()
+                and cls._fork_agent is not None
+            ):
+                logger.forceInfo("[HyperProbe] Worker fork mode is already configured.")
+                return cls._fork_agent
             if cls._instance is not None:
+                if cls._instance.owner_pid != os.getpid():
+                    logger.forceError(
+                        "[HyperProbe] Inherited agent state detected in a forked "
+                        "process. Configure fork_mode='worker' before forking."
+                    )
+                    return None
                 logger.forceInfo("[HyperProbe] Agent is already running.")
                 return cls._instance
 
@@ -134,12 +161,15 @@ class HyperProbeAgent:
                 return None
             options["commit_sha"] = commit_sha
 
-            service_id = options.get("service_id")
+            service_id = options.get("service_id") or os.getenv(
+                "HYPERPROBE_SERVICE_ID"
+            )
             if not service_id or not str(service_id).strip():
                 logger.forceError('\033[1m\033[33m⚠️  [HyperProbe] CRITICAL: Failed to start agent. HYPERPROBE_SERVICE_ID is required.\033[0m')
                 return None
             if not UUID_REGEX.match(str(service_id).strip()):
                 logger.forceInfo('\033[1m\033[33m⚠️  [HyperProbe] WARN: service_id is not a valid UUID, please check again.\033[0m')
+            options["service_id"] = service_id
 
             environment = options.get("environment") or os.getenv("HYPERPROBE_ENVIRONMENT")
             if not environment or not str(environment).strip():
@@ -147,26 +177,164 @@ class HyperProbeAgent:
                 return None
             options["environment"] = environment
 
-            broker_url = options.get("broker_url")
+            broker_url = options.get("broker_url") or os.getenv(
+                "HYPERPROBE_BROKER_URL"
+            )
             if not is_valid_broker_url(broker_url):
                 logger.forceError(f'\033[1m\033[33m⚠️  [HyperProbe] CRITICAL: Failed to start agent. Invalid broker_url "{broker_url}". It must be a valid URL (http:// or https://) or a raw gRPC target (e.g. localhost:60051), with no query parameters and no trailing slash.\033[0m')
                 return None
+            options["broker_url"] = broker_url
+
+            fork_mode = str(
+                options.get("fork_mode")
+                or os.getenv("HYPERPROBE_FORK_MODE", "none")
+            ).strip().lower()
+            if fork_mode not in {"none", "worker"}:
+                logger.forceError(
+                    '[HyperProbe] Invalid fork_mode. Expected "none" or "worker".'
+                )
+                return None
+            options["fork_mode"] = fork_mode
+
+            if fork_mode == "worker":
+                return cls._prepare_worker_fork_mode_locked(options)
 
-            cls._instance = cls(options)
-            cls._instance._start_background_loops()
-            logger.forceInfo(f"[HyperProbe] Python agent successfully started (ID: {cls._instance.agent_id}).")
+            instance = cls.__new__(cls)
+            try:
+                instance.__init__(options)
+                cls._instance = instance
+                instance._start_background_loops()
+            except Exception as exc:
+                instance._cleanup_failed_start()
+                cls._instance = None
+                logger.forceError(
+                    f"[HyperProbe] Agent failed to initialize "
+                    f"({type(exc).__name__}: {exc}). "
+                    "Running application uninstrumented."
+                )
+                return None
+            logger.forceInfo(
+                f"[HyperProbe] Python agent successfully started "
+                f"(ID: {cls._instance.agent_id}, PID: {cls._instance.owner_pid})."
+            )
             return cls._instance
 
+    @classmethod
+    def _prepare_worker_fork_mode_locked(cls, options):
+        if not hasattr(os, "register_at_fork"):
+            logger.forceError(
+                "[HyperProbe] fork_mode='worker' is not supported on this platform."
+            )
+            return None
+
+        # Return a stable placeholder to application code imported by the
+        # prefork parent. It is initialized in place after each child fork.
+        instance = cls.__new__(cls)
+        instance.options = dict(options)
+        instance.owner_pid = os.getpid()
+        instance.agent_id = None
+        instance.is_shutdown = True
+        instance.fork_mode = "worker"
+
+        cls._fork_owner_pid = os.getpid()
+        cls._fork_options = dict(options)
+        cls._fork_agent = instance
+
+        if cls._fork_handlers_registered:
+            logger.forceInfo(
+                f"[HyperProbe] Worker fork mode configured (PID: {os.getpid()})."
+            )
+            return instance
+
+        os.register_at_fork(
+            before=cls._before_fork,
+            after_in_parent=cls._after_fork_parent,
+            after_in_child=cls._after_fork_child,
+        )
+        cls._fork_handlers_registered = True
+        logger.forceInfo(
+            f"[HyperProbe] Worker fork mode configured (PID: {os.getpid()})."
+        )
+        return instance
+
+    @classmethod
+    def _before_fork(cls):
+        if cls._fork_owner_pid != os.getpid() or cls._fork_options is None:
+            return
+
+        cls._lock.acquire()
+        cls._fork_pending = True
+
+    @classmethod
+    def _after_fork_parent(cls):
+        if not cls._fork_pending:
+            return
+        cls._fork_pending = False
+        cls._lock.release()
+
+    @classmethod
+    def _after_fork_child(cls):
+        if not cls._fork_pending:
+            return
+
+        options = dict(cls._fork_options or {})
+        instance = cls._fork_agent
+
+        # Locks and process resources inherited from a multithreaded parent must
+        # never be reused in the child.
+        cls._lock = threading.Lock()
+        cls._instance = None
+        cls._fork_pending = False
+        cls._fork_owner_pid = None
+        cls._fork_options = None
+        cls._fork_agent = None
+
+        if instance is None or not options:
+            return
+
+        try:
+            # Reinitialize in place so the object returned by HyperProbe.start()
+            # remains valid in application modules imported before the fork.
+            instance.__init__(options)
+            cls._instance = instance
+            instance._start_background_loops()
+        except Exception as exc:
+            instance._cleanup_failed_start()
+            cls._instance = None
+            logger.forceError(
+                f"[HyperProbe] Failed to restart the agent after fork: {exc}"
+            )
+            return
+
+        logger.forceInfo(
+            f"[HyperProbe] Python agent started after fork "
+            f"(ID: {instance.agent_id}, PID: {instance.owner_pid})."
+        )
+
     @classmethod
     def shutdown(cls):
         """Cleanly and safely shuts down the running agent singleton."""
         with cls._lock:
             if cls._instance is None:
+                if cls._fork_owner_pid == os.getpid():
+                    cls._clear_fork_state_locked()
+                return
+            if cls._instance.owner_pid != os.getpid():
+                cls._instance = None
                 return
             cls._instance._stop()
             cls._instance = None
+            if cls._fork_owner_pid == os.getpid():
+                cls._clear_fork_state_locked()
             print("[HyperProbe] Python agent successfully shut down.")
 
+    @classmethod
+    def _clear_fork_state_locked(cls):
+        cls._fork_owner_pid = None
+        cls._fork_options = None
+        cls._fork_agent = None
+        cls._fork_pending = False
+
     def _init_instrumentation_engine(self):
         from hyperprobe.core.monitoring_engine import MonitoringEngine
         return MonitoringEngine(
@@ -177,6 +345,8 @@ class HyperProbeAgent:
         )
 
     def _start_background_loops(self):
+        if self.owner_pid != os.getpid():
+            return
         self.stop_event.clear()
         self.safety_monitor.start()
 
@@ -195,29 +365,107 @@ class HyperProbeAgent:
     def _stop(self):
         self.is_shutdown = True
         self.stop_event.set()
-        self.safety_monitor.stop()
 
-        # Stop tracing immediately
-        self.engine.set_probes([])
-        self.engine.close()
-        self.probe_log_writer.stop(timeout=2.0)
+        try:
+            self.safety_monitor.stop()
+        except Exception as exc:
+            logger.error(f"[HyperProbe] Failed to stop safety monitor: {exc}")
 
-        with self._agent_lock:
-            self._cooldown_generation += 1
-            cooldown_timer = self.cooldown_timer
-            self.cooldown_timer = None
+        try:
+            self.engine.set_probes([])
+        except Exception as exc:
+            logger.error(f"[HyperProbe] Failed to clear monitoring probes: {exc}")
+        try:
+            self.engine.close()
+        except Exception as exc:
+            logger.error(f"[HyperProbe] Failed to stop monitoring engine: {exc}")
+
+        try:
+            self.probe_log_writer.stop(timeout=2.0)
+        except Exception as exc:
+            logger.error(f"[HyperProbe] Failed to stop probe output: {exc}")
+
+        cooldown_timer = None
+        try:
+            with self._agent_lock:
+                self._cooldown_generation += 1
+                cooldown_timer = self.cooldown_timer
+                self.cooldown_timer = None
+        except Exception as exc:
+            logger.error(f"[HyperProbe] Failed to clear cooldown state: {exc}")
         if cooldown_timer:
-            cooldown_timer.cancel()
+            try:
+                cooldown_timer.cancel()
+            except Exception:
+                pass
 
-        self.broker_client.shutdown()
+        try:
+            self.broker_client.shutdown()
+        except Exception as exc:
+            logger.error(f"[HyperProbe] Failed to close broker client: {exc}")
 
         current_thread = threading.current_thread()
         for thread in (self.sync_thread, self.flush_thread, self.stats_thread):
-            if thread and thread is not current_thread:
-                thread.join(timeout=2.0)
+            try:
+                if thread and thread is not current_thread and thread.is_alive():
+                    thread.join(timeout=2.0)
+            except Exception as exc:
+                logger.error(f"[HyperProbe] Failed to join worker thread: {exc}")
+
+    def _cleanup_failed_start(self):
+        """Best-effort cleanup for a partially initialized child agent."""
+        self.is_shutdown = True
+
+        stop_event = getattr(self, "stop_event", None)
+        if stop_event is not None:
+            stop_event.set()
+
+        for component_name in ("safety_monitor", "probe_log_writer"):
+            component = getattr(self, component_name, None)
+            if component is None:
+                continue
+            try:
+                component.stop()
+            except Exception:
+                pass
+
+        engine = getattr(self, "engine", None)
+        if engine is not None:
+            try:
+                engine.close()
+            except Exception:
+                pass
+
+        broker_client = getattr(self, "broker_client", None)
+        if broker_client is not None:
+            try:
+                broker_client.shutdown()
+            except Exception:
+                pass
+
+        cooldown_timer = getattr(self, "cooldown_timer", None)
+        if cooldown_timer is not None:
+            try:
+                cooldown_timer.cancel()
+            except Exception:
+                pass
+            self.cooldown_timer = None
+        if hasattr(self, "_cooldown_generation"):
+            self._cooldown_generation += 1
+
+        current_thread = threading.current_thread()
+        for thread_name in ("sync_thread", "flush_thread", "stats_thread"):
+            thread = getattr(self, thread_name, None)
+            if thread is None or thread is current_thread:
+                continue
+            try:
+                if thread.is_alive():
+                    thread.join(timeout=2.0)
+            except Exception:
+                pass
 
     def _sync_loop(self):
-        while not self.stop_event.is_set():
+        while self.owner_pid == os.getpid() and not self.stop_event.is_set():
             try:
                 self._sync_with_broker()
             except Exception as e:
@@ -277,7 +525,7 @@ class HyperProbeAgent:
         self.engine.set_probes(to_apply)
 
     def _flush_loop(self):
-        while not self.stop_event.is_set():
+        while self.owner_pid == os.getpid() and not self.stop_event.is_set():
             try:
                 self._flush_telemetry()
             except Exception as e:
@@ -285,7 +533,7 @@ class HyperProbeAgent:
             self.stop_event.wait(self.flush_interval_sec)
 
     def _stats_loop(self):
-        while not self.stop_event.is_set():
+        while self.owner_pid == os.getpid() and not self.stop_event.is_set():
             try:
                 stats = self.engine.get_stats()
                 if stats["hits"] > 0 or stats["skips"] > 0:
@@ -313,12 +561,18 @@ class HyperProbeAgent:
             return
 
         self._inflight_batch = batch
+        broker_logger.info(
+            f"[HyperProbe] Flushing {len(batch)} telemetry events to broker..."
+        )
         try:
             finished_probe_ids = self.broker_client.report_telemetry(
                 [item.event for item in batch]
             )
+            broker_logger.info(
+                f"[HyperProbe] Successfully flushed {len(batch)} telemetry events to broker."
+            )
         except Exception as e:
-            logger.error(
+            broker_logger.error(
                 f"[HyperProbe] Failed to flush telemetry: {str(e)}. "
                 f"Retaining {len(batch)} events for retry."
             )
@@ -378,6 +632,11 @@ class HyperProbeAgent:
             return list(self.active_probes.values())
 
     def _handle_capture(self, event):
+        if (
+            getattr(self, "owner_pid", os.getpid()) != os.getpid()
+            or getattr(self, "is_shutdown", False)
+        ):
+            return
         probe_id = event["probe_id"]
         with self._agent_lock:
             probe = self.active_probes.get(probe_id)
@@ -449,7 +708,7 @@ class HyperProbeAgent:
             self.engine.set_probes(probes_list)
 
     def _handle_health_change(self, health, reason):
-        if self.is_shutdown:
+        if self.owner_pid != os.getpid() or self.is_shutdown:
             return
 
         if health == AgentHealth.RED: