kaizen/visualization/
build.rs

1// SPDX-License-Identifier: AGPL-3.0-or-later
2
3use super::activity::activity;
4use super::types::*;
5use crate::core::event::{SessionRecord, SessionStatus};
6use crate::store::Store;
7use anyhow::{Result, ensure};
8use serde::{Deserialize, Serialize};
9
10const ACTIVE_TTL_MS: u64 = 5 * 60_000;
11const ORPHAN_TTL_MS: u64 = 30 * 60_000;
12
13#[derive(Clone, Copy, Debug, Eq, PartialEq, Serialize, Deserialize)]
14pub struct VisualizationLimits {
15    /// Maximum latest sessions materialized for summaries.
16    pub sessions: usize,
17    /// Maximum latest events materialized for selected detail.
18    pub selected_events: usize,
19    /// Maximum spans materialized for selected detail.
20    pub selected_spans: usize,
21    /// Maximum files materialized for selected detail.
22    pub selected_files: usize,
23}
24
25#[derive(Clone, Debug, Serialize, Deserialize)]
26pub struct VisualizationQuery {
27    pub workspace: String,
28    pub selected_session_id: Option<String>,
29    pub now_ms: u64,
30    /// Compute heatmap bins only for surfaces that render them.
31    pub include_activity: bool,
32    /// Fall back to latest session when requested selection is absent or invalid.
33    pub select_latest: bool,
34    pub limits: VisualizationLimits,
35}
36
37#[derive(Clone, Copy, Debug, Eq, PartialEq)]
38pub(crate) struct MaterializedRows {
39    pub(crate) sessions: usize,
40    pub(crate) selected_events: usize,
41    pub(crate) selected_spans: usize,
42    pub(crate) selected_files: usize,
43}
44
45pub(crate) struct BuiltReport {
46    pub(crate) report: VisualizationReport,
47    pub(crate) materialized: MaterializedRows,
48}
49
50pub fn build_report(store: &Store, query: VisualizationQuery) -> Result<VisualizationReport> {
51    Ok(build_report_observed(store, query)?.report)
52}
53
54pub(crate) fn build_report_observed(
55    store: &Store,
56    query: VisualizationQuery,
57) -> Result<BuiltReport> {
58    validate(&query.limits)?;
59    let (totals, quality) = store.visualization_totals(&query.workspace)?;
60    let sessions =
61        store.visualization_sessions(&query.workspace, query.limits.sessions, query.now_ms)?;
62    let selected = selected_detail(store, &query, sessions.first())?;
63    let activity = activity_report(store, &query)?;
64    let materialized = counts(&sessions, &selected);
65    Ok(BuiltReport {
66        report: report(query, totals, quality, sessions, selected, activity),
67        materialized,
68    })
69}
70
71fn validate(limits: &VisualizationLimits) -> Result<()> {
72    ensure_positive(limits.sessions, "session")?;
73    ensure_positive(limits.selected_events, "event")?;
74    ensure_positive(limits.selected_spans, "span")?;
75    ensure_positive(limits.selected_files, "file")?;
76    Ok(())
77}
78
79fn ensure_positive(limit: usize, kind: &str) -> Result<()> {
80    ensure!(limit > 0, "visualization {kind} limit must be positive");
81    Ok(())
82}
83
84fn activity_report(store: &Store, query: &VisualizationQuery) -> Result<ActivityReport> {
85    if query.include_activity {
86        activity(store, &query.workspace, query.now_ms)
87    } else {
88        Ok(Default::default())
89    }
90}
91
92fn selected_detail(
93    store: &Store,
94    query: &VisualizationQuery,
95    latest: Option<&TraceSummary>,
96) -> Result<Option<TraceDetail>> {
97    let Some(session) = selected_session(store, query, latest)? else {
98        return Ok(None);
99    };
100    let id = session.id.clone();
101    Ok(Some(TraceDetail {
102        session,
103        events: store.list_latest_events_for_session(&id, query.limits.selected_events)?,
104        spans: store.limited_session_span_tree(&id, query.limits.selected_spans)?,
105        files: store.limited_files_for_session(&id, query.limits.selected_files)?,
106    }))
107}
108
109fn selected_session(
110    store: &Store,
111    query: &VisualizationQuery,
112    latest: Option<&TraceSummary>,
113) -> Result<Option<SessionRecord>> {
114    if let Some(session) = requested_session(store, query)? {
115        return Ok(Some(session));
116    }
117    if !query.select_latest {
118        return Ok(None);
119    }
120    latest
121        .map(|summary| store.get_session(&summary.id))
122        .transpose()
123        .map(Option::flatten)
124}
125
126fn requested_session(store: &Store, query: &VisualizationQuery) -> Result<Option<SessionRecord>> {
127    let Some(id) = query.selected_session_id.as_deref() else {
128        return Ok(None);
129    };
130    Ok(store
131        .get_session(id)?
132        .filter(|session| session.workspace == query.workspace))
133}
134
135fn counts(sessions: &[TraceSummary], selected: &Option<TraceDetail>) -> MaterializedRows {
136    MaterializedRows {
137        sessions: sessions.len(),
138        selected_events: selected.as_ref().map_or(0, |detail| detail.events.len()),
139        selected_spans: selected
140            .as_ref()
141            .map_or(0, |detail| span_count(&detail.spans)),
142        selected_files: selected.as_ref().map_or(0, |detail| detail.files.len()),
143    }
144}
145
146fn span_count(spans: &[crate::store::SpanNode]) -> usize {
147    spans
148        .iter()
149        .map(|node| 1 + span_count(&node.children))
150        .sum()
151}
152
153fn report(
154    query: VisualizationQuery,
155    totals: VisualizationTotals,
156    quality: DataQuality,
157    sessions: Vec<TraceSummary>,
158    selected: Option<TraceDetail>,
159    activity: ActivityReport,
160) -> VisualizationReport {
161    VisualizationReport {
162        generated_at_ms: query.now_ms,
163        workspace: query.workspace,
164        totals,
165        activity,
166        sessions,
167        selected,
168        quality,
169    }
170}
171
172pub(crate) fn derive_status(
173    session: &SessionRecord,
174    last_event_ms: Option<u64>,
175    error_count: u64,
176    now_ms: u64,
177) -> (DerivedStatus, String) {
178    if error_count > 0 {
179        return (DerivedStatus::Errored, "error event".into());
180    }
181    if session.status == SessionStatus::Done || session.ended_at_ms.is_some() {
182        return (DerivedStatus::Done, "session ended".into());
183    }
184    match last_event_ms {
185        Some(ts) if now_ms.saturating_sub(ts) <= ACTIVE_TTL_MS => {
186            (DerivedStatus::Active, "recent event".into())
187        }
188        Some(ts) if now_ms.saturating_sub(ts) >= ORPHAN_TTL_MS => {
189            (DerivedStatus::Orphaned, "stale open session".into())
190        }
191        Some(_) => (DerivedStatus::Idle, "no recent event".into()),
192        None => (DerivedStatus::Idle, "no events".into()),
193    }
194}
kaizen/visualization/build.rs

kaizen/visualization/
build.rs
