From 97e62dc11b561db29df24260d158ec9dba1f9a0d Mon Sep 17 00:00:00 2001 From: Xuanwo Date: Sat, 14 Nov 2026 15:41:33 +0800 Subject: [PATCH] feat(remote): expose canonical job statistics reports (#5016) Expose `Job::stats()` in Rust and synchronous/asynchronous Python jobs. It reads `POST /v1/jobs/stats` and returns the canonical server-rendered report verbatim, or `None` for a running job or one without a readable durable profile. It does not wait for completion or recompute measurements. On `cc25005525671756b5cf5ebd96492b792e9aa1cb`, all three Rust transport tests and six Python tests passed against the matching rebuilt native extension; strict SDK Clippy also passed. These tests cover optional reports, exact text preservation, fresh reads, errors, and the HTTP boundary with a controlled server. Against the actual Phalanx HTTP route from [Sophon #10247](https://github.com/lancedb/sophon/pull/10247) (`5be3236`), the same native extension also completed two sync and two async reads after durable registry archival, preserving the exact canonical report. This is an HTTP/registry integration fixture, not a Function workload or shared-cluster acceptance. The private runner's JSON field-order collector failed after the successful probe; all raw evidence was retained and hash-verified, and the original receipt was recovered with the corrected parser without rerunning the probe. The follow-up `ad36f66` only corrects the synchronous Python API-reference link to the asynchronous method. Ruff checks and formatting passed; runtime evidence above remains applicable. The actual Phalanx/native-SDK probe covers archived reports; running-job null availability is covered by separate backend and SDK transport tests, not that end-to-end probe. Part of ENT-3501. --- python/python/lancedb/_lancedb.pyi | 1 + python/python/lancedb/job.py | 41 +++++++++++ python/python/tests/test_job.py | 40 +++++++++++ python/python/tests/test_remote_db.py | 44 ++++++++++++ python/src/job.rs | 5 ++ rust/lancedb/src/job.rs | 28 ++++++++ rust/lancedb/src/remote/job.rs | 97 +++++++++++++++++++++++++++ 7 files changed, 256 insertions(+) diff --git a/python/python/lancedb/_lancedb.pyi b/python/python/lancedb/_lancedb.pyi index cbc62f772..1e811d865 100644 --- a/python/python/lancedb/_lancedb.pyi +++ b/python/python/lancedb/_lancedb.pyi @@ -437,6 +437,7 @@ class Job: async def cancel(self) -> None: ... async def refresh(self) -> None: ... async def timeline(self) -> str: ... + async def stats(self) -> Optional[str]: ... async def events( self, *, diff --git a/python/python/lancedb/job.py b/python/python/lancedb/job.py index bf9605567..9195e01ae 100644 --- a/python/python/lancedb/job.py +++ b/python/python/lancedb/job.py @@ -425,6 +425,32 @@ class AsyncJob(Generic[T]): description = self._inner._description if self._inner is not None else None return getattr(description, name) if description is not None else None + async def stats(self) -> Optional[str]: + """Return a printable run report for this Function job. + + The report includes recorded phase timings, finishing-supervisor slot + occupancy, all-attempt split execution and batch latency, and accepted-row + throughput. Each call reads the current server report. + Returns ``None`` while the job is running or if no recorded profile is + available, without waiting for completion. Missing measurements remain + unavailable rather than becoming zero. The server formats the report; + the SDK returns it verbatim. + + Requires a server-side Function job and a server supporting run reports. + Local operations and SQL query handles do not support this operation. + Unsupported operations raise ``NotImplementedError`` or a server error. + This method returns text; use ``print`` to display it. + + Examples + -------- + >>> print(await job.stats()) # doctest: +SKIP + """ + if self._inner is None: + raise NotImplementedError( + "job statistics require a server-side Function job" + ) + return await self._inner.stats() + async def export_timeline(self, path: str | PathLike[str]) -> None: """Write a fresh recorded Function job timeline as Chrome trace JSON. @@ -649,6 +675,21 @@ class Job(Generic[T]): def _field(self, name: str) -> Optional[Any]: return getattr(self._inner, name) if self._inner is not None else None + def stats(self) -> Optional[str]: + """Return a printable Function job run report. + + See [AsyncJob.stats][lancedb.job.AsyncJob.stats] for metrics and availability. + + Examples + -------- + >>> print(job.stats()) # doctest: +SKIP + """ + if self._inner is None: + raise NotImplementedError( + "job statistics require a server-side Function job" + ) + return LOOP.run(self._inner.stats()) + def export_timeline(self, path: str | PathLike[str]) -> None: """Write Chrome trace JSON for this Function job. diff --git a/python/python/tests/test_job.py b/python/python/tests/test_job.py index 690f6414b..9897d97b5 100644 --- a/python/python/tests/test_job.py +++ b/python/python/tests/test_job.py @@ -754,6 +754,46 @@ async def test_query_wait_timeout_requires_keeping_original_handle(): assert "db.open_job" not in message +@pytest.mark.asyncio +@pytest.mark.parametrize("sync", [False, True]) +async def test_stats_returns_fresh_report_without_waiting_or_printing(sync, capsys): + reports = [ + None, + "Function job: finished\nWorker utilization: unavailable\n", + "Function job: finished\nWorker utilization: 25.0%\n", + ] + inner = SimpleNamespace( + stats=AsyncMock(side_effect=reports), + wait=AsyncMock(), + cancel=AsyncMock(), + ) + job = AsyncJob(inner) + for expected in reports: + actual = await asyncio.to_thread(Job(job).stats) if sync else await job.stats() + assert actual == expected + inner.wait.assert_not_awaited() + inner.cancel.assert_not_awaited() + assert capsys.readouterr().out == "" + + +@pytest.mark.asyncio +@pytest.mark.parametrize("sync", [False, True]) +async def test_stats_preserves_errors_and_rejects_untracked_jobs(sync): + error = RuntimeError("run reports are unavailable on this server") + job = AsyncJob(SimpleNamespace(stats=AsyncMock(side_effect=error))) + with pytest.raises(RuntimeError) as exc: + if sync: + await asyncio.to_thread(Job(job).stats) + else: + await job.stats() + assert exc.value is error + with pytest.raises(NotImplementedError, match="server-side Function job"): + if sync: + Job(None).stats() + else: + await AsyncJob(None).stats() + + @pytest.mark.asyncio @pytest.mark.parametrize("sync", [False, True]) async def test_export_timeline_writes_fresh_recording_without_waiting(sync, tmp_path): diff --git a/python/python/tests/test_remote_db.py b/python/python/tests/test_remote_db.py index ea7f73c71..b38ae4a5b 100644 --- a/python/python/tests/test_remote_db.py +++ b/python/python/tests/test_remote_db.py @@ -2732,6 +2732,50 @@ async def test_remote_job_wait_disconnection_timeout_can_be_resumed(sync): assert exc.value.__cause__.is_transport_error is True +@pytest.mark.asyncio +@pytest.mark.parametrize("sync", [False, True]) +async def test_remote_job_stats_returns_native_optional_report(sync): + report = "Function job: finished\nWorker utilization: unavailable\n" + paths = [] + + def handler(request): + payload = json.loads(request.rfile.read(int(request.headers["Content-Length"]))) + assert payload == {"job_id": "refresh-1"} + paths.append(request.path) + if request.path == "/v1/jobs/describe": + response = { + "job_id": "refresh-1", + "job_type": "function_refresh", + "job_state": "IN_PROGRESS", + "creation_ms": 1000, + } + elif request.path == "/v1/jobs/stats": + available = paths.count("/v1/jobs/stats") > 1 + response = { + "job_id": "refresh-1", + "profile": {"future_field": True} if available else None, + "report": report if available else None, + } + else: + raise AssertionError(f"unexpected request: {request.path}") + request.send_response(200) + request.send_header("Content-Type", "application/json") + request.end_headers() + request.wfile.write(json.dumps(response).encode()) + + if sync: + with mock_lancedb_connection(handler) as db: + job = db.open_job("refresh-1") + assert job.stats() is None + assert job.stats() == report + else: + async with mock_lancedb_connection_async(handler) as db: + job = await db.open_job("refresh-1") + assert await job.stats() is None + assert await job.stats() == report + assert paths == ["/v1/jobs/describe", "/v1/jobs/stats", "/v1/jobs/stats"] + + @pytest.mark.asyncio @pytest.mark.parametrize("sync", [False, True]) @pytest.mark.parametrize( diff --git a/python/src/job.rs b/python/src/job.rs index 0d411072f..08f6440ab 100644 --- a/python/src/job.rs +++ b/python/src/job.rs @@ -159,6 +159,11 @@ impl Job { }) } + pub fn stats(self_: PyRef<'_, Self>) -> PyResult> { + let inner = self_.inner.clone(); + future_into_py(self_.py(), async move { inner.stats().await.infer_error() }) + } + #[pyo3(signature = (*, limit=None, filter=None))] pub fn events( self_: PyRef<'_, Self>, diff --git a/rust/lancedb/src/job.rs b/rust/lancedb/src/job.rs index 092ece8b5..b1e3c1bbf 100644 --- a/rust/lancedb/src/job.rs +++ b/rust/lancedb/src/job.rs @@ -90,6 +90,11 @@ pub(crate) trait JobHandle: Send + Sync { job_detail_not_supported("job timeline export") } + /// A printable report of recorded Function job metrics. + async fn stats(&self) -> Result> { + job_detail_not_supported("job statistics") + } + /// The job's recorded lifecycle events. async fn events(&self, _request: JobEventsRequest) -> Result> { job_detail_not_supported("job event history") @@ -531,6 +536,29 @@ where } } + /// Fetch a printable run report for a server-side Function job. + /// + /// The server report includes recorded phase timings, finishing-supervisor + /// slot occupancy, all-attempt split execution and batch latency, and + /// accepted-row throughput. Returns `None` for running jobs or when no recorded + /// profile is available, without waiting for completion. Requires server + /// support; local operations and SQL query handles do not support reports. + /// + /// ```no_run + /// # async fn report(job: &lancedb::job::Job) -> Result<(), Box> { + /// if let Some(report) = job.stats().await? { + /// println!("{report}"); + /// } + /// # Ok(()) + /// # } + /// ``` + pub async fn stats(&self) -> Result> { + match &self.inner { + JobInner::Handle { handle, .. } => handle.stats().await, + JobInner::Completed(_) => job_detail_not_supported("job statistics"), + } + } + /// Waits until the operation reaches a terminal state. /// /// Returns the endpoint's typed result. Unit-result jobs return `()`. diff --git a/rust/lancedb/src/remote/job.rs b/rust/lancedb/src/remote/job.rs index 5a0afa7e8..c546ce4d1 100644 --- a/rust/lancedb/src/remote/job.rs +++ b/rust/lancedb/src/remote/job.rs @@ -261,6 +261,35 @@ impl JobHandle for RemoteJob { Ok(trace) } + async fn stats(&self) -> Result> { + let request = self + .client + .post("/v1/jobs/stats") + .json(&serde_json::json!({"job_id": self.job_id})); + let (request_id, response) = self.client.send(request).await?; + let response = self.client.check_response(&request_id, response).await?; + let body = response.text().await.err_to_http(request_id.clone())?; + let response: serde_json::Value = + serde_json::from_str(&body).map_err(|error| Error::Http { + source: format!("failed to parse job statistics: {error}").into(), + request_id: request_id.clone(), + status_code: None, + })?; + if response.get("job_id").and_then(serde_json::Value::as_str) == Some(self.job_id.as_str()) + { + match response.get("report") { + Some(serde_json::Value::Null) => return Ok(None), + Some(serde_json::Value::String(report)) => return Ok(Some(report.clone())), + _ => {} + } + } + Err(Error::Http { + source: "server response is not a Function job run report; job statistics require server support".into(), + request_id, + status_code: None, + }) + } + async fn events(&self, request: JobEventsRequest) -> Result> { let mut body = serde_json::json!({ "job_id": self.job_id }); if let Some(limit) = request.limit { @@ -354,6 +383,74 @@ mod tests { include_str!("../../tests/fixtures/first_class_functions/v1/remote_unit_job.json"); const MISSING_RESULT_JOB: &str = r#"{"job_state":"DONE"}"#; + #[tokio::test] + async fn stats_reads_report_verbatim_and_preserves_unavailable_without_waiting() { + let requests = Arc::new(AtomicUsize::new(0)); + let seen = requests.clone(); + let report = "Function job: finished\nWorker utilization: unavailable\n"; + let client = client_with_handler(move |request| { + assert_eq!(request.method(), reqwest::Method::POST); + assert_eq!(request.url().path(), "/v1/jobs/stats"); + let body: serde_json::Value = + serde_json::from_slice(request.body().unwrap().as_bytes().unwrap()).unwrap(); + assert_eq!(body, serde_json::json!({"job_id":"job-1"})); + let response = if seen.fetch_add(1, Ordering::SeqCst) == 0 { + serde_json::json!({"job_id":"job-1","profile":null,"report":null}) + } else { + serde_json::json!({"job_id":"job-1","profile":{"future_field":17},"report":report}) + }; + http::Response::builder() + .status(200) + .body(response.to_string()) + .unwrap() + }); + let job = Job::new(Box::new(RemoteJob::new(client, "job-1".to_string()))); + assert_eq!(job.stats().await.unwrap(), None); + assert_eq!(requests.load(Ordering::SeqCst), 1); + assert_eq!(job.stats().await.unwrap().as_deref(), Some(report)); + assert_eq!(requests.load(Ordering::SeqCst), 2); + } + + #[tokio::test] + async fn stats_rejects_malformed_or_unrelated_responses() { + for body in [ + "{", + r#"{"job_id":"job-1"}"#, + r#"{"job_id":"job-1","report":7}"#, + r#"{"job_id":"another-job","report":"a report"}"#, + ] { + let client = client_with_handler(move |_| { + http::Response::builder().status(200).body(body).unwrap() + }); + let error = RemoteJob::new(client, "job-1".to_string()) + .stats() + .await + .unwrap_err(); + assert!(matches!(error, crate::Error::Http { .. })); + assert!(error.to_string().contains("job statistics")); + } + } + + #[tokio::test] + async fn stats_preserves_not_found_errors() { + let client = client_with_handler(|_| { + http::Response::builder() + .status(404) + .body("job not found") + .unwrap() + }); + let error = RemoteJob::new(client, "missing".to_string()) + .stats() + .await + .unwrap_err(); + match error { + crate::Error::Http { status_code, .. } => { + assert_eq!(status_code, Some(reqwest::StatusCode::NOT_FOUND)); + } + other => panic!("expected HTTP 404, got {other:?}"), + } + } + struct FixtureRemoteJob(&'static str); #[async_trait]