remove direct usage of start_telemetry (#4048)

Summary:
Pull Request resolved: #4048

Use job-level telemetry in tests, examples, and docs in preparation of per-host telemetry actor RFC; default dashboard port to `0`.

Reviewed By: shayne-fletcher

Differential Revision: D106130989

fbshipit-source-id: 71bda3f7a907ec50e93c9581007af4ae456dc6cc

Author: thedavekwon

docs/source/monarch-dashboard.md

@@ -9,8 +9,8 @@ full DAG visualization.
 > **Note** — The Monarch Dashboard is in early development and may change
 > significantly between releases.
 
-The dashboard is included in the `torchmonarch` PyPI package. When you call
-`start_telemetry(include_dashboard=True)`, it starts a local web server that
+The dashboard is included in the `torchmonarch` PyPI package. When a job enables
+`TelemetryConfig(include_dashboard=True)`, Monarch starts a local web server that
 serves the dashboard UI.
 
 ## Quick Start

examples/distributed_telemetry.py

@@ -10,7 +10,7 @@
 
 This example demonstrates querying real tracing data collected from actors:
 
-1. Starts telemetry
+1. Enables job-level telemetry
 2. Spawns actors that do work (generating real tracing events)
 3. Queries the spans, span_events, events, and actors tables
 
@@ -36,7 +36,6 @@
 
 import pyarrow as pa
 from monarch.actor import Actor, endpoint
-from monarch.distributed_telemetry.actor import start_telemetry
 from monarch.job import ProcessJob, TelemetryConfig
 
 
@@ -470,10 +469,7 @@ def run_workload(job, summary=False, interactive=False):
     """Run the full telemetry demo: spawn actors, run work, query, and shut down.
 
     Args:
-        job: JobTrait whose state has a "workers" HostMesh.
-            If the job was created with ``telemetry=TelemetryConfig()``, the
-            query engine is available via ``state.query_engine`` and
-            ``start_telemetry()`` does not need to be called separately.
+        job: JobTrait whose state has a "workers" HostMesh and telemetry enabled.
         summary: If True, print summary output instead of full tables.
         interactive: If True, pause after setup so the dashboard can be browsed.
     """
@@ -482,11 +478,9 @@ def run_workload(job, summary=False, interactive=False):
 
     state = job.state(cached_path=None)
 
-    # Use engine from JobState if available (telemetry configured on job),
-    # otherwise fall back to manual start_telemetry() for backward compat.
     engine = state.query_engine
     if engine is None:
-        engine, _, _scanner = start_telemetry()
+        raise RuntimeError("run_workload requires job.enable_telemetry(...)")
 
     hosts = state.hosts
 

hyperactor_mesh/test/mesh_admin_integration/telemetry.rs

@@ -11,7 +11,7 @@
 //!
 //! These routes proxy to the Monarch dashboard and require
 //! `telemetry_url` to be configured. The Python dining_philosophers
-//! binary is launched with `--dashboard` so that `start_telemetry`
+//! binary is launched with `--dashboard` so that job-level telemetry
 //! starts the dashboard and passes `telemetry_url` to `_spawn_admin`.
 
 use std::time::Duration;

python/monarch/_src/job/job.py

@@ -20,7 +20,7 @@
 from abc import ABC, abstractmethod
 from dataclasses import dataclass
 from pathlib import Path
-from typing import Any, Dict, List, Literal, NamedTuple, Optional, Sequence
+from typing import Any, Dict, List, Literal, NamedTuple, Optional, Self, Sequence
 
 from monarch._rust_bindings.monarch_hyperactor.host_mesh import PyMeshAdminRef
 from monarch._src.actor.bootstrap import attach_to_workers
@@ -522,7 +522,7 @@ def _wrap_state(self, job_state: JobState) -> JobState:
 
     def enable_telemetry(
         self, config: "Optional[TelemetryConfig]" = None, **kwargs
-    ) -> "JobTrait":
+    ) -> Self:
         """Configure automatic telemetry startup on the next :meth:`state` call.
 
         Args:
@@ -537,7 +537,7 @@ def enable_telemetry(
 
     def enable_admin(
         self, config: "Optional[MeshAdminConfig]" = None, **kwargs
-    ) -> "JobTrait":
+    ) -> Self:
         """Configure automatic mesh admin agent startup on the next :meth:`state` call.
 
         Args:

python/monarch/distributed_telemetry/__init__.py

@@ -15,9 +15,11 @@
 3. QueryEngine (Rust): DataFusion query execution
 
 Usage:
-    from monarch.distributed_telemetry.actor import start_telemetry
+    from monarch.job import ProcessJob, TelemetryConfig
 
-    engine, telemetry_url, scanner = start_telemetry()
+    state = ProcessJob({"hosts": 1}).enable_telemetry(TelemetryConfig()).state()
+    engine = state.query_engine
+    assert engine is not None
     # ... spawn procs, they're automatically tracked ...
     result = engine.query("SELECT * FROM metrics")
 """

python/monarch/monarch_dashboard/server/query_engine_adapter.py

@@ -7,7 +7,7 @@
 """Production adapter: wraps the Monarch DataFusion QueryEngine.
 
 Unlike the SQLite-based db.py (local dev/testing), this connects directly
-to the live telemetry engine started by start_telemetry(). The QueryEngine
+to the live telemetry engine attached to a job state. The QueryEngine
 uses DataFusion as its SQL planner/executor and returns pyarrow Tables.
 """
 
@@ -25,8 +25,10 @@ class QueryEngineAdapter(DBAdapter):
 
     Usage::
 
-        from monarch.distributed_telemetry.actor import start_telemetry
-        engine, _, _scanner = start_telemetry()
+        from monarch.job import ProcessJob, TelemetryConfig
+        state = ProcessJob({"hosts": 1}).enable_telemetry(TelemetryConfig()).state()
+        engine = state.query_engine
+        assert engine is not None
         adapter = QueryEngineAdapter(engine)
         rows = adapter.query("SELECT * FROM actors LIMIT 10")
     """