observatory: reviewer-friction fixes (typo, fail-soft, export summary)

- backends/xnnpack + LENSES.md: correct '--lense_recipe' typo to
  '--lens-recipe' (4 occurrences) so the documented commands actually
  work as pasted.

- devtools/fx_viewer/exporter.py + devtools/observatory/lenses/graph.py:
  GraphLens now fails soft when 'fast-sugiyama' is missing. The
  exporter raises a specific _FastSugiyamaMissingError (subclass of
  ImportError) at the layout site; GraphLens.observe() catches it,
  logs the actionable 'pip install fast-sugiyama[all]' hint exactly
  once per process, and returns None for that record. Other lenses
  continue producing records; the run finishes with exit 0. Restores
  full graph payloads automatically once the dependency is installed.

- devtools/observatory/cli.py: end-of-run export summary via print()
  (not logging.info, which is swallowed at the default WARNING level).
  Applies to run_observatory, run_compare, and run_visualize. Lists
  output paths with byte-size and the collected record names so the
  CLI no longer ends silently after the last 'Running fast-sugiyama
  layout...' line.

Authored with Claude.

Author: Bo-Yu Cheng

backends/xnnpack/debugger/observatory/README.md

@@ -15,7 +15,7 @@ python -m executorch.backends.xnnpack.debugger.observatory \
 
 ```bash
 python -m executorch.backends.xnnpack.debugger.observatory \
-    --lense_recipe=accuracy \
+    --lens-recipe=accuracy \
     [--output-html PATH] [--output-archive PATH] \
     SCRIPT [SCRIPT_ARGS...]
 ```
@@ -39,7 +39,7 @@ uses `runpy.run_module` instead of `runpy.run_path`.
 ```bash
 python -m executorch.backends.xnnpack.debugger.observatory \
     --output-html /tmp/mv2/report.html \
-    --lense_recipe=accuracy \
+    --lens-recipe=accuracy \
     examples/xnnpack/aot_compiler.py \
     --model_name=mv2 --delegate --quantize --output_dir /tmp/mv2
 ```
@@ -49,7 +49,7 @@ python -m executorch.backends.xnnpack.debugger.observatory \
 ```bash
 python -m executorch.backends.xnnpack.debugger.observatory \
     --output-html /tmp/mv2/report.html \
-    --lense_recipe=accuracy \
+    --lens-recipe=accuracy \
     examples.xnnpack.aot_compiler \
     --model_name=mv2 --delegate --quantize --output_dir /tmp/mv2
 ```
@@ -79,7 +79,7 @@ Pass `--model_name` with any of the models defined in `examples/xnnpack/__init__
 Common flags: `--delegate` (XNNPACK delegation, on by default), `--quantize` (8-bit PTQ),
 `--output_dir` (where the `.pte` is written).
 
-## Accuracy lenses (`--lense_recipe=accuracy`)
+## Accuracy lenses (`--lens-recipe=accuracy`)
 
 Registers `AccuracyLens` and `PerLayerAccuracyLens` on top of the default
 `PipelineGraphCollectorLens`. These produce:

devtools/fx_viewer/exporter.py

@@ -26,6 +26,15 @@
 )
 
 
+class _FastSugiyamaMissingError(ImportError):
+    """Raised when the optional fast-sugiyama dependency is not installed.
+
+    Subclasses ImportError so callers can catch either this specific type
+    (to fail-soft, e.g. skip the graph payload for one record) or the
+    generic ImportError (to fail-fast at library load time).
+    """
+
+
 class FXGraphExporter:
     """Export PyTorch FX graphs to JSON/JS/HTML payloads for the viewer.
 
@@ -330,7 +339,7 @@ def _compute_layout_with_ext_lines(
         try:
             from fast_sugiyama import from_edges
         except ImportError as exc:
-            raise ImportError(
+            raise _FastSugiyamaMissingError(
                 "fx_viewer layout requires 'fast-sugiyama' (and rectangle-packer "
                 "for multi-component packing). Install with: "
                 "pip install 'fast-sugiyama[all]'  (requires Python >= 3.11)"

devtools/observatory/cli.py

@@ -42,6 +42,43 @@
 # ---------------------------------------------------------------------------
 
 
+def _format_bytes(n: int) -> str:
+    for unit in ("B", "KB", "MB", "GB"):
+        if n < 1024 or unit == "GB":
+            return f"{n:,.1f} {unit}" if unit != "B" else f"{n:,} B"
+        n = n / 1024
+    return f"{n:,.1f} GB"
+
+
+def _print_export_summary(
+    output_html: str,
+    output_archive: str,
+    output_report_json: str | None,
+    record_names: list[str],
+) -> None:
+    """Print a one-shot end-of-run summary so users can see what was written.
+
+    Uses ``print`` rather than ``logging.info`` because the default Python log
+    level is WARNING, which silently swallows info-level messages. A visible
+    summary matters here: without it, the CLI ends immediately after the last
+    "Running fast-sugiyama layout..." line, which reads like the run hung.
+    """
+    lines = ["[Observatory CLI] Session complete. Wrote:"]
+    for path in (output_html, output_archive, output_report_json):
+        if not path:
+            continue
+        try:
+            size = os.path.getsize(path)
+            size_str = _format_bytes(size)
+        except OSError:
+            size_str = "missing"
+        lines.append(f"  {path}  ({size_str})")
+    lines.append(
+        f"  {len(record_names)} record(s): {', '.join(record_names)}"
+    )
+    print("\n".join(lines))
+
+
 def make_collect_parser(prog=None):
     """Create the base argparse parser for collection mode.
 
@@ -173,10 +210,11 @@ def run_visualize(input_archive: str, output_html: str, *, setup_fn=None) -> Non
     if setup_fn is not None:
         setup_fn(Observatory)
     Observatory.generate_html_from_json(input_archive, output_html)
-    logging.info(
-        "[Observatory CLI] visualize: html=%s from archive=%s",
-        output_html,
-        input_archive,
+    _print_export_summary(
+        output_html=output_html,
+        output_archive="",  # visualize consumes an archive, does not produce one
+        output_report_json=None,
+        record_names=[f"←{os.path.basename(input_archive)}"],
     )
 
 
@@ -286,15 +324,14 @@ def run_observatory(
             Observatory.export_report_json(output_report_json, title=title)
         collected = Observatory.list_collected()
         if collected:
-            logging.info(
-                "[Observatory CLI] Reports: html=%s archive=%s (%d records: %s)",
-                output_html,
-                output_archive,
-                len(collected),
-                ", ".join(collected),
+            _print_export_summary(
+                output_html=output_html,
+                output_archive=output_archive,
+                output_report_json=output_report_json,
+                record_names=collected,
             )
         else:
-            logging.warning("[Observatory CLI] No records collected")
+            print("[Observatory CLI] No records collected — no report written.")
 
 
 # ---------------------------------------------------------------------------
@@ -341,10 +378,11 @@ def run_compare(
         # config is not threaded through compare mode (compare_archives drives
         # analysis). Pass None so export_report_json uses an empty config.
         Observatory.export_report_json(output_report_json, title=title, config=None)
-    logging.info(
-        "[Observatory CLI] compare: html=%s from %d archives",
-        output_html,
-        len(input_archives),
+    _print_export_summary(
+        output_html=output_html,
+        output_archive="",  # compare has no output archive of its own
+        output_report_json=output_report_json,
+        record_names=[f"{lbl}←{os.path.basename(pth)}" for lbl, pth in zip(labels, input_archives)],
     )
 
 

devtools/observatory/lenses/LENSES.md

@@ -392,7 +392,7 @@ evaluator = StandardEvaluator(
 
 ### Disabling Accuracy Evaluation
 
-Accuracy lenses are opt-in via `--lense_recipe=accuracy` on backend CLIs. When
+Accuracy lenses are opt-in via `--lens-recipe=accuracy` on backend CLIs. When
 omitted, no accuracy evaluation runs. To disable accuracy when using the Python
 API directly:
 

devtools/observatory/lenses/graph.py

@@ -6,18 +6,26 @@
 
 from __future__ import annotations
 
+import logging
 from typing import Any, Dict, Optional
 
 import torch
 
 from executorch.devtools.fx_viewer import FXGraphExporter
+from executorch.devtools.fx_viewer.exporter import _FastSugiyamaMissingError
 
 from ..interfaces import Frontend, GraphView, Lens, ObservationContext, ViewList
 
 
 class GraphLens(Lens):
     """Canonical producer of base fx_viewer graph payload per record."""
 
+    # Emit the missing-fast-sugiyama install hint at most once per process.
+    # Missing this dep degrades graph payloads to None but does not abort the
+    # run — all other lenses (accuracy, metadata, adb, ...) continue producing
+    # their records.
+    _warned_fast_sugiyama_missing: bool = False
+
     @classmethod
     def get_name(cls) -> str:
         return "graph"
@@ -57,7 +65,24 @@ def observe(cls, artifact: Any, context: ObservationContext) -> Any:
             return None
 
         exporter = FXGraphExporter(graph_module)
-        payload = exporter.generate_json_payload()
+        try:
+            payload = exporter.generate_json_payload()
+        except _FastSugiyamaMissingError as exc:
+            # First occurrence — log the actionable install hint once.
+            # Subsequent occurrences degrade silently to "no graph payload"
+            # for this record; the run continues, other lenses still fire,
+            # and Archive/Report artifacts are still produced (just without
+            # interactive graphs on records that flow through GraphLens).
+            if not GraphLens._warned_fast_sugiyama_missing:
+                GraphLens._warned_fast_sugiyama_missing = True
+                logging.warning(
+                    "[Observatory] GraphLens: %s Records that would carry an "
+                    "interactive FX graph will be captured without one; other "
+                    "lenses continue normally. This message is shown once per "
+                    "process.",
+                    exc,
+                )
+            return None
 
         base = payload.get("base", {})
         record_name = str(context.shared_state.get("record_name") or "record")