qualcomm/observatory: AdbLens groups records under top-level "device" region

Adds the third top-level Region in the typical AOT+device flow:

    Session "<script-name>"
    ├── quantization/   (pipeline_graph_collector, AOT)
    ├── edge/           (pipeline_graph_collector, AOT)
    └── device/         (this lens; on-device runtime work)
          ├── adb.execute #1
          ├── adb.execute #2
          └── ...

Region opens lazily on the first patched SimpleADB operation
(via `_ensure_device_region`, called from `note_simple_adb`), so a
CLI run with no on-device inference doesn't get an empty group
cluttering the tree view. The region is closed in `on_session_end`
via a `contextlib.ExitStack`.

Each inference record (`adb.execute #N`) lives **directly** under
`device` — no per-call sub-region — so the region holds multiple
records as designed in RFC §4.5.

Disabled lens (`config={"adb": {"enabled": False}}`) skips region
opening entirely.

tests/test_adb_lens_regions.py (new):
- 6 tests covering: lazy device-region opening, first SimpleADB
  call triggers it, multiple records share the one region,
  disabled-lens does not open it, on_session_end closes the
  ExitStack, idempotent _ensure_device_region.

Verification:
  source ~/executorch/.venv-11/bin/activate
  source ~/executorch/qaisw-*/bin/envsetup.sh
  export QNN_SDK_ROOT=~/executorch/qaisw-v2.41.0.251111144900_191416
  PYTHONPATH=~ python -m pytest \
    ~/executorch/backends/qualcomm/debugger/observatory/tests/ -v
  -> 19 passed (6 new + 13 existing AdbLens tests).

Co-Authored-By: Claude Sonnet 4.6 (1M context) <noreply@anthropic.com>

Author: quic-boyuc

backends/qualcomm/debugger/observatory/lenses/adb.py

@@ -28,6 +28,7 @@
 import logging
 import re
 import threading
+import contextlib
 from dataclasses import dataclass, field
 from typing import Any, Callable, Dict, List, Optional
 
@@ -117,14 +118,34 @@ def _scan_error_lines(text: str) -> List[int]:
 
 
 class AdbLens(Lens):
-    """Lens that records ``SimpleADB`` activity for the run."""
+    """Lens that records ``SimpleADB`` activity for the run.
+
+    Region structure (cf. RFC §4.5):
+
+        Session "<script-name>"
+        ├── quantization/             (pipeline_graph_collector, AOT)
+        ├── edge/                     (pipeline_graph_collector, AOT)
+        └── device/                   (this lens; on-device runtime work)
+              ├── adb.execute #1
+              ├── adb.execute #2
+              └── ...
+
+    The ``device`` region is opened lazily on the first patched
+    ``SimpleADB`` operation (push / pull / execute) via
+    ``_ensure_device_region`` and closed in ``on_session_end``. Each
+    inference record (``adb.execute #N``) lives directly under
+    ``device`` rather than getting its own per-call region — every
+    region holds more than one Record by design.
+    """
 
     _lock = threading.Lock()
 
     _enabled: bool = True
     _config: Dict[str, Any] = {}
     _patches_installed: bool = False
     _install_patches: Optional[Callable[[], None]] = None
+    _enter_context_fn: Optional[Callable[..., Any]] = None
+    _device_stack: Optional["contextlib.ExitStack"] = None
 
     _raw_events: List[Dict[str, Any]] = []
     _device_info: List[Dict[str, Any]] = []
@@ -175,6 +196,13 @@ def on_session_start(cls, context: ObservationContext) -> Optional[Dict[str, Any
         if not cls._enabled:
             return {"enabled": False}
 
+        # Capture the framework's enter_context callable so the lens can
+        # lazily open a top-level "device" region on the first patched
+        # SimpleADB operation. The region is closed in on_session_end.
+        from executorch.devtools.observatory import Observatory
+
+        cls._enter_context_fn = Observatory.enter_context
+
         if cls._install_patches is not None and not cls._patches_installed:
             cls._install_patches()
             cls._patches_installed = True
@@ -201,6 +229,33 @@ def on_session_end(cls, context: ObservationContext) -> Optional[Dict[str, Any]]
             if is_installed():
                 uninstall_adb_patches()
             cls._patches_installed = False
+            # Close the lazy "device" region (if any) before the framework
+            # tears down the outer Session. Idempotent: no-op when never
+            # opened (e.g., a CLI run with no on-device inference).
+            if cls._device_stack is not None:
+                try:
+                    cls._device_stack.close()
+                except Exception as exc:
+                    logging.warning(
+                        "[AdbLens] failed to close device region: %s", exc
+                    )
+                cls._device_stack = None
+            cls._enter_context_fn = None
+
+    @classmethod
+    def _ensure_device_region(cls) -> None:
+        """Lazy-open the top-level ``device`` Region on first ADB activity.
+
+        Idempotent: subsequent calls are no-ops once the region is open.
+        Called from ``note_simple_adb`` so every patched SimpleADB
+        operation (push / pull / execute) lands inside the region.
+        """
+
+        if not cls._enabled or cls._enter_context_fn is None:
+            return
+        if cls._device_stack is None:
+            cls._device_stack = contextlib.ExitStack()
+            cls._device_stack.enter_context(cls._enter_context_fn("device"))
 
     @classmethod
     def observe(cls, artifact: Any, context: ObservationContext) -> Any:
@@ -475,6 +530,9 @@ def _publish_active_inference(cls) -> None:
     def note_simple_adb(cls, instance: Any) -> None:
         if not cls._enabled:
             return
+        # Open the lazy "device" Region on the first patched ADB call,
+        # so every record produced from now on is grouped under it.
+        cls._ensure_device_region()
         info = _summarize_simple_adb(instance)
         key = (info.get("host"), info.get("device_serial"))
         with cls._lock:

backends/qualcomm/debugger/observatory/tests/test_adb_lens_regions.py

@@ -0,0 +1,142 @@
+# Copyright (c) Qualcomm Innovation Center, Inc.
+# All rights reserved
+#
+# This source code is licensed under the BSD-style license found in the
+# LICENSE file in the root directory of this source tree.
+
+"""Unit tests for the AdbLens region structure (RFC §4.5).
+
+The Qualcomm ADB lens contributes a top-level ``device`` Region opened
+lazily on the first patched SimpleADB operation. All ``adb.execute #N``
+inference records (and any other ADB-related collects) live directly
+under it.
+
+These tests don't run an actual on-device inference. They invoke the
+public AdbLens entry points (``note_simple_adb``, ``begin_inference``,
+``record_event``, ``end_inference``) directly to exercise the region
+state machine.
+"""
+
+from __future__ import annotations
+
+import pytest
+
+from executorch.backends.qualcomm.debugger.observatory.lenses.adb import (
+    AdbLens,
+    AdbExecuteEvent,
+)
+from executorch.devtools.observatory import Observatory
+
+
+class _DummyAdb:
+    """Minimal stand-in for SimpleADB used by AdbLens.note_simple_adb."""
+
+    host_id = "test-host"
+    device_id = "test-device"
+
+
+@pytest.fixture(autouse=True)
+def _reset_observatory():
+    Observatory.clear()
+    Observatory._lens_registry = []
+    Observatory._lenses_initialized = True
+    Observatory.register_lens(AdbLens)
+    yield
+    # AdbLens has class-level state; reset it so tests are independent.
+    AdbLens._device_info = []
+    AdbLens._device_info_seen = set()
+    AdbLens._raw_events = []
+    AdbLens._push_groups = []
+    AdbLens._pull_groups = []
+    AdbLens._open_groups = []
+    AdbLens._execute_seq = 0
+    AdbLens._active_inference = None
+    AdbLens._device_stack = None
+    AdbLens._enter_context_fn = None
+    Observatory.clear()
+    Observatory._lens_registry = []
+    Observatory._lenses_initialized = False
+
+
+def test_no_device_region_until_first_adb_call():
+    """The 'device' region is lazy — nothing happens until ADB activity."""
+
+    with Observatory.enter_context("session_no_adb"):
+        # No SimpleADB call yet — collect a record from a hypothetical
+        # other lens. Its region_stack should not include "device".
+        Observatory.collect("non_adb_record", object())
+
+    rec = list(Observatory._records.values())[0]
+    assert "device" not in rec.region_stack
+    assert AdbLens._device_stack is None
+
+
+def test_first_simple_adb_call_opens_device_region():
+    """note_simple_adb fires _ensure_device_region the first time."""
+
+    with Observatory.enter_context("session_with_adb"):
+        AdbLens.note_simple_adb(_DummyAdb())
+        # Now the device region is open; subsequent collects pick it up.
+        Observatory.collect("inside_device", object())
+
+    rec = list(Observatory._records.values())[0]
+    assert rec.region_stack == ["session_with_adb", "device"]
+
+
+def test_multiple_inference_events_share_one_device_region():
+    """Several adb.execute records should land directly under 'device' (no
+    per-call sub-region — every region holds >=2 records)."""
+
+    with Observatory.enter_context("session_multi_exec"):
+        AdbLens.note_simple_adb(_DummyAdb())
+        # Collect two records from inside the lazy device region. We
+        # bypass the full inference event flow here because that path
+        # has many internal dependencies (event publishing, active
+        # inference accumulator) that aren't worth wiring up for a
+        # region-structure test.
+        Observatory.collect("adb.execute #1", object())
+        Observatory.collect("adb.execute #2", object())
+
+    by_region: dict = {}
+    for rec in Observatory._records.values():
+        by_region.setdefault(tuple(rec.region_stack), []).append(rec.name)
+
+    assert ("session_multi_exec", "device") in by_region
+    assert len(by_region[("session_multi_exec", "device")]) == 2
+
+
+def test_disabled_adb_lens_does_not_open_region():
+    """When AdbLens is disabled via config, no device region is opened."""
+
+    with Observatory.enter_context(
+        "session_adb_disabled", config={"adb": {"enabled": False}}
+    ):
+        AdbLens.note_simple_adb(_DummyAdb())
+        Observatory.collect("non_adb", object())
+
+    rec = list(Observatory._records.values())[0]
+    assert "device" not in rec.region_stack
+    assert AdbLens._device_stack is None
+
+
+def test_device_region_closes_on_session_end():
+    """on_session_end closes the lazy device ExitStack cleanly."""
+
+    with Observatory.enter_context("session_close"):
+        AdbLens.note_simple_adb(_DummyAdb())
+        assert AdbLens._device_stack is not None
+
+    assert AdbLens._device_stack is None
+
+
+def test_ensure_device_region_idempotent():
+    """Multiple ADB calls do not re-open the region."""
+
+    with Observatory.enter_context("session_idempotent"):
+        AdbLens.note_simple_adb(_DummyAdb())
+        first = AdbLens._device_stack
+        AdbLens.note_simple_adb(_DummyAdb())
+        second = AdbLens._device_stack
+
+    # Both reference the same ExitStack (was open already by second call).
+    assert first is second