From e0720601c67d40af8f15abc8d9ca8dbaf2538af4 Mon Sep 17 00:00:00 2001 From: Pradeep Garigipati Date: Fri, 7 Aug 2026 07:15:48 +0530 Subject: [PATCH 1/6] feat(nvtx): add context server routes --- Cargo.lock | 21 + Cargo.toml | 1 + .../query_engine/server/src/analyzer_cache.rs | 80 ++- domains/query_engine/server/src/lib.rs | 19 +- domains/query_engine/server/src/ui.rs | 29 + domains/query_engine/ui/src/lib.rs | 16 +- integrations/nvtx/server/Cargo.toml | 31 + integrations/nvtx/server/src/lib.rs | 541 ++++++++++++++++++ 8 files changed, 735 insertions(+), 3 deletions(-) create mode 100644 integrations/nvtx/server/Cargo.toml create mode 100644 integrations/nvtx/server/src/lib.rs diff --git a/Cargo.lock b/Cargo.lock index ea3c5c8d6..19427e926 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -2128,6 +2128,27 @@ dependencies = [ "thiserror", ] +[[package]] +name = "nvtx-server" +version = "0.1.0" +dependencies = [ + "axum", + "moka", + "nvtx-analyzer", + "nvtx-bridge", + "nvtx-events", + "nvtx-ui", + "quent-events", + "quent-io", + "serde", + "serde_json", + "tempfile", + "tokio", + "tower", + "tracing", + "uuid", +] + [[package]] name = "nvtx-ui" version = "0.1.0" diff --git a/Cargo.toml b/Cargo.toml index 3a4989869..f867c30cc 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -31,6 +31,7 @@ members = [ "integrations/nvtx/example", "integrations/nvtx/analyzer", "integrations/nvtx/ui", + "integrations/nvtx/server", # Domain-specific crates "domains/query_engine/analyzer", "domains/query_engine/model", diff --git a/domains/query_engine/server/src/analyzer_cache.rs b/domains/query_engine/server/src/analyzer_cache.rs index cb355bd08..21f754aae 100644 --- a/domains/query_engine/server/src/analyzer_cache.rs +++ b/domains/query_engine/server/src/analyzer_cache.rs @@ -1,7 +1,7 @@ // SPDX-FileCopyrightText: Copyright (c) 2026, NVIDIA CORPORATION & AFFILIATES. All rights reserved. // SPDX-License-Identifier: Apache-2.0 -use std::collections::{BTreeSet, HashMap, HashSet}; +use std::collections::{BTreeMap, BTreeSet, HashMap, HashSet}; use std::path::Path; use std::{sync::Arc, time::Duration}; @@ -42,6 +42,10 @@ pub struct EngineIndex { contexts: HashMap>, /// Engine id to its workers and the context each was found in. workers: HashMap>, + /// Engine id to context id to the resource-group entities observed in that + /// context. This lets context-wide integrations sit beside the resources + /// owned by the same process without claiming query correlation. + context_resources: HashMap>>, } impl EngineIndex { @@ -54,12 +58,22 @@ impl EngineIndex { fn add_worker(&mut self, engine_id: Uuid, worker_id: Uuid, context_id: Uuid) { self.attribute_context(engine_id, context_id); + self.attribute_resource(engine_id, context_id, worker_id); self.workers .entry(engine_id) .or_default() .push((worker_id, context_id)); } + fn attribute_resource(&mut self, engine_id: Uuid, context_id: Uuid, resource_id: Uuid) { + self.context_resources + .entry(engine_id) + .or_default() + .entry(context_id) + .or_default() + .insert(resource_id); + } + /// All known engine ids. pub fn engine_ids(&self) -> impl Iterator + '_ { self.contexts.keys().copied() @@ -78,6 +92,21 @@ impl EngineIndex { pub fn workers_of(&self, engine_id: Uuid) -> &[(Uuid, Uuid)] { self.workers.get(&engine_id).map_or(&[], Vec::as_slice) } + + /// Resource-group entity IDs observed in each context of `engine_id`. + pub fn context_resources_of(&self, engine_id: Uuid) -> BTreeMap> { + let mut resources: BTreeMap> = self + .contexts_of(engine_id) + .into_iter() + .map(|context_id| (context_id, Vec::new())) + .collect(); + if let Some(by_context) = self.context_resources.get(&engine_id) { + for (&context_id, resource_ids) in by_context { + resources.insert(context_id, resource_ids.iter().copied().collect()); + } + } + resources + } } /// A dumb lister for query-engine-domain models: scan every `//` @@ -117,6 +146,7 @@ pub fn index_query_engines(output_dir: &Path) -> ServerResult { let event = event?; if seen.insert(event.id) { index.attribute_context(event.id, context_id); + index.attribute_resource(event.id, context_id, event.id); } } } @@ -202,6 +232,15 @@ where Ok((self.lister)()?.engine_ids().collect()) } + pub(crate) fn contexts(&self, engine_id: Uuid) -> ServerResult { + let index = (self.lister)()?; + Ok(ui::EngineContexts { + engine_id, + context_ids: index.contexts_of(engine_id), + context_resources: index.context_resources_of(engine_id), + }) + } + pub(crate) async fn list_with_metadata(&self) -> ServerResult> { let lister = Arc::clone(&self.lister); let importer = Arc::clone(&self.importer); @@ -241,3 +280,42 @@ where .map_err(|e: Arc| ServerError::Cache(format!("{e:?}"))) } } + +#[cfg(test)] +mod tests { + use super::*; + + #[test] + fn engine_context_inventory_is_deduplicated_and_sorted() { + let engine_id = Uuid::from_u128(1); + let earlier = Uuid::from_u128(2); + let later = Uuid::from_u128(3); + let mut index = EngineIndex::default(); + index.attribute_context(engine_id, later); + index.attribute_context(engine_id, earlier); + index.attribute_context(engine_id, later); + + assert_eq!(index.contexts_of(engine_id), vec![earlier, later]); + assert!(index.contexts_of(Uuid::from_u128(4)).is_empty()); + } + + #[test] + fn context_inventory_retains_resource_ownership() { + let engine_id = Uuid::from_u128(1); + let engine_context = Uuid::from_u128(2); + let worker_context = Uuid::from_u128(3); + let worker_id = Uuid::from_u128(4); + let mut index = EngineIndex::default(); + index.attribute_context(engine_id, engine_context); + index.attribute_resource(engine_id, engine_context, engine_id); + index.add_worker(engine_id, worker_id, worker_context); + + assert_eq!( + index.context_resources_of(engine_id), + BTreeMap::from([ + (engine_context, vec![engine_id]), + (worker_context, vec![worker_id]), + ]) + ); + } +} diff --git a/domains/query_engine/server/src/lib.rs b/domains/query_engine/server/src/lib.rs index 2f08670aa..9b00cf2ad 100644 --- a/domains/query_engine/server/src/lib.rs +++ b/domains/query_engine/server/src/lib.rs @@ -55,6 +55,21 @@ pub fn analyzer_service_router( lister: Box, cors: Option, ) -> Result> +where + A: UiAnalyzer + Send + Sync + 'static, + ::EntityRef: serde::Serialize, +{ + analyzer_service_router_with_routes::(importer, lister, cors, AxumRouter::new()) +} + +/// Build the analyzer router and merge integration-owned routes before common +/// CORS and embedded-UI fallback layers are installed. +pub fn analyzer_service_router_with_routes( + importer: Box>, + lister: Box, + cors: Option, + additional_routes: AxumRouter, +) -> Result> where A: UiAnalyzer + Send + Sync + 'static, ::EntityRef: serde::Serialize, @@ -64,7 +79,9 @@ where timelines: TimelineCache::new(), }; - let mut http_routes = axum::Router::new().nest("/api/engines", ui::routes(state)); + let mut http_routes = axum::Router::new() + .nest("/api/engines", ui::routes(state)) + .merge(additional_routes); #[cfg(feature = "swagger")] { diff --git a/domains/query_engine/server/src/ui.rs b/domains/query_engine/server/src/ui.rs index 8729d4a5f..63a0b8240 100644 --- a/domains/query_engine/server/src/ui.rs +++ b/domains/query_engine/server/src/ui.rs @@ -114,6 +114,33 @@ where Ok(Json(analyzer.query_engine_model().engine()?.to_ui()?)) } +/// List every Quent context attributed to an engine. +#[cfg_attr(feature = "swagger", utoipa::path( + get, + path = "/api/engines/{engine_id}/contexts", + tag = "engines", + params( + ("engine_id" = Uuid, Path, description = "The engine ID") + ), + responses( + (status = 200, description = "Contexts contributing telemetry to the engine", body = Object) + ) +))] +#[tracing::instrument(skip_all, err)] +async fn engine_contexts( + State(state): State>, + Path(engine_id): Path, +) -> ServerResult> +where + A: UiAnalyzer + Send + Sync + 'static, +{ + let contexts = state.analyzers.contexts(engine_id).map_err(|error| { + tracing::error!(%error, %engine_id, "engine context inventory failed"); + crate::error::ServerError::Cache("engine context inventory could not be loaded".to_owned()) + })?; + Ok(Json(contexts)) +} + // TODO(johanpel): pagination /// List all query groups for a given engine. #[cfg_attr(feature = "swagger", utoipa::path( @@ -329,6 +356,7 @@ where paths( list_engines, engine, + engine_contexts, list_query_groups, list_queries, query, @@ -353,6 +381,7 @@ where Router::new() .route("/", get(list_engines)) .route("/{engine_id}", get(engine)) + .route("/{engine_id}/contexts", get(engine_contexts)) .route("/{engine_id}/query-groups", get(list_query_groups)) .route( "/{engine_id}/query_group/{query_group_id}/queries", diff --git a/domains/query_engine/ui/src/lib.rs b/domains/query_engine/ui/src/lib.rs index e73556c0a..bb04f323d 100644 --- a/domains/query_engine/ui/src/lib.rs +++ b/domains/query_engine/ui/src/lib.rs @@ -15,10 +15,24 @@ use quent_ui::{ quantity::QuantitySpec, }; use serde::{Deserialize, Serialize}; -use std::collections::HashMap; +use std::collections::{BTreeMap, HashMap}; use ts_rs::TS; use uuid::Uuid; +/// Quent contexts whose streams contribute to one engine view. +/// +/// This is intentionally an inventory only. It does not claim that every +/// context contains a particular query or NVTX stream. +#[derive(TS, Debug, Clone, PartialEq, Eq, Serialize, Deserialize)] +pub struct EngineContexts { + pub engine_id: Uuid, + pub context_ids: Vec, + /// Resource-group entities observed in each context, keyed by context ID. + /// Engine IDs identify engine-owned contexts and worker IDs identify the + /// process-local worker beneath which context-wide integrations belong. + pub context_resources: BTreeMap>, +} + /// Global timeline-request parameter identifying the query to report on. #[derive(TS, Debug, Clone, PartialEq, Eq, Hash, Serialize, Deserialize)] pub struct QueryFilter { diff --git a/integrations/nvtx/server/Cargo.toml b/integrations/nvtx/server/Cargo.toml new file mode 100644 index 000000000..ceef0e945 --- /dev/null +++ b/integrations/nvtx/server/Cargo.toml @@ -0,0 +1,31 @@ +# SPDX-FileCopyrightText: Copyright (c) 2026, NVIDIA CORPORATION & AFFILIATES. All rights reserved. +# SPDX-License-Identifier: Apache-2.0 + +[package] +name = "nvtx-server" +version.workspace = true +edition.workspace = true +publish.workspace = true + +[features] +default = [] +real-capture-tests = ["nvtx-analyzer/real-capture-tests"] + +[dependencies] +axum = { version = "0.8.7" } +moka = { version = "0.12.13", features = ["future", "sync"] } +nvtx-analyzer = { path = "../analyzer" } +nvtx-bridge = { path = "../bridge" } +nvtx-ui = { path = "../ui" } +quent-events = { path = "../../../crates/events" } +quent-io = { path = "../../../crates/io" } +serde.workspace = true +tokio = { workspace = true, features = ["rt-multi-thread", "sync"] } +tracing.workspace = true +uuid.workspace = true + +[dev-dependencies] +nvtx-events = { path = "../events" } +serde_json.workspace = true +tempfile = "3" +tower = { version = "0.5", features = ["util"] } diff --git a/integrations/nvtx/server/src/lib.rs b/integrations/nvtx/server/src/lib.rs new file mode 100644 index 000000000..2e32f46da --- /dev/null +++ b/integrations/nvtx/server/src/lib.rs @@ -0,0 +1,541 @@ +// SPDX-FileCopyrightText: Copyright (c) 2026, NVIDIA CORPORATION & AFFILIATES. All rights reserved. +// SPDX-License-Identifier: Apache-2.0 + +//! Context-keyed NVTX reconstruction cache and Axum routes. + +use std::error::Error; +use std::fmt; +use std::path::Path; +use std::sync::Arc; +use std::time::Duration; + +use axum::extract::{DefaultBodyLimit, Path as AxumPath, Query, State}; +use axum::http::StatusCode; +use axum::response::{IntoResponse, Response}; +use axum::routing::{get, post}; +use axum::{Json, Router}; +use moka::{future::Cache as AsyncCache, sync::Cache as SyncCache}; +use nvtx_analyzer::{NvtxModel, NvtxModelBuilder}; +use nvtx_bridge::NvtxEventEntity; +use nvtx_ui::{NvtxCatalog, NvtxViewportRequest, NvtxViewportResponse}; +use quent_events::{EntityEvent, Event}; +use quent_io::filesystem::{self, Format}; +use quent_io::{ImporterOptions, ImporterProvider}; +use uuid::Uuid; + +const MAX_BODY_BYTES: usize = 64 * 1024; +const MAX_DOMAIN_FILTERS: usize = 256; +const MAX_CATEGORY_FILTERS: usize = 4096; +const MAX_CATALOG_ORIGINS: u64 = 32; + +/// A redacted importer failure. Details are logged server-side and are never +/// copied into an HTTP response. +#[derive(Debug, Clone)] +pub struct NvtxImporterError(String); + +impl NvtxImporterError { + pub fn new(error: impl fmt::Display) -> Self { + Self(error.to_string()) + } +} + +impl fmt::Display for NvtxImporterError { + fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { + f.write_str(&self.0) + } +} + +impl Error for NvtxImporterError {} + +pub type NvtxImporterResult = Result; + +/// Loads only one context's NVTX entity stream. `None` is a cacheable absence; +/// `Some(Vec::new())` is a present but empty stream. +pub type NvtxImporterFn = + dyn Fn(Uuid) -> NvtxImporterResult>>> + Send + Sync; + +/// Import one context's NVTX stream from the standard filesystem layout. +pub fn import_context_events( + root: &Path, + context_id: Uuid, +) -> NvtxImporterResult>>> { + let context_dir = root.join(context_id.to_string()); + let stream_dir = context_dir.join(::NAME); + if !stream_dir.is_dir() { + return Ok(None); + } + let mut stream_entries = std::fs::read_dir(&stream_dir).map_err(NvtxImporterError::new)?; + match stream_entries.next() { + None => return Ok(Some(Vec::new())), + Some(Err(error)) => return Err(NvtxImporterError::new(error)), + Some(Ok(_)) => {} + } + let format = Format::detect(&context_dir) + .ok_or_else(|| NvtxImporterError::new("unable to detect context stream format"))?; + let importer = >::create_importer( + &ImporterOptions::FileSystem(filesystem::importer::Options { + format, + path: stream_dir, + }), + ) + .map_err(NvtxImporterError::new)?; + importer + .collect::>>() + .map(Some) + .map_err(NvtxImporterError::new) +} + +enum CachedModel { + Absent, + Present(Box), +} + +struct CachedNvtx { + model: NvtxModel, + catalogs: SyncCache>, +} + +impl CachedNvtx { + fn new(model: NvtxModel) -> Self { + Self { + model, + catalogs: SyncCache::builder() + .max_capacity(MAX_CATALOG_ORIGINS) + .build(), + } + } + + fn catalog(&self, query_start: u64) -> Arc { + self.catalogs.get_with(query_start, || { + Arc::new(NvtxCatalog::from_model(&self.model, query_start)) + }) + } +} + +#[derive(Clone)] +struct NvtxModelCache { + models: AsyncCache>, + importer: Arc, +} + +impl NvtxModelCache { + fn new(importer: Box) -> Self { + Self { + models: AsyncCache::builder() + .max_capacity(128) + .time_to_idle(Duration::from_hours(24)) + .build(), + importer: Arc::from(importer), + } + } + + async fn get(&self, context_id: Uuid) -> Result, NvtxServerError> { + let importer = Arc::clone(&self.importer); + self.models + .entry(context_id) + .or_try_insert_with(async move { + tokio::task::spawn_blocking(move || match importer(context_id) { + Ok(Some(events)) => { + let model = NvtxModelBuilder::build(events); + Ok(Arc::new(CachedModel::Present(Box::new(CachedNvtx::new( + model, + ))))) + } + Ok(None) => Ok(Arc::new(CachedModel::Absent)), + Err(error) => Err(NvtxServerError::Internal(error.to_string())), + }) + .await + .map_err(|error| NvtxServerError::Internal(error.to_string()))? + }) + .await + .map(|entry| entry.into_value()) + .map_err(|error: Arc| (*error).clone()) + } +} + +#[derive(Clone)] +struct NvtxState { + cache: NvtxModelCache, +} + +#[derive(Debug, Clone, Copy, serde::Deserialize)] +struct NvtxTimeOrigin { + query_start: u64, +} + +#[derive(Debug, Clone)] +enum NvtxServerError { + BadRequest(String), + NotFound, + Internal(String), +} + +impl IntoResponse for NvtxServerError { + fn into_response(self) -> Response { + match self { + Self::BadRequest(message) => (StatusCode::BAD_REQUEST, message).into_response(), + Self::NotFound => (StatusCode::NOT_FOUND, "NVTX stream not found").into_response(), + Self::Internal(error) => { + tracing::error!(%error, "NVTX context load failed"); + ( + StatusCode::INTERNAL_SERVER_ERROR, + "NVTX data could not be loaded", + ) + .into_response() + } + } + } +} + +async fn catalog( + State(state): State, + AxumPath(context_id): AxumPath, + Query(origin): Query, +) -> Result, NvtxServerError> { + match state.cache.get(context_id).await?.as_ref() { + CachedModel::Absent => Err(NvtxServerError::NotFound), + CachedModel::Present(cached) => Ok(Json((*cached.catalog(origin.query_start)).clone())), + } +} + +async fn viewport( + State(state): State, + AxumPath(context_id): AxumPath, + Query(origin): Query, + Json(request): Json, +) -> Result, NvtxServerError> { + validate_filter_count(&request)?; + match state.cache.get(context_id).await?.as_ref() { + CachedModel::Absent => Err(NvtxServerError::NotFound), + CachedModel::Present(cached) => { + let catalog = cached.catalog(origin.query_start); + NvtxViewportResponse::from_model_with_catalog(&cached.model, &catalog, request) + .map(Json) + .map_err(|error| NvtxServerError::BadRequest(error.to_string())) + } + } +} + +fn validate_filter_count(request: &NvtxViewportRequest) -> Result<(), NvtxServerError> { + if request.selections.len() > MAX_DOMAIN_FILTERS { + return Err(NvtxServerError::BadRequest( + "too many domain filters".to_owned(), + )); + } + let category_count = request + .selections + .iter() + .try_fold(0_usize, |total, selection| { + total.checked_add(selection.category_ids.len()) + }) + .ok_or_else(|| NvtxServerError::BadRequest("too many category filters".to_owned()))?; + if category_count > MAX_CATEGORY_FILTERS { + return Err(NvtxServerError::BadRequest( + "too many category filters".to_owned(), + )); + } + Ok(()) +} + +/// Context-keyed NVTX API routes, ready to merge into the host service before +/// its common CORS and embedded-UI fallback layers. +/// +/// Catalog and viewport requests require a `query_start` query parameter in +/// Unix nanoseconds. Public viewport times are seconds relative to that origin. +pub fn routes(importer: Box) -> Router { + let state = NvtxState { + cache: NvtxModelCache::new(importer), + }; + Router::new() + .route("/api/nvtx/contexts/{context_id}/catalog", get(catalog)) + .route("/api/nvtx/contexts/{context_id}/viewport", post(viewport)) + .layer(DefaultBodyLimit::max(MAX_BODY_BYTES)) + .with_state(state) +} + +#[cfg(test)] +mod tests { + use std::sync::atomic::{AtomicUsize, Ordering}; + + use axum::body::{Body, to_bytes}; + use axum::http::Request; + use nvtx_events::{NvtxEvent, NvtxEventAttributes, NvtxMessage}; + use tempfile::tempdir; + use tower::ServiceExt; + + use super::*; + + const QUERY_START: u64 = 2_000_000_000; + const RANGE_END: u64 = 3_000_000_000; + + fn range_events(context_id: Uuid) -> Vec> { + let attributes = NvtxEventAttributes { + message: Some(NvtxMessage::String("work".to_owned())), + ..Default::default() + }; + vec![ + Event::new( + context_id, + QUERY_START, + NvtxEventEntity(NvtxEvent::RangeStart { + domain: 4, + range_id: 9, + attributes, + }), + ), + Event::new( + context_id, + RANGE_END, + NvtxEventEntity(NvtxEvent::RangeEnd { + domain: 4, + range_id: 9, + }), + ), + ] + } + + #[tokio::test] + async fn model_and_query_relative_catalogs_are_cached_end_to_end() { + let present = Uuid::from_u128(1); + let loads = Arc::new(AtomicUsize::new(0)); + let importer_loads = Arc::clone(&loads); + let app = routes(Box::new(move |context_id| { + importer_loads.fetch_add(1, Ordering::SeqCst); + Ok((context_id == present).then(|| range_events(context_id))) + })); + + let response = app + .clone() + .oneshot( + Request::get(format!( + "/api/nvtx/contexts/{present}/catalog?query_start={QUERY_START}" + )) + .body(Body::empty()) + .unwrap(), + ) + .await + .unwrap(); + assert_eq!(response.status(), StatusCode::OK); + let body = to_bytes(response.into_body(), usize::MAX).await.unwrap(); + let catalog: serde_json::Value = serde_json::from_slice(&body).unwrap(); + assert_eq!(catalog["trace_start"], 0.0); + assert_eq!(catalog["trace_end"], 1.0); + assert!(catalog.get("query_start").is_none()); + + let alternate_origin = QUERY_START + 500_000_000; + let alternate = app + .clone() + .oneshot( + Request::get(format!( + "/api/nvtx/contexts/{present}/catalog?query_start={alternate_origin}" + )) + .body(Body::empty()) + .unwrap(), + ) + .await + .unwrap(); + let body = to_bytes(alternate.into_body(), usize::MAX).await.unwrap(); + let alternate: serde_json::Value = serde_json::from_slice(&body).unwrap(); + assert_eq!(alternate["trace_start"], -0.5); + assert_eq!(alternate["trace_end"], 0.5); + + let request = NvtxViewportRequest { + viewport: nvtx_ui::NvtxViewportWindow { + start: 0.0, + end: 1.0, + }, + selections: vec![nvtx_ui::NvtxDomainSelection { + domain_id: 4, + category_ids: vec![], + include_uncategorized: true, + }], + }; + let response = app + .oneshot( + Request::post(format!( + "/api/nvtx/contexts/{present}/viewport?query_start={QUERY_START}" + )) + .header("content-type", "application/json") + .body(Body::from(serde_json::to_vec(&request).unwrap())) + .unwrap(), + ) + .await + .unwrap(); + assert_eq!(response.status(), StatusCode::OK); + let body = to_bytes(response.into_body(), usize::MAX).await.unwrap(); + let viewport: NvtxViewportResponse = serde_json::from_slice(&body).unwrap(); + assert_eq!(viewport.statistics[0].total_duration, 1.0); + assert_eq!( + loads.load(Ordering::SeqCst), + 1, + "one reconstruction per context" + ); + } + + #[tokio::test] + async fn absent_and_empty_streams_are_distinct() { + let empty = Uuid::from_u128(2); + let absent = Uuid::from_u128(3); + let app = routes(Box::new(move |context_id| { + Ok((context_id == empty).then(Vec::new)) + })); + + let empty_response = app + .clone() + .oneshot( + Request::get(format!( + "/api/nvtx/contexts/{empty}/catalog?query_start={QUERY_START}" + )) + .body(Body::empty()) + .unwrap(), + ) + .await + .unwrap(); + assert_eq!(empty_response.status(), StatusCode::OK); + + let absent_response = app + .oneshot( + Request::get(format!( + "/api/nvtx/contexts/{absent}/catalog?query_start={QUERY_START}" + )) + .body(Body::empty()) + .unwrap(), + ) + .await + .unwrap(); + assert_eq!(absent_response.status(), StatusCode::NOT_FOUND); + } + + #[test] + fn filesystem_importer_recognizes_an_empty_present_stream() { + let root = tempdir().unwrap(); + let context_id = Uuid::from_u128(8); + std::fs::create_dir_all( + root.path() + .join(context_id.to_string()) + .join(::NAME), + ) + .unwrap(); + + let imported = import_context_events(root.path(), context_id).unwrap(); + assert!(imported.is_some_and(|events| events.is_empty())); + } + + #[tokio::test] + async fn invalid_selector_is_a_bounded_bad_request() { + let present = Uuid::from_u128(4); + let app = routes(Box::new(move |context_id| { + Ok((context_id == present).then(|| range_events(context_id))) + })); + let request = NvtxViewportRequest { + viewport: nvtx_ui::NvtxViewportWindow { + start: 0.0, + end: 1.0, + }, + selections: vec![nvtx_ui::NvtxDomainSelection { + domain_id: 4, + category_ids: vec![], + include_uncategorized: false, + }], + }; + let response = app + .oneshot( + Request::post(format!( + "/api/nvtx/contexts/{present}/viewport?query_start={QUERY_START}" + )) + .header("content-type", "application/json") + .body(Body::from(serde_json::to_vec(&request).unwrap())) + .unwrap(), + ) + .await + .unwrap(); + assert_eq!(response.status(), StatusCode::BAD_REQUEST); + } + + #[tokio::test] + async fn malformed_paths_and_oversized_requests_are_rejected() { + let present = Uuid::from_u128(5); + let app = routes(Box::new(move |context_id| { + Ok((context_id == present).then(|| range_events(context_id))) + })); + + let invalid_uuid = app + .clone() + .oneshot( + Request::get(format!( + "/api/nvtx/contexts/not-a-uuid/catalog?query_start={QUERY_START}" + )) + .body(Body::empty()) + .unwrap(), + ) + .await + .unwrap(); + assert_eq!(invalid_uuid.status(), StatusCode::BAD_REQUEST); + + let missing_origin = app + .clone() + .oneshot( + Request::get(format!("/api/nvtx/contexts/{present}/catalog")) + .body(Body::empty()) + .unwrap(), + ) + .await + .unwrap(); + assert_eq!(missing_origin.status(), StatusCode::BAD_REQUEST); + + let oversized = app + .oneshot( + Request::post(format!( + "/api/nvtx/contexts/{present}/viewport?query_start={QUERY_START}" + )) + .header("content-type", "application/json") + .body(Body::from(vec![b' '; MAX_BODY_BYTES + 1])) + .unwrap(), + ) + .await + .unwrap(); + assert_eq!(oversized.status(), StatusCode::PAYLOAD_TOO_LARGE); + } + + #[tokio::test] + async fn importer_failures_are_redacted_and_isolated_by_context() { + let failing = Uuid::from_u128(6); + let present = Uuid::from_u128(7); + let app = routes(Box::new(move |context_id| { + if context_id == failing { + Err(NvtxImporterError::new( + "/secret/capture/path could not be read", + )) + } else { + Ok((context_id == present).then(|| range_events(context_id))) + } + })); + + let failed = app + .clone() + .oneshot( + Request::get(format!( + "/api/nvtx/contexts/{failing}/catalog?query_start={QUERY_START}" + )) + .body(Body::empty()) + .unwrap(), + ) + .await + .unwrap(); + assert_eq!(failed.status(), StatusCode::INTERNAL_SERVER_ERROR); + let failed_body = to_bytes(failed.into_body(), usize::MAX).await.unwrap(); + assert_eq!(&failed_body[..], b"NVTX data could not be loaded"); + + let healthy = app + .oneshot( + Request::get(format!( + "/api/nvtx/contexts/{present}/catalog?query_start={QUERY_START}" + )) + .body(Body::empty()) + .unwrap(), + ) + .await + .unwrap(); + assert_eq!(healthy.status(), StatusCode::OK); + } +} From 064ca8b133be13a37b0878f34196b1a4bdecab61 Mon Sep 17 00:00:00 2001 From: Pradeep Garigipati Date: Wed, 12 Aug 2026 11:08:09 +0530 Subject: [PATCH 2/6] fix(nvtx): offload viewport reconstruction --- integrations/nvtx/server/src/lib.rs | 31 +++++++++++++++++++++++++---- 1 file changed, 27 insertions(+), 4 deletions(-) diff --git a/integrations/nvtx/server/src/lib.rs b/integrations/nvtx/server/src/lib.rs index 2e32f46da..f36e716af 100644 --- a/integrations/nvtx/server/src/lib.rs +++ b/integrations/nvtx/server/src/lib.rs @@ -187,15 +187,26 @@ impl IntoResponse for NvtxServerError { } } +async fn run_model_task(task: impl FnOnce() -> T + Send + 'static) -> Result +where + T: Send + 'static, +{ + tokio::task::spawn_blocking(task) + .await + .map_err(|error| NvtxServerError::Internal(error.to_string())) +} + async fn catalog( State(state): State, AxumPath(context_id): AxumPath, Query(origin): Query, ) -> Result, NvtxServerError> { - match state.cache.get(context_id).await?.as_ref() { + let cached_model = state.cache.get(context_id).await?; + run_model_task(move || match cached_model.as_ref() { CachedModel::Absent => Err(NvtxServerError::NotFound), CachedModel::Present(cached) => Ok(Json((*cached.catalog(origin.query_start)).clone())), - } + }) + .await? } async fn viewport( @@ -205,7 +216,8 @@ async fn viewport( Json(request): Json, ) -> Result, NvtxServerError> { validate_filter_count(&request)?; - match state.cache.get(context_id).await?.as_ref() { + let cached_model = state.cache.get(context_id).await?; + run_model_task(move || match cached_model.as_ref() { CachedModel::Absent => Err(NvtxServerError::NotFound), CachedModel::Present(cached) => { let catalog = cached.catalog(origin.query_start); @@ -213,7 +225,8 @@ async fn viewport( .map(Json) .map_err(|error| NvtxServerError::BadRequest(error.to_string())) } - } + }) + .await? } fn validate_filter_count(request: &NvtxViewportRequest) -> Result<(), NvtxServerError> { @@ -294,6 +307,16 @@ mod tests { ] } + #[tokio::test(flavor = "current_thread")] + async fn model_work_runs_off_the_async_executor() { + let executor_thread = std::thread::current().id(); + let model_thread = run_model_task(|| std::thread::current().id()) + .await + .unwrap(); + + assert_ne!(model_thread, executor_thread); + } + #[tokio::test] async fn model_and_query_relative_catalogs_are_cached_end_to_end() { let present = Uuid::from_u128(1); From 2a2beba6f910493b00f797dd2f1265c60d3d3a16 Mon Sep 17 00:00:00 2001 From: Pradeep Garigipati Date: Wed, 12 Aug 2026 14:36:29 +0530 Subject: [PATCH 3/6] fix(server): bound blocking telemetry work --- .../query_engine/server/src/analyzer_cache.rs | 18 +- domains/query_engine/server/src/ui.rs | 2 +- integrations/nvtx/server/src/lib.rs | 165 +++++++++++++----- 3 files changed, 139 insertions(+), 46 deletions(-) diff --git a/domains/query_engine/server/src/analyzer_cache.rs b/domains/query_engine/server/src/analyzer_cache.rs index 21f754aae..84b17952e 100644 --- a/domains/query_engine/server/src/analyzer_cache.rs +++ b/domains/query_engine/server/src/analyzer_cache.rs @@ -232,13 +232,19 @@ where Ok((self.lister)()?.engine_ids().collect()) } - pub(crate) fn contexts(&self, engine_id: Uuid) -> ServerResult { - let index = (self.lister)()?; - Ok(ui::EngineContexts { - engine_id, - context_ids: index.contexts_of(engine_id), - context_resources: index.context_resources_of(engine_id), + /// List an engine's contributing contexts without blocking the async executor. + pub(crate) async fn contexts(&self, engine_id: Uuid) -> ServerResult { + let lister = Arc::clone(&self.lister); + tokio::task::spawn_blocking(move || { + let index = lister()?; + Ok(ui::EngineContexts { + engine_id, + context_ids: index.contexts_of(engine_id), + context_resources: index.context_resources_of(engine_id), + }) }) + .await + .map_err(|error| ServerError::Cache(format!("blocking task panicked: {error}")))? } pub(crate) async fn list_with_metadata(&self) -> ServerResult> { diff --git a/domains/query_engine/server/src/ui.rs b/domains/query_engine/server/src/ui.rs index 63a0b8240..d113dce86 100644 --- a/domains/query_engine/server/src/ui.rs +++ b/domains/query_engine/server/src/ui.rs @@ -134,7 +134,7 @@ async fn engine_contexts( where A: UiAnalyzer + Send + Sync + 'static, { - let contexts = state.analyzers.contexts(engine_id).map_err(|error| { + let contexts = state.analyzers.contexts(engine_id).await.map_err(|error| { tracing::error!(%error, %engine_id, "engine context inventory failed"); crate::error::ServerError::Cache("engine context inventory could not be loaded".to_owned()) })?; diff --git a/integrations/nvtx/server/src/lib.rs b/integrations/nvtx/server/src/lib.rs index f36e716af..8e48526ca 100644 --- a/integrations/nvtx/server/src/lib.rs +++ b/integrations/nvtx/server/src/lib.rs @@ -21,12 +21,14 @@ use nvtx_ui::{NvtxCatalog, NvtxViewportRequest, NvtxViewportResponse}; use quent_events::{EntityEvent, Event}; use quent_io::filesystem::{self, Format}; use quent_io::{ImporterOptions, ImporterProvider}; +use tokio::sync::Semaphore; use uuid::Uuid; const MAX_BODY_BYTES: usize = 64 * 1024; const MAX_DOMAIN_FILTERS: usize = 256; const MAX_CATEGORY_FILTERS: usize = 4096; const MAX_CATALOG_ORIGINS: u64 = 32; +const MAX_CONCURRENT_MODEL_TASKS: usize = 4; /// A redacted importer failure. Details are logged server-side and are never /// copied into an HTTP response. @@ -34,6 +36,7 @@ const MAX_CATALOG_ORIGINS: u64 = 32; pub struct NvtxImporterError(String); impl NvtxImporterError { + /// Capture an importer error for server-side logging. pub fn new(error: impl fmt::Display) -> Self { Self(error.to_string()) } @@ -96,6 +99,7 @@ struct CachedNvtx { } impl CachedNvtx { + /// Pair a reconstructed model with its origin-specific catalog cache. fn new(model: NvtxModel) -> Self { Self { model, @@ -105,6 +109,7 @@ impl CachedNvtx { } } + /// Return the catalog whose relative times use `query_start` as their origin. fn catalog(&self, query_start: u64) -> Arc { self.catalogs.get_with(query_start, || { Arc::new(NvtxCatalog::from_model(&self.model, query_start)) @@ -112,13 +117,48 @@ impl CachedNvtx { } } +/// Applies backpressure before scheduling expensive NVTX work on Tokio's +/// blocking pool. +#[derive(Clone)] +struct NvtxTaskLimiter { + permits: Arc, +} + +impl NvtxTaskLimiter { + /// Create a limiter allowing at most `max_concurrency` model tasks. + fn new(max_concurrency: usize) -> Self { + Self { + permits: Arc::new(Semaphore::new(max_concurrency)), + } + } + + /// Wait for capacity, then retain that capacity until the blocking task exits. + async fn run(&self, task: impl FnOnce() -> T + Send + 'static) -> Result + where + T: Send + 'static, + { + let permit = Arc::clone(&self.permits) + .acquire_owned() + .await + .map_err(|error| NvtxServerError::Internal(error.to_string()))?; + tokio::task::spawn_blocking(move || { + let _permit = permit; + task() + }) + .await + .map_err(|error| NvtxServerError::Internal(error.to_string())) + } +} + #[derive(Clone)] struct NvtxModelCache { models: AsyncCache>, importer: Arc, + tasks: NvtxTaskLimiter, } impl NvtxModelCache { + /// Create the context model cache and its shared blocking-work limiter. fn new(importer: Box) -> Self { Self { models: AsyncCache::builder() @@ -126,31 +166,45 @@ impl NvtxModelCache { .time_to_idle(Duration::from_hours(24)) .build(), importer: Arc::from(importer), + tasks: NvtxTaskLimiter::new(MAX_CONCURRENT_MODEL_TASKS), } } + /// Load and reconstruct one context, coalescing concurrent misses by ID. async fn get(&self, context_id: Uuid) -> Result, NvtxServerError> { let importer = Arc::clone(&self.importer); + let tasks = self.tasks.clone(); self.models .entry(context_id) .or_try_insert_with(async move { - tokio::task::spawn_blocking(move || match importer(context_id) { - Ok(Some(events)) => { - let model = NvtxModelBuilder::build(events); - Ok(Arc::new(CachedModel::Present(Box::new(CachedNvtx::new( - model, - ))))) - } - Ok(None) => Ok(Arc::new(CachedModel::Absent)), - Err(error) => Err(NvtxServerError::Internal(error.to_string())), - }) - .await - .map_err(|error| NvtxServerError::Internal(error.to_string()))? + tasks + .run(move || match importer(context_id) { + Ok(Some(events)) => { + let model = NvtxModelBuilder::build(events); + Ok(Arc::new(CachedModel::Present(Box::new(CachedNvtx::new( + model, + ))))) + } + Ok(None) => Ok(Arc::new(CachedModel::Absent)), + Err(error) => Err(NvtxServerError::Internal(error.to_string())), + }) + .await? }) .await .map(|entry| entry.into_value()) .map_err(|error: Arc| (*error).clone()) } + + /// Run catalog or viewport conversion under the same limit as model loading. + async fn run_model_task( + &self, + task: impl FnOnce() -> T + Send + 'static, + ) -> Result + where + T: Send + 'static, + { + self.tasks.run(task).await + } } #[derive(Clone)] @@ -187,28 +241,23 @@ impl IntoResponse for NvtxServerError { } } -async fn run_model_task(task: impl FnOnce() -> T + Send + 'static) -> Result -where - T: Send + 'static, -{ - tokio::task::spawn_blocking(task) - .await - .map_err(|error| NvtxServerError::Internal(error.to_string())) -} - +/// Return stable metadata for a context relative to one query origin. async fn catalog( State(state): State, AxumPath(context_id): AxumPath, Query(origin): Query, ) -> Result, NvtxServerError> { let cached_model = state.cache.get(context_id).await?; - run_model_task(move || match cached_model.as_ref() { - CachedModel::Absent => Err(NvtxServerError::NotFound), - CachedModel::Present(cached) => Ok(Json((*cached.catalog(origin.query_start)).clone())), - }) - .await? + state + .cache + .run_model_task(move || match cached_model.as_ref() { + CachedModel::Absent => Err(NvtxServerError::NotFound), + CachedModel::Present(cached) => Ok(Json((*cached.catalog(origin.query_start)).clone())), + }) + .await? } +/// Build lanes and statistics for one relative-time viewport. async fn viewport( State(state): State, AxumPath(context_id): AxumPath, @@ -217,18 +266,21 @@ async fn viewport( ) -> Result, NvtxServerError> { validate_filter_count(&request)?; let cached_model = state.cache.get(context_id).await?; - run_model_task(move || match cached_model.as_ref() { - CachedModel::Absent => Err(NvtxServerError::NotFound), - CachedModel::Present(cached) => { - let catalog = cached.catalog(origin.query_start); - NvtxViewportResponse::from_model_with_catalog(&cached.model, &catalog, request) - .map(Json) - .map_err(|error| NvtxServerError::BadRequest(error.to_string())) - } - }) - .await? + state + .cache + .run_model_task(move || match cached_model.as_ref() { + CachedModel::Absent => Err(NvtxServerError::NotFound), + CachedModel::Present(cached) => { + let catalog = cached.catalog(origin.query_start); + NvtxViewportResponse::from_model_with_catalog(&cached.model, &catalog, request) + .map(Json) + .map_err(|error| NvtxServerError::BadRequest(error.to_string())) + } + }) + .await? } +/// Reject requests whose selector lists could cause disproportionate work. fn validate_filter_count(request: &NvtxViewportRequest) -> Result<(), NvtxServerError> { if request.selections.len() > MAX_DOMAIN_FILTERS { return Err(NvtxServerError::BadRequest( @@ -309,14 +361,49 @@ mod tests { #[tokio::test(flavor = "current_thread")] async fn model_work_runs_off_the_async_executor() { + let limiter = NvtxTaskLimiter::new(1); let executor_thread = std::thread::current().id(); - let model_thread = run_model_task(|| std::thread::current().id()) - .await - .unwrap(); + let model_thread = limiter.run(|| std::thread::current().id()).await.unwrap(); assert_ne!(model_thread, executor_thread); } + #[tokio::test(flavor = "current_thread")] + async fn model_work_waits_for_capacity_before_entering_the_blocking_pool() { + let limiter = NvtxTaskLimiter::new(1); + let (first_started_tx, first_started_rx) = tokio::sync::oneshot::channel(); + let (release_first_tx, release_first_rx) = std::sync::mpsc::channel(); + let first_limiter = limiter.clone(); + let first = tokio::spawn(async move { + first_limiter + .run(move || { + first_started_tx.send(()).unwrap(); + release_first_rx.recv().unwrap(); + }) + .await + .unwrap(); + }); + first_started_rx.await.unwrap(); + + let (second_started_tx, mut second_started_rx) = tokio::sync::oneshot::channel(); + let second = tokio::spawn(async move { + limiter + .run(move || second_started_tx.send(()).unwrap()) + .await + .unwrap(); + }); + tokio::task::yield_now().await; + assert!(matches!( + second_started_rx.try_recv(), + Err(tokio::sync::oneshot::error::TryRecvError::Empty) + )); + + release_first_tx.send(()).unwrap(); + first.await.unwrap(); + second_started_rx.await.unwrap(); + second.await.unwrap(); + } + #[tokio::test] async fn model_and_query_relative_catalogs_are_cached_end_to_end() { let present = Uuid::from_u128(1); From 169183b9be66ec002258688c62f5be31c40d95a8 Mon Sep 17 00:00:00 2001 From: Pradeep Garigipati Date: Wed, 12 Aug 2026 15:04:41 +0530 Subject: [PATCH 4/6] refactor(server): simplify context routes --- .../query_engine/server/src/analyzer_cache.rs | 9 +- domains/query_engine/ui/src/lib.rs | 3 - integrations/nvtx/server/src/lib.rs | 143 +++++++----------- 3 files changed, 56 insertions(+), 99 deletions(-) diff --git a/domains/query_engine/server/src/analyzer_cache.rs b/domains/query_engine/server/src/analyzer_cache.rs index 84b17952e..b97c74b75 100644 --- a/domains/query_engine/server/src/analyzer_cache.rs +++ b/domains/query_engine/server/src/analyzer_cache.rs @@ -42,9 +42,7 @@ pub struct EngineIndex { contexts: HashMap>, /// Engine id to its workers and the context each was found in. workers: HashMap>, - /// Engine id to context id to the resource-group entities observed in that - /// context. This lets context-wide integrations sit beside the resources - /// owned by the same process without claiming query correlation. + /// Resource-group entities observed in each context, by engine ID. context_resources: HashMap>>, } @@ -57,7 +55,6 @@ impl EngineIndex { } fn add_worker(&mut self, engine_id: Uuid, worker_id: Uuid, context_id: Uuid) { - self.attribute_context(engine_id, context_id); self.attribute_resource(engine_id, context_id, worker_id); self.workers .entry(engine_id) @@ -66,6 +63,7 @@ impl EngineIndex { } fn attribute_resource(&mut self, engine_id: Uuid, context_id: Uuid, resource_id: Uuid) { + self.attribute_context(engine_id, context_id); self.context_resources .entry(engine_id) .or_default() @@ -145,7 +143,6 @@ pub fn index_query_engines(output_dir: &Path) -> ServerResult { for event in importer { let event = event?; if seen.insert(event.id) { - index.attribute_context(event.id, context_id); index.attribute_resource(event.id, context_id, event.id); } } @@ -239,7 +236,6 @@ where let index = lister()?; Ok(ui::EngineContexts { engine_id, - context_ids: index.contexts_of(engine_id), context_resources: index.context_resources_of(engine_id), }) }) @@ -312,7 +308,6 @@ mod tests { let worker_context = Uuid::from_u128(3); let worker_id = Uuid::from_u128(4); let mut index = EngineIndex::default(); - index.attribute_context(engine_id, engine_context); index.attribute_resource(engine_id, engine_context, engine_id); index.add_worker(engine_id, worker_id, worker_context); diff --git a/domains/query_engine/ui/src/lib.rs b/domains/query_engine/ui/src/lib.rs index bb04f323d..6657accdc 100644 --- a/domains/query_engine/ui/src/lib.rs +++ b/domains/query_engine/ui/src/lib.rs @@ -26,10 +26,7 @@ use uuid::Uuid; #[derive(TS, Debug, Clone, PartialEq, Eq, Serialize, Deserialize)] pub struct EngineContexts { pub engine_id: Uuid, - pub context_ids: Vec, /// Resource-group entities observed in each context, keyed by context ID. - /// Engine IDs identify engine-owned contexts and worker IDs identify the - /// process-local worker beneath which context-wide integrations belong. pub context_resources: BTreeMap>, } diff --git a/integrations/nvtx/server/src/lib.rs b/integrations/nvtx/server/src/lib.rs index 8e48526ca..1cfd10a54 100644 --- a/integrations/nvtx/server/src/lib.rs +++ b/integrations/nvtx/server/src/lib.rs @@ -36,7 +36,6 @@ const MAX_CONCURRENT_MODEL_TASKS: usize = 4; pub struct NvtxImporterError(String); impl NvtxImporterError { - /// Capture an importer error for server-side logging. pub fn new(error: impl fmt::Display) -> Self { Self(error.to_string()) } @@ -99,7 +98,6 @@ struct CachedNvtx { } impl CachedNvtx { - /// Pair a reconstructed model with its origin-specific catalog cache. fn new(model: NvtxModel) -> Self { Self { model, @@ -125,7 +123,6 @@ struct NvtxTaskLimiter { } impl NvtxTaskLimiter { - /// Create a limiter allowing at most `max_concurrency` model tasks. fn new(max_concurrency: usize) -> Self { Self { permits: Arc::new(Semaphore::new(max_concurrency)), @@ -158,7 +155,6 @@ struct NvtxModelCache { } impl NvtxModelCache { - /// Create the context model cache and its shared blocking-work limiter. fn new(importer: Box) -> Self { Self { models: AsyncCache::builder() @@ -194,22 +190,6 @@ impl NvtxModelCache { .map(|entry| entry.into_value()) .map_err(|error: Arc| (*error).clone()) } - - /// Run catalog or viewport conversion under the same limit as model loading. - async fn run_model_task( - &self, - task: impl FnOnce() -> T + Send + 'static, - ) -> Result - where - T: Send + 'static, - { - self.tasks.run(task).await - } -} - -#[derive(Clone)] -struct NvtxState { - cache: NvtxModelCache, } #[derive(Debug, Clone, Copy, serde::Deserialize)] @@ -243,14 +223,14 @@ impl IntoResponse for NvtxServerError { /// Return stable metadata for a context relative to one query origin. async fn catalog( - State(state): State, + State(cache): State, AxumPath(context_id): AxumPath, Query(origin): Query, ) -> Result, NvtxServerError> { - let cached_model = state.cache.get(context_id).await?; - state - .cache - .run_model_task(move || match cached_model.as_ref() { + let cached_model = cache.get(context_id).await?; + cache + .tasks + .run(move || match cached_model.as_ref() { CachedModel::Absent => Err(NvtxServerError::NotFound), CachedModel::Present(cached) => Ok(Json((*cached.catalog(origin.query_start)).clone())), }) @@ -259,16 +239,16 @@ async fn catalog( /// Build lanes and statistics for one relative-time viewport. async fn viewport( - State(state): State, + State(cache): State, AxumPath(context_id): AxumPath, Query(origin): Query, Json(request): Json, ) -> Result, NvtxServerError> { validate_filter_count(&request)?; - let cached_model = state.cache.get(context_id).await?; - state - .cache - .run_model_task(move || match cached_model.as_ref() { + let cached_model = cache.get(context_id).await?; + cache + .tasks + .run(move || match cached_model.as_ref() { CachedModel::Absent => Err(NvtxServerError::NotFound), CachedModel::Present(cached) => { let catalog = cached.catalog(origin.query_start); @@ -302,24 +282,21 @@ fn validate_filter_count(request: &NvtxViewportRequest) -> Result<(), NvtxServer Ok(()) } -/// Context-keyed NVTX API routes, ready to merge into the host service before -/// its common CORS and embedded-UI fallback layers. +/// Context-keyed NVTX API routes. /// /// Catalog and viewport requests require a `query_start` query parameter in /// Unix nanoseconds. Public viewport times are seconds relative to that origin. pub fn routes(importer: Box) -> Router { - let state = NvtxState { - cache: NvtxModelCache::new(importer), - }; Router::new() .route("/api/nvtx/contexts/{context_id}/catalog", get(catalog)) .route("/api/nvtx/contexts/{context_id}/viewport", post(viewport)) .layer(DefaultBodyLimit::max(MAX_BODY_BYTES)) - .with_state(state) + .with_state(NvtxModelCache::new(importer)) } #[cfg(test)] mod tests { + use std::fmt::Display; use std::sync::atomic::{AtomicUsize, Ordering}; use axum::body::{Body, to_bytes}; @@ -333,6 +310,14 @@ mod tests { const QUERY_START: u64 = 2_000_000_000; const RANGE_END: u64 = 3_000_000_000; + fn catalog_uri(context_id: impl Display, query_start: u64) -> String { + format!("/api/nvtx/contexts/{context_id}/catalog?query_start={query_start}") + } + + fn viewport_uri(context_id: impl Display) -> String { + format!("/api/nvtx/contexts/{context_id}/viewport?query_start={QUERY_START}") + } + fn range_events(context_id: Uuid) -> Vec> { let attributes = NvtxEventAttributes { message: Some(NvtxMessage::String("work".to_owned())), @@ -417,11 +402,9 @@ mod tests { let response = app .clone() .oneshot( - Request::get(format!( - "/api/nvtx/contexts/{present}/catalog?query_start={QUERY_START}" - )) - .body(Body::empty()) - .unwrap(), + Request::get(catalog_uri(present, QUERY_START)) + .body(Body::empty()) + .unwrap(), ) .await .unwrap(); @@ -436,11 +419,9 @@ mod tests { let alternate = app .clone() .oneshot( - Request::get(format!( - "/api/nvtx/contexts/{present}/catalog?query_start={alternate_origin}" - )) - .body(Body::empty()) - .unwrap(), + Request::get(catalog_uri(present, alternate_origin)) + .body(Body::empty()) + .unwrap(), ) .await .unwrap(); @@ -462,12 +443,10 @@ mod tests { }; let response = app .oneshot( - Request::post(format!( - "/api/nvtx/contexts/{present}/viewport?query_start={QUERY_START}" - )) - .header("content-type", "application/json") - .body(Body::from(serde_json::to_vec(&request).unwrap())) - .unwrap(), + Request::post(viewport_uri(present)) + .header("content-type", "application/json") + .body(Body::from(serde_json::to_vec(&request).unwrap())) + .unwrap(), ) .await .unwrap(); @@ -493,11 +472,9 @@ mod tests { let empty_response = app .clone() .oneshot( - Request::get(format!( - "/api/nvtx/contexts/{empty}/catalog?query_start={QUERY_START}" - )) - .body(Body::empty()) - .unwrap(), + Request::get(catalog_uri(empty, QUERY_START)) + .body(Body::empty()) + .unwrap(), ) .await .unwrap(); @@ -505,11 +482,9 @@ mod tests { let absent_response = app .oneshot( - Request::get(format!( - "/api/nvtx/contexts/{absent}/catalog?query_start={QUERY_START}" - )) - .body(Body::empty()) - .unwrap(), + Request::get(catalog_uri(absent, QUERY_START)) + .body(Body::empty()) + .unwrap(), ) .await .unwrap(); @@ -550,12 +525,10 @@ mod tests { }; let response = app .oneshot( - Request::post(format!( - "/api/nvtx/contexts/{present}/viewport?query_start={QUERY_START}" - )) - .header("content-type", "application/json") - .body(Body::from(serde_json::to_vec(&request).unwrap())) - .unwrap(), + Request::post(viewport_uri(present)) + .header("content-type", "application/json") + .body(Body::from(serde_json::to_vec(&request).unwrap())) + .unwrap(), ) .await .unwrap(); @@ -572,11 +545,9 @@ mod tests { let invalid_uuid = app .clone() .oneshot( - Request::get(format!( - "/api/nvtx/contexts/not-a-uuid/catalog?query_start={QUERY_START}" - )) - .body(Body::empty()) - .unwrap(), + Request::get(catalog_uri("not-a-uuid", QUERY_START)) + .body(Body::empty()) + .unwrap(), ) .await .unwrap(); @@ -595,12 +566,10 @@ mod tests { let oversized = app .oneshot( - Request::post(format!( - "/api/nvtx/contexts/{present}/viewport?query_start={QUERY_START}" - )) - .header("content-type", "application/json") - .body(Body::from(vec![b' '; MAX_BODY_BYTES + 1])) - .unwrap(), + Request::post(viewport_uri(present)) + .header("content-type", "application/json") + .body(Body::from(vec![b' '; MAX_BODY_BYTES + 1])) + .unwrap(), ) .await .unwrap(); @@ -624,11 +593,9 @@ mod tests { let failed = app .clone() .oneshot( - Request::get(format!( - "/api/nvtx/contexts/{failing}/catalog?query_start={QUERY_START}" - )) - .body(Body::empty()) - .unwrap(), + Request::get(catalog_uri(failing, QUERY_START)) + .body(Body::empty()) + .unwrap(), ) .await .unwrap(); @@ -638,11 +605,9 @@ mod tests { let healthy = app .oneshot( - Request::get(format!( - "/api/nvtx/contexts/{present}/catalog?query_start={QUERY_START}" - )) - .body(Body::empty()) - .unwrap(), + Request::get(catalog_uri(present, QUERY_START)) + .body(Body::empty()) + .unwrap(), ) .await .unwrap(); From 583d6bf0f4aa33fe2b8abd349f41974b12d390c4 Mon Sep 17 00:00:00 2001 From: Pradeep Garigipati Date: Thu, 13 Aug 2026 14:53:59 +0530 Subject: [PATCH 5/6] fix(io): reject mixed context formats --- crates/io/src/filesystem/mod.rs | 53 +++++++++++++++++++++++++++++---- 1 file changed, 48 insertions(+), 5 deletions(-) diff --git a/crates/io/src/filesystem/mod.rs b/crates/io/src/filesystem/mod.rs index bf1beb844..0ddba0705 100644 --- a/crates/io/src/filesystem/mod.rs +++ b/crates/io/src/filesystem/mod.rs @@ -31,10 +31,10 @@ impl TryFrom<&str> for Format { } impl Format { - /// Detect the format of a context directory from the first recognized - /// `*.` event stream in any of its per-entity subdirectories. Returns - /// `None` if no readable stream with a known extension is present. + /// Detect the common format of a context's event streams. Returns `None` if + /// no recognized stream is present or streams use different formats. pub fn detect(context_dir: &std::path::Path) -> Option { + let mut detected = None; for entry in std::fs::read_dir(context_dir).ok()?.flatten() { if !entry.file_type().map(|t| t.is_dir()).unwrap_or(false) { continue; @@ -48,10 +48,53 @@ impl Format { .and_then(|ext| ext.to_str()) .and_then(|ext| Self::try_from(ext).ok()) { - return Some(format); + match detected { + Some(existing) if existing != format => return None, + None => detected = Some(format), + _ => {} + } } } } - None + detected + } +} + +#[cfg(all(test, feature = "ndjson"))] +mod tests { + use std::path::PathBuf; + + use super::*; + use uuid::Uuid; + + fn context_with_streams(streams: &[(&str, &str)]) -> PathBuf { + let context = std::env::temp_dir().join(format!("quent-format-{}", Uuid::now_v7())); + for &(entity, extension) in streams { + let stream_dir = context.join(entity); + std::fs::create_dir_all(&stream_dir).unwrap(); + std::fs::write(stream_dir.join(format!("events.{extension}")), []).unwrap(); + } + context + } + + #[test] + fn detects_one_context_wide_format() { + let context = + context_with_streams(&[("EngineEvent", "ndjson"), ("NvtxEventEntity", "ndjson")]); + let detected = Format::detect(&context); + std::fs::remove_dir_all(context).unwrap(); + + assert_eq!(detected, Some(Format::Ndjson)); + } + + #[test] + #[cfg(feature = "msgpack")] + fn rejects_mixed_context_formats() { + let context = + context_with_streams(&[("EngineEvent", "ndjson"), ("NvtxEventEntity", "msgpack")]); + let detected = Format::detect(&context); + std::fs::remove_dir_all(context).unwrap(); + + assert_eq!(detected, None); } } From a7bb36b6fea71f4fc4d6e09c6c54110c4a09975b Mon Sep 17 00:00:00 2001 From: Pradeep Garigipati Date: Thu, 13 Aug 2026 15:09:38 +0530 Subject: [PATCH 6/6] fix(nvtx): retry unavailable streams --- integrations/nvtx/server/src/lib.rs | 85 +++++++++++++++++++---------- 1 file changed, 57 insertions(+), 28 deletions(-) diff --git a/integrations/nvtx/server/src/lib.rs b/integrations/nvtx/server/src/lib.rs index 1cfd10a54..6da5a5b9a 100644 --- a/integrations/nvtx/server/src/lib.rs +++ b/integrations/nvtx/server/src/lib.rs @@ -51,8 +51,8 @@ impl Error for NvtxImporterError {} pub type NvtxImporterResult = Result; -/// Loads only one context's NVTX entity stream. `None` is a cacheable absence; -/// `Some(Vec::new())` is a present but empty stream. +/// Loads only one context's NVTX entity stream. `None` means the stream is not +/// available; `Some(Vec::new())` is a present but empty stream. pub type NvtxImporterFn = dyn Fn(Uuid) -> NvtxImporterResult>>> + Send + Sync; @@ -87,11 +87,6 @@ pub fn import_context_events( .map_err(NvtxImporterError::new) } -enum CachedModel { - Absent, - Present(Box), -} - struct CachedNvtx { model: NvtxModel, catalogs: SyncCache>, @@ -149,7 +144,7 @@ impl NvtxTaskLimiter { #[derive(Clone)] struct NvtxModelCache { - models: AsyncCache>, + models: AsyncCache>, importer: Arc, tasks: NvtxTaskLimiter, } @@ -167,7 +162,7 @@ impl NvtxModelCache { } /// Load and reconstruct one context, coalescing concurrent misses by ID. - async fn get(&self, context_id: Uuid) -> Result, NvtxServerError> { + async fn get(&self, context_id: Uuid) -> Result, NvtxServerError> { let importer = Arc::clone(&self.importer); let tasks = self.tasks.clone(); self.models @@ -177,11 +172,9 @@ impl NvtxModelCache { .run(move || match importer(context_id) { Ok(Some(events)) => { let model = NvtxModelBuilder::build(events); - Ok(Arc::new(CachedModel::Present(Box::new(CachedNvtx::new( - model, - ))))) + Ok(Arc::new(CachedNvtx::new(model))) } - Ok(None) => Ok(Arc::new(CachedModel::Absent)), + Ok(None) => Err(NvtxServerError::NotFound), Err(error) => Err(NvtxServerError::Internal(error.to_string())), }) .await? @@ -227,13 +220,10 @@ async fn catalog( AxumPath(context_id): AxumPath, Query(origin): Query, ) -> Result, NvtxServerError> { - let cached_model = cache.get(context_id).await?; + let cached = cache.get(context_id).await?; cache .tasks - .run(move || match cached_model.as_ref() { - CachedModel::Absent => Err(NvtxServerError::NotFound), - CachedModel::Present(cached) => Ok(Json((*cached.catalog(origin.query_start)).clone())), - }) + .run(move || Ok(Json((*cached.catalog(origin.query_start)).clone()))) .await? } @@ -245,17 +235,14 @@ async fn viewport( Json(request): Json, ) -> Result, NvtxServerError> { validate_filter_count(&request)?; - let cached_model = cache.get(context_id).await?; + let cached = cache.get(context_id).await?; cache .tasks - .run(move || match cached_model.as_ref() { - CachedModel::Absent => Err(NvtxServerError::NotFound), - CachedModel::Present(cached) => { - let catalog = cached.catalog(origin.query_start); - NvtxViewportResponse::from_model_with_catalog(&cached.model, &catalog, request) - .map(Json) - .map_err(|error| NvtxServerError::BadRequest(error.to_string())) - } + .run(move || { + let catalog = cached.catalog(origin.query_start); + NvtxViewportResponse::from_model_with_catalog(&cached.model, &catalog, request) + .map(Json) + .map_err(|error| NvtxServerError::BadRequest(error.to_string())) }) .await? } @@ -297,7 +284,7 @@ pub fn routes(importer: Box) -> Router { #[cfg(test)] mod tests { use std::fmt::Display; - use std::sync::atomic::{AtomicUsize, Ordering}; + use std::sync::atomic::{AtomicBool, AtomicUsize, Ordering}; use axum::body::{Body, to_bytes}; use axum::http::Request; @@ -491,6 +478,48 @@ mod tests { assert_eq!(absent_response.status(), StatusCode::NOT_FOUND); } + #[tokio::test] + async fn absent_stream_is_retried_and_cached_after_it_becomes_available() { + let context_id = Uuid::from_u128(9); + let available = Arc::new(AtomicBool::new(false)); + let loads = Arc::new(AtomicUsize::new(0)); + let importer_available = Arc::clone(&available); + let importer_loads = Arc::clone(&loads); + let app = routes(Box::new(move |requested_context_id| { + importer_loads.fetch_add(1, Ordering::SeqCst); + Ok( + (requested_context_id == context_id && importer_available.load(Ordering::SeqCst)) + .then(|| range_events(requested_context_id)), + ) + })); + + let missing = app + .clone() + .oneshot( + Request::get(catalog_uri(context_id, QUERY_START)) + .body(Body::empty()) + .unwrap(), + ) + .await + .unwrap(); + assert_eq!(missing.status(), StatusCode::NOT_FOUND); + + available.store(true, Ordering::SeqCst); + for _ in 0..2 { + let present = app + .clone() + .oneshot( + Request::get(catalog_uri(context_id, QUERY_START)) + .body(Body::empty()) + .unwrap(), + ) + .await + .unwrap(); + assert_eq!(present.status(), StatusCode::OK); + } + assert_eq!(loads.load(Ordering::SeqCst), 2); + } + #[test] fn filesystem_importer_recognizes_an_empty_present_stream() { let root = tempdir().unwrap();