A reactive notebook for Python — run reproducible experiments, query with SQL, execute as a script, deploy as an app, and version with git. Stored as pure Python. All in a modern, AI-native editor.
Python artificial-intelligencedagdata-sciencedata-visualizationdataflowdeveloper-toolsmachine-learningnotebookspipelinepythonreactivesqlweb-app
/* Copyright 2026 Marimo. All rights reserved. */
import { atom, useAtomValue, useSetAtom } from "jotai";
import {
ActivityIcon,
ChevronDown,
ChevronRight,
CircleCheck,
CircleEllipsis,
CirclePlayIcon,
CircleX,
} from "lucide-react";
import React, { type JSX, Suspense, useEffect, useRef, useState } from "react";
import { Panel, PanelGroup, PanelResizeHandle } from "react-resizable-panels";
import { useVegaEmbed } from "react-vega";
import useResizeObserver from "use-resize-observer";
import { compile } from "vega-lite";
import { Tooltip } from "@/components/ui/tooltip";
import { useCellIds } from "@/core/cells/cells";
import type { CellId } from "@/core/cells/ids";
import { formatLogTimestamp } from "@/core/cells/logs";
import {
type CellRun,
type Run,
type RunId,
runsAtom,
useRunsActions,
} from "@/core/cells/runs";
import { type ResolvedTheme, useTheme } from "@/theme/useTheme";
import { cn } from "@/utils/cn";
import { formatElapsedTime } from "@/utils/time";
import { ClearButton } from "../buttons/clear-button";
import type { SignalListener } from "../charts/types";
import { ElapsedTime } from "../editor/cell/CellStatus";
import { PanelEmptyState } from "../editor/chrome/panels/empty-state";
import { usePanelSection } from "../editor/chrome/panels/panel-context";
import { CellLink } from "../editor/links/cell-link";
import {
type ChartPosition,
type ChartValues,
createGanttBaseSpec,
VEGA_HOVER_SIGNAL,
} from "./tracing-spec";
import { formatChartTime } from "./utils";
const expandedRunsAtom = atom<Map<RunId, boolean>>(new Map<RunId, boolean>());
export const Tracing: React.FC = () => {
const { runIds: newestToOldestRunIds, runMap } = useAtomValue(runsAtom);
const expandedRuns = useAtomValue(expandedRunsAtom);
const { clearRuns } = useRunsActions();
const { theme } = useTheme();
const [chartPosition, setChartPosition] = useState<ChartPosition>("above");
const chartPositionId = React.useId();
const panelSection = usePanelSection();
const toggleChartPosition = () => {
if (chartPosition === "above") {
setChartPosition("sideBySide");
} else {
setChartPosition("above");
}
};
if (newestToOldestRunIds.length === 0) {
return (
<PanelEmptyState
title="No traces"
description={<span>Cells that have ran will appear here.</span>}
icon={<ActivityIcon />}
/>
);
}
const tracingComponent = (
<div className="py-1 px-2 overflow-y-scroll h-full">
<div className="flex flex-row justify-start gap-3">
<div className="flex flex-row gap-1 items-center">
<label htmlFor={chartPositionId} className="text-xs">
Inline chart
</label>
<input
type="checkbox"
id={chartPositionId}
name="chartPosition"
data-testid="chartPosition"
onClick={toggleChartPosition}
defaultChecked={chartPosition === "sideBySide"}
className="h-3 cursor-pointer"
/>
</div>
<ClearButton dataTestId="clear-traces-button" onClick={clearRuns} />
</div>
<div className="flex flex-col gap-3">
{newestToOldestRunIds.map((runId: RunId, index: number) => {
const run = runMap.get(runId);
if (run) {
return (
<TraceBlock
key={run.runId}
run={run}
isExpanded={expandedRuns.get(run.runId)}
isMostRecentRun={index === 0}
chartPosition={chartPosition}
theme={theme}
/>
);
}
return null;
})}
</div>
</div>
);
if (panelSection === "sidebar") {
return tracingComponent;
}
// Allow the panel to be resized when in the wider developer panel
return (
<PanelGroup direction="horizontal" className="h-full">
<Panel defaultSize={50} minSize={30} maxSize={80}>
{tracingComponent}
</Panel>
<PanelResizeHandle className="w-1 bg-border hover:bg-primary/50 transition-colors" />
<Panel defaultSize={50}>
<div />
</Panel>
</PanelGroup>
);
};
interface VegaHoverCellSignal {
cell: string[];
vlPoint: unknown;
}
const TraceBlock: React.FC<{
run: Run;
/**
* undefined means the user hasn't clicked on this run yet
*/
isExpanded: boolean | undefined;
isMostRecentRun: boolean;
chartPosition: ChartPosition;
theme: ResolvedTheme;
}> = ({ run, isMostRecentRun, chartPosition, isExpanded: expanded, theme }) => {
const setExpandedRuns = useSetAtom(expandedRunsAtom);
// We prefer the user's last click, but if they haven't clicked on this run,
// we expand the most recent run by default, otherwise we collapse it.
const isExpanded = expanded ?? isMostRecentRun;
const onToggleExpanded = () => {
setExpandedRuns((prev) => {
const newMap = new Map(prev);
newMap.set(run.runId, !isExpanded);
return newMap;
});
};
const Icon = isExpanded ? ChevronDown : ChevronRight;
const chevron = <Icon height={16} className="inline" />;
const traceTitle = (
<button
type="button"
aria-expanded={isExpanded}
className="text-sm cursor-pointer"
onClick={onToggleExpanded}
>
Run - {formatLogTimestamp(run.runStartTime)}
{chevron}
</button>
);
return (
<div
className={cn(
"grid grid-cols-1",
isExpanded &&
chartPosition === "sideBySide" &&
"grid-cols-[auto_minmax(0,1fr)] grid-rows-[auto_1fr]",
)}
>
<pre className="font-mono font-semibold">{traceTitle}</pre>
{isExpanded && (
<TraceBlockBody run={run} chartPosition={chartPosition} theme={theme} />
)}
</div>
);
};
const TraceBlockBody: React.FC<{
run: Run;
chartPosition: ChartPosition;
theme: ResolvedTheme;
}> = ({ run, chartPosition, theme }) => {
const [hoveredCellId, setHoveredCellId] = useState<CellId | null>();
const vegaRef = useRef<HTMLDivElement>(null);
const { ref, width = 300 } = useResizeObserver<HTMLDivElement>();
const cellIds = useCellIds();
const chartValues: ChartValues[] = [...run.cellRuns.values()].map(
(cellRun) => {
const elapsedTime = cellRun.elapsedTime ?? 0;
return {
cell: cellRun.cellId,
cellNum: cellIds.indexOf(cellRun.cellId),
startTimestamp: formatChartTime(cellRun.startTime),
endTimestamp: formatChartTime(cellRun.startTime + elapsedTime),
elapsedTime: formatElapsedTime(elapsedTime * 1000),
status: cellRun.status,
};
},
);
const hiddenInputElementId = `hiddenInputElement-${run.runId}`;
const vegaSpec = compile(
createGanttBaseSpec(
chartValues,
hiddenInputElementId,
chartPosition,
theme,
),
).spec;
const embed = useVegaEmbed({
ref: vegaRef,
spec: vegaSpec,
options: {
theme: theme === "dark" ? "dark" : undefined,
width: width - 50,
height: chartPosition === "above" ? 120 : 100,
actions: false,
// Using vega instead of vegaLite as some parts of the spec get interpreted as vega & will throw warnings
mode: "vega",
renderer: "canvas",
},
});
useEffect(() => {
const signalListeners: SignalListener[] = [
{
signalName: VEGA_HOVER_SIGNAL,
handler: (_name: string, value: unknown) => {
const signalValue = value as VegaHoverCellSignal;
const hoveredCell = (signalValue.cell?.[0] ?? undefined) as
| CellId
| undefined;
setHoveredCellId(hoveredCell ?? null);
},
},
];
signalListeners.forEach(({ signalName, handler }) => {
embed?.view.addSignalListener(signalName, handler);
});
return () => {
signalListeners.forEach(({ signalName, handler }) => {
embed?.view.removeSignalListener(signalName, handler);
});
};
}, [embed]);
const traceRows = (
<div className="font-mono font-semibold">
<TraceRows
run={run}
hoveredCellId={hoveredCellId}
hiddenInputElementId={hiddenInputElementId}
/>
</div>
);
const chartElement = (
<div
className={
chartPosition === "sideBySide"
? "-mt-0.5 col-start-2 row-start-1 row-span-2 min-w-0"
: "min-w-0"
}
ref={ref}
>
<Suspense>
<div ref={vegaRef} />
</Suspense>
</div>
);
if (chartPosition === "above") {
return (
<>
{chartElement}
{traceRows}
</>
);
}
return (
<>
{traceRows}
{chartElement}
</>
);
};
const TraceRows = (props: {
run: Run;
hoveredCellId: CellId | null | undefined;
hiddenInputElementId: string;
}) => {
const { run, hoveredCellId, hiddenInputElementId } = props;
// To send signals to Vega from React, we bind a hidden input element
const hiddenInputRef = useRef<HTMLInputElement>(null);
const dispatchHoverEvent = (cellId: CellId | null) => {
// dispatch input event to trigger vega's param to update
if (hiddenInputRef.current) {
hiddenInputRef.current.value = String(cellId);
hiddenInputRef.current.dispatchEvent(
new Event("input", { bubbles: true }),
);
}
};
return (
<div className="text-xs mt-0.5 ml-3 flex flex-col gap-0.5">
<input
type="text"
id={hiddenInputElementId}
defaultValue={hoveredCellId || ""}
hidden={true}
ref={hiddenInputRef}
/>
{[...run.cellRuns.values()].map((cellRun) => (
<TraceRow
key={cellRun.cellId}
cellRun={cellRun}
hovered={cellRun.cellId === hoveredCellId}
dispatchHoverEvent={dispatchHoverEvent}
/>
))}
</div>
);
};
const StatusIcons: Record<CellRun["status"], JSX.Element> = {
success: <CircleCheck color="green" size={14} />,
running: <CirclePlayIcon color="var(--blue-10)" size={14} />,
error: <CircleX color="red" size={14} />,
queued: <CircleEllipsis color="grey" size={14} />,
};
interface TraceRowProps {
cellRun: CellRun;
hovered: boolean;
dispatchHoverEvent: (cellId: CellId | null) => void;
}
const TraceRow: React.FC<TraceRowProps> = ({
cellRun,
hovered,
dispatchHoverEvent,
}: TraceRowProps) => {
const elapsedTimeStr = cellRun.elapsedTime
? formatElapsedTime(cellRun.elapsedTime * 1000)
: "-";
const elapsedTimeTooltip = cellRun.elapsedTime ? (
<span>
This cell took <ElapsedTime elapsedTime={elapsedTimeStr} /> to run
</span>
) : (
<span>This cell has not been run</span>
);
const handleMouseEnter = () => {
dispatchHoverEvent(cellRun.cellId);
};
const handleMouseLeave = () => {
dispatchHoverEvent(null);
};
return (
<div
className={cn(
"flex flex-row gap-2 py-1 px-1 opacity-70 hover:bg-(--gray-3) hover:opacity-100",
hovered && "bg-(--gray-3) opacity-100",
)}
onMouseEnter={handleMouseEnter}
onMouseLeave={handleMouseLeave}
>
<span className="text-(--gray-10) dark:text-(--gray-11)">
[{formatLogTimestamp(cellRun.startTime)}]
</span>
<span className="text-(--gray-10) w-16 overflow-hidden">
(<CellLink cellId={cellRun.cellId} />)
</span>
<span className="w-40 truncate -ml-1">{cellRun.code}</span>
<div className="flex flex-row gap-1 w-16 justify-end -ml-2">
<Tooltip content={elapsedTimeTooltip}>
<span className="text-(--gray-10) dark:text-(--gray-11)">
{elapsedTimeStr}
</span>
</Tooltip>
<Tooltip content={cellRun.status}>
{StatusIcons[cellRun.status]}
</Tooltip>
</div>
</div>
);
};