hyperprobe-agent 1.12.19__py3-none-any.whl

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}'")

hyperprobe/agent.py

@@ -0,0 +1,476 @@
+import sys
+import os
+import uuid
+import time
+import threading
+import queue
+import re
+from urllib.parse import urlparse
+
+from hyperprobe.core.quota import QuotaManager
+from hyperprobe.core.safety import SafetyMonitor, AgentHealth
+from hyperprobe.core.broker import BrokerClient
+from hyperprobe.core.logger import get_logger
+
+logger = get_logger("hyperprobe:agent")
+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)
+
+SUPPORTED_PROBE_TYPES = {PROBE_TYPE_UNSPECIFIED,PROBE_TYPE_SNAPSHOT,PROBE_TYPE_LOG,PROBE_TYPE_COUNTER,PROBE_TYPE_METRIC,PROBE_TYPE_DURATION}
+
+
+class _TelemetryItem:
+    def __init__(self, event, bandwidth_reservation=None):
+        self.event = event
+        self.bandwidth_reservation = bandwidth_reservation
+
+
+def is_valid_broker_url(url):
+    if not url or not str(url).strip():
+        return False
+    url = str(url).strip()
+    
+    if url.startswith("http://") or url.startswith("https://"):
+        try:
+            parsed = urlparse(url)
+            return not url.endswith("/") and not parsed.query and bool(parsed.hostname)
+        except Exception:
+            return False
+            
+    # Raw gRPC targets should have no schema, no path, and no query parameters
+    return "://" not in url and "/" not in url and "?" not in url
+
+class HyperProbeAgent:
+    _instance = None
+    _lock = threading.Lock()
+
+    def __init__(self, options):
+        self.options = options
+        self.agent_id = str(uuid.uuid4())
+        self.is_shutdown = False
+        self.stop_event = threading.Event()
+
+        # 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))
+
+        self.global_config = {
+            "redact_keys": options.get("redact_keys") or os.getenv("HYPERPROBE_REDACT_KEYS", "password,secret,token,authorization,cookie,key,signature").split(","),
+            "redact_values": options.get("redact_values") or os.getenv("HYPERPROBE_REDACT_VALUES", "").split(","),
+            "max_object_depth": options.get("max_object_depth") or int(os.getenv("HYPERPROBE_MAX_OBJECT_DEPTH", 3)),
+            "max_array_length": options.get("max_array_length") or int(os.getenv("HYPERPROBE_MAX_ARRAY_LENGTH", 3)),
+            "stack_frame_depth": options.get("stack_frame_depth") or int(os.getenv("HYPERPROBE_STACK_FRAME_DEPTH", 3)),
+            "max_object_properties": options.get("max_object_properties") or int(os.getenv("HYPERPROBE_MAX_OBJECT_PROPERTIES", 50)),
+            "max_string_length": options.get("max_string_length") or int(os.getenv("HYPERPROBE_MAX_STRING_LENGTH", 1024))
+        }
+
+        # Strip empty redaction strings
+        self.global_config["redact_keys"] = [k.strip() for k in self.global_config["redact_keys"] if k.strip()]
+        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.safety_monitor = SafetyMonitor(
+            self._handle_health_change,
+            max_lag_ms=max_lag_ms,
+            pause_budget_ms=pause_budget_ms,
+        )
+
+        self.broker_client = BrokerClient(
+            broker_url=options["broker_url"],
+            service_id=options["service_id"],
+            environment=options["environment"],
+            commit_sha=options.get("commit_sha") or os.getenv("GIT_COMMIT", "unknown"),
+            agent_id=self.agent_id,
+            rpc_timeout_sec=rpc_timeout_sec,
+        )
+
+        # Thread-safe queue for telemetry events
+        self.telemetry_queue = queue.Queue(maxsize=self.max_queue_size)
+        self.active_probes = {}  # probe_id -> Probe
+        self.local_hits = {}     # probe_id -> count
+        self.pending_hits = {}   # probe_id -> queued capture reservations
+        self.cooldown_timer = None
+        self._cooldown_generation = 0
+        self._agent_lock = threading.RLock()  # Synchronizes state access with re-entrancy safety
+        self._inflight_batch = None
+
+        # Determine and initialize dynamic instrumentation engine
+        self.engine = self._init_instrumentation_engine()
+        self.engine.set_global_config(self.global_config)
+
+        # Background worker threads
+        self.sync_thread = None
+        self.flush_thread = None
+        self.stats_thread = None
+
+    @classmethod
+    def start(cls, options):
+        """Starts the global HyperProbe Agent singleton."""
+        with cls._lock:
+            if cls._instance is not None:
+                logger.forceInfo("[HyperProbe] Agent is already running.")
+                return cls._instance
+
+            # Check kill switch
+            if os.getenv("HYPERPROBE_DISABLED", "").strip().upper() == "YES":
+                logger.forceInfo("[HyperProbe] Explicitly disabled via HYPERPROBE_DISABLED.")
+                return None
+
+            commit_sha = options.get("commit_sha") or os.getenv("HYPERPROBE_COMMIT_SHA") or os.getenv("GIT_COMMIT")
+            if not commit_sha or not str(commit_sha).strip() or str(commit_sha).strip().lower() == "unknown":
+                logger.forceError('\033[1m\033[33m⚠️  [HyperProbe] CRITICAL: Failed to start agent. A valid "commit_sha" is required via options or the GIT_COMMIT environment variable to ensure accurate source map resolution and prevent cross-deployment collisions.\033[0m')
+                return None
+            options["commit_sha"] = commit_sha
+
+            service_id = options.get("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')
+
+            environment = options.get("environment") or os.getenv("HYPERPROBE_ENVIRONMENT")
+            if not environment or not str(environment).strip():
+                logger.forceError('\033[1m\033[33m⚠️  [HyperProbe] CRITICAL: Failed to start agent. HYPERPROBE_ENVIRONMENT is required.\033[0m')
+                return None
+            options["environment"] = environment
+
+            broker_url = options.get("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
+
+            cls._instance = cls(options)
+            cls._instance._start_background_loops()
+            logger.forceInfo(f"[HyperProbe] Python agent successfully started (ID: {cls._instance.agent_id}).")
+            return cls._instance
+
+    @classmethod
+    def shutdown(cls):
+        """Cleanly and safely shuts down the running agent singleton."""
+        with cls._lock:
+            if cls._instance is None:
+                return
+            cls._instance._stop()
+            cls._instance = None
+            print("[HyperProbe] Python agent successfully shut down.")
+
+    def _init_instrumentation_engine(self):
+        from hyperprobe.core.monitoring_engine import MonitoringEngine
+        return MonitoringEngine(
+            self.quota_manager,
+            self.safety_monitor,
+            self._handle_capture,
+            custom_set_trace_id=self.options.get("set_trace_id")
+        )
+
+    def _start_background_loops(self):
+        self.stop_event.clear()
+        self.safety_monitor.start()
+
+        self.sync_thread = threading.Thread(target=self._sync_loop, name="hyperprobe-sync")
+        self.sync_thread.daemon = True
+        self.sync_thread.start()
+
+        self.flush_thread = threading.Thread(target=self._flush_loop, name="hyperprobe-flush")
+        self.flush_thread.daemon = True
+        self.flush_thread.start()
+
+        self.stats_thread = threading.Thread(target=self._stats_loop, name="hyperprobe-stats")
+        self.stats_thread.daemon = True
+        self.stats_thread.start()
+
+    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()
+
+        with self._agent_lock:
+            self._cooldown_generation += 1
+            cooldown_timer = self.cooldown_timer
+            self.cooldown_timer = None
+        if cooldown_timer:
+            cooldown_timer.cancel()
+
+        self.broker_client.shutdown()
+
+        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)
+
+    def _sync_loop(self):
+        while not self.stop_event.is_set():
+            try:
+                self._sync_with_broker()
+            except Exception as e:
+                logger.error(f"[HyperProbe] Sync loop encountered error: {str(e)}")
+            self.stop_event.wait(self.sync_interval_sec)
+
+    def _sync_with_broker(self):
+        response = self.broker_client.get_probes()
+        if not response:
+            return
+
+        # Update global config if returned
+        if response.HasField("global_config"):
+            gc = response.global_config
+            with self._agent_lock:
+                self.global_config.update({
+                    "redact_keys": list(gc.redact_keys) if gc.redact_keys else self.global_config["redact_keys"],
+                    "redact_values": list(gc.redact_values) if gc.redact_values else self.global_config["redact_values"],
+                    "max_object_depth": gc.max_object_depth if gc.HasField("max_object_depth") else self.global_config["max_object_depth"],
+                    "max_array_length": gc.max_array_length if gc.HasField("max_array_length") else self.global_config["max_array_length"],
+                    "stack_frame_depth": gc.stack_frame_depth if gc.HasField("stack_frame_depth") else self.global_config["stack_frame_depth"],
+                    "max_object_properties": gc.max_object_properties if gc.HasField("max_object_properties") else self.global_config["max_object_properties"],
+                    "max_string_length": gc.max_string_length if gc.HasField("max_string_length") else self.global_config["max_string_length"],
+                })
+            self.engine.set_global_config(self.global_config)
+
+        # Only activate probe types implemented by this SDK.
+        server_probes = {}
+        for probe in response.probes:
+            if probe.type in SUPPORTED_PROBE_TYPES:
+                server_probes[probe.id] = probe
+            else:
+                msg = f"[HyperProbe] Ignoring unsupported probe type {probe.type} for probe {probe.id}."
+                logger.error(msg)
+
+        now_ms = int(time.time() * 1000)
+
+        with self._agent_lock:
+            # Cleanup stale state
+            self.active_probes = {pid: p for pid, p in self.active_probes.items() if pid in server_probes}
+            self.local_hits = {pid: count for pid, count in self.local_hits.items() if pid in server_probes}
+            self.pending_hits = {pid: count for pid, count in self.pending_hits.items() if pid in server_probes}
+
+            to_apply = []
+            for pid, p in server_probes.items():
+                hits = self.local_hits.get(pid, 0)
+                is_expired = p.expiry_time <= now_ms if p.expiry_time else False
+
+                if hits < p.hit_limit and not is_expired:
+                    to_apply.append(p)
+                    self.active_probes[pid] = p
+                else:
+                    self.active_probes.pop(pid, None)
+
+        # set_probes updates the configured probes; the engine decides whether
+        # instrumentation may run while suspended.
+        self.engine.set_probes(to_apply)
+
+    def _flush_loop(self):
+        while not self.stop_event.is_set():
+            try:
+                self._flush_telemetry()
+            except Exception as e:
+                logger.error(f"[HyperProbe] Flush loop encountered error: {str(e)}")
+            self.stop_event.wait(self.flush_interval_sec)
+
+    def _stats_loop(self):
+        while not self.stop_event.is_set():
+            try:
+                stats = self.engine.get_stats()
+                if stats["hits"] > 0 or stats["skips"] > 0:
+                    logger.info(f"[HyperProbe] Probes Hit: {stats['hits']}, Probes Skipped: {stats['skips']}")
+            except Exception as e:
+                logger.error(f"[HyperProbe] Stats loop encountered error: {str(e)}")
+            self.stop_event.wait(5.0)
+
+    def _flush_telemetry(self):
+        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.
+            while not self.telemetry_queue.empty():
+                try:
+                    item = self.telemetry_queue.get_nowait()
+                    if not isinstance(item, _TelemetryItem):
+                        item = _TelemetryItem(item)
+                    batch.append(item)
+                except queue.Empty:
+                    break
+
+        if not batch:
+            return
+
+        self._inflight_batch = batch
+        try:
+            finished_probe_ids = self.broker_client.report_telemetry(
+                [item.event for item in batch]
+            )
+        except Exception as e:
+            logger.error(
+                f"[HyperProbe] Failed to flush telemetry: {str(e)}. "
+                f"Retaining {len(batch)} events for retry."
+            )
+            return
+
+        for item in batch:
+            if item.bandwidth_reservation is not None:
+                item.bandwidth_reservation.commit()
+        self._inflight_batch = None
+
+        # If broker confirmed certain probes reached global limit, clear them locally
+        if finished_probe_ids:
+            changed = False
+            with self._agent_lock:
+                for pid in finished_probe_ids:
+                    if pid in self.active_probes:
+                        self.active_probes.pop(pid, None)
+                        changed = True
+                if changed:
+                    probes_list = list(self.active_probes.values())
+            if changed:
+                self.engine.set_probes(probes_list)
+
+    def _reserve_hit_slot(self, probe_id, probe):
+        with self._agent_lock:
+            if self.active_probes.get(probe_id) is not probe:
+                return False
+            committed_hits = self.local_hits.get(probe_id, 0)
+            pending_hits = self.pending_hits.get(probe_id, 0)
+            if committed_hits + pending_hits >= probe.hit_limit:
+                return False
+            self.pending_hits[probe_id] = pending_hits + 1
+            return True
+
+    def _release_hit_slot(self, probe_id):
+        with self._agent_lock:
+            pending_hits = self.pending_hits.get(probe_id, 0)
+            if pending_hits <= 1:
+                self.pending_hits.pop(probe_id, None)
+            else:
+                self.pending_hits[probe_id] = pending_hits - 1
+
+    def _commit_hit_slot(self, probe_id, probe):
+        with self._agent_lock:
+            pending_hits = self.pending_hits.get(probe_id, 0)
+            if pending_hits <= 1:
+                self.pending_hits.pop(probe_id, None)
+            else:
+                self.pending_hits[probe_id] = pending_hits - 1
+
+            hits = self.local_hits.get(probe_id, 0) + 1
+            self.local_hits[probe_id] = hits
+            if hits < probe.hit_limit:
+                return None
+
+            self.active_probes.pop(probe_id, None)
+            return list(self.active_probes.values())
+
+    def _handle_capture(self, event):
+        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:
+                return
+
+        if not self._reserve_hit_slot(probe_id, probe):
+            return
+
+        try:
+            event_size = self.broker_client.estimate_event_size(event)
+            logger.info(f"[HyperProbe] Got event size : {event_size} Bytes")
+        except Exception as exc:
+            logger.error(
+                f"[HyperProbe] Failed to size telemetry for probe {probe_id}: {exc}"
+            )
+            self._release_hit_slot(probe_id)
+            return
+
+        bandwidth_reservation = self.quota_manager.reserve_bandwidth(event_size)
+        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)
+            self._release_hit_slot(probe_id)
+            return
+
+        # 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)
+        except queue.Full:
+            bandwidth_reservation.release()
+            self._release_hit_slot(probe_id)
+            return
+        except Exception as exc:
+            bandwidth_reservation.release()
+            self._release_hit_slot(probe_id)
+            logger.error(
+                f"[HyperProbe] Failed to queue telemetry for probe {probe_id}: {exc}"
+            )
+            return
+
+        probes_list = self._commit_hit_slot(probe_id, probe)
+        if probes_list is not None:
+            self.engine.set_probes(probes_list)
+
+    def _handle_health_change(self, health, reason):
+        if self.is_shutdown:
+            return
+
+        if health == AgentHealth.RED:
+            logger.error(f"[HyperProbe] Safety Shield Triggered (RED): {reason or ''}. Suspending tracing.")
+            with self._agent_lock:
+                self.engine.suspend()
+
+                if self.cooldown_timer is not None:
+                    self.cooldown_timer.cancel()
+
+                self._cooldown_generation += 1
+                cooldown_generation = self._cooldown_generation
+                cooldown_sec = self._cooldown_sec
+                self.cooldown_timer = threading.Timer(
+                    cooldown_sec,
+                    lambda: self._cooldown_expired(cooldown_generation),
+                )
+                self.cooldown_timer.daemon = True
+                self.cooldown_timer.start()
+
+        elif health == AgentHealth.YELLOW:
+            logger.error(f"[HyperProbe] Safety Warning (YELLOW): {reason or ''}.")
+        elif health == AgentHealth.GREEN:
+            with self._agent_lock:
+                cooldown_expired = self.cooldown_timer is None
+            if cooldown_expired:
+                self._resume_instrumentation()
+
+    def _cooldown_expired(self, cooldown_generation):
+        with self._agent_lock:
+            if cooldown_generation != self._cooldown_generation:
+                return
+            self.cooldown_timer = None
+            self._resume_instrumentation()
+
+    def _resume_instrumentation(self):
+        with self._agent_lock:
+            if (
+                self.is_shutdown
+                or self.safety_monitor.get_health() != AgentHealth.GREEN
+                or self.cooldown_timer is not None
+            ):
+                return
+            logger.info("[HyperProbe] Cooldown window expired. Resuming probes from local cache.")
+            probes_list = list(self.active_probes.values())
+            self.engine.set_probes(probes_list)
+            self.engine.resume()

hyperprobe/bootstrap.py

@@ -0,0 +1,40 @@
+import sys
+import os
+
+def main():
+    if len(sys.argv) < 2:
+        print("Usage: hyperprobe-run <python_script_or_command> [args...]")
+        sys.exit(1)
+
+    target_args = sys.argv[1:]
+    cmd = target_args[0]
+    
+    # Locate the SDK and injection directories
+    sdk_path = os.path.dirname(os.path.abspath(__file__))
+    parent_path = os.path.dirname(sdk_path)
+    injection_path = os.path.join(sdk_path, "core", "injection")
+
+    # We inject two things into PYTHONPATH:
+    # 1. The injection_path (which contains sitecustomize.py) so Python runs it natively at boot
+    # 2. The parent_path so that sitecustomize.py can successfully `import hyperprobe.agent`
+    
+    old_pythonpath = os.environ.get("PYTHONPATH", "")
+    new_paths = os.pathsep.join((injection_path, parent_path))
+
+    if old_pythonpath:
+        os.environ["PYTHONPATH"] = os.pathsep.join((new_paths, old_pythonpath))
+    else:
+        os.environ["PYTHONPATH"] = new_paths
+
+    # Standard execution replacement
+    # The current hyperprobe-run process is completely replaced by the target application.
+    # Because we manipulated PYTHONPATH, Python will natively execute our sitecustomize.py
+    # before running the user's application, resulting in perfect, zero-code-change auto-instrumentation!
+    try:
+        os.execvp(cmd, target_args)
+    except FileNotFoundError:
+        print(f"[HyperProbe] Error: Executable '{cmd}' not found in PATH.", file=sys.stderr)
+        sys.exit(1)
+
+if __name__ == "__main__":
+    main()

hyperprobe/core/__init__.py

@@ -0,0 +1 @@
+# HyperProbe Core Module

hyperprobe/core/broker.py

@@ -0,0 +1,131 @@
+import os
+import sys
+import time
+
+try:
+    # Shaded/vendored fallback
+    import _vendor.grpc as grpc
+except ImportError:
+    import grpc
+
+# 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):
+    """Raised when a broker RPC cannot be completed."""
+
+class BrokerClient:
+    def __init__(
+        self,
+        broker_url,
+        service_id,
+        environment,
+        commit_sha,
+        agent_id,
+        agent_version=None,
+        rpc_timeout_sec=10.0,
+    ):
+        self.broker_url = broker_url
+        self.service_id = service_id
+        self.environment = environment
+        self.commit_sha = commit_sha
+        self.agent_id = agent_id
+        if agent_version is None:
+            try:
+                from importlib.metadata import version
+                agent_version = version("hyperprobe-agent")
+            except Exception:
+                agent_version = "unknown"
+        self.agent_version = agent_version
+        self.rpc_timeout_sec = max(float(rpc_timeout_sec), 0.1)
+        self.metadata = (("x-hp-service-id", str(service_id)),)
+        self.hostname = os.uname().nodename if hasattr(os, 'uname') else 'unknown'
+
+        # Establish channel depending on URL protocol to support both secure (SSL) and insecure brokers
+        if broker_url.startswith("https://"):
+            clean_url = broker_url[8:]
+            self.channel = grpc.secure_channel(clean_url, grpc.ssl_channel_credentials())
+        elif broker_url.startswith("http://"):
+            clean_url = broker_url[7:]
+            self.channel = grpc.insecure_channel(clean_url)
+        else:
+            self.channel = grpc.insecure_channel(broker_url)
+            
+        self.stub = agent_pb2_grpc.AgentBrokerStub(self.channel)
+
+    def shutdown(self):
+        self.channel.close()
+
+    def get_probes(self):
+        """Fetches active probes from the HyperProbe Broker."""
+        request = agent_pb2.GetProbesRequest(
+            agent_id=self.agent_id,
+            service_id=self.service_id,
+            environment=self.environment,
+            commit_sha=self.commit_sha,
+            language="python",
+            agent_version=self.agent_version,
+            hostname=self.hostname
+        )
+        try:
+            response = self.stub.GetProbes(
+                request,
+                timeout=self.rpc_timeout_sec,
+                metadata=self.metadata,
+            )
+            return response
+        except Exception as e:
+            raise BrokerTransportError("GetProbes failed") from e
+
+    @staticmethod
+    def _to_proto_event(event):
+        stack_frames = [
+            agent_pb2.StackFrame(
+                function_name=frame["function_name"],
+                file_name=frame["file_name"],
+                line_number=frame["line_number"],
+                column_number=frame["column_number"],
+            )
+            for frame in event.get("stack_frames", [])
+        ]
+
+        proto_event = agent_pb2.TelemetryEvent(
+            probe_id=event["probe_id"],
+            timestamp_ms=event["timestamp_ms"],
+            stack_frames=stack_frames,
+            captured_vars_json=event.get("captured_vars_json", ""),
+            watch_results_json=event.get("watch_results_json", ""),
+            evaluated_log=event.get("evaluated_log", ""),
+            metric_value=event.get("metric_value", 0.0),
+            capture_error=event.get("capture_error", ""),
+        )
+        if event.get("trace_id"):
+            proto_event.trace_id = event["trace_id"]
+        return proto_event
+
+    def estimate_event_size(self, event):
+        return len(self._to_proto_event(event).SerializeToString())
+
+    def report_telemetry(self, events):
+        """Sends a batch of captured Telemetry Events to the HyperProbe Broker."""
+        batch_events = [self._to_proto_event(event) for event in events]
+
+        batch = agent_pb2.TelemetryBatch(
+            agent_id=self.agent_id,
+            events=batch_events
+        )
+        
+        try:
+            response = self.stub.ReportTelemetry(
+                batch,
+                timeout=self.rpc_timeout_sec,
+                metadata=self.metadata,
+            )
+            return response.finished_probe_ids
+        except Exception as e:
+            raise BrokerTransportError("ReportTelemetry failed") from e