Trace & Invocation Viewer
Relevant source files
The following files were used as context for generating this wiki page:
- apps/web/src/app/(protected)/(traces)/trace/[wf_inv_id]/page.tsx
- apps/web/src/features/trace-visualization/components/TimelineEntry.tsx
- apps/web/src/app/components/agent-dialog/purpose-section.tsx
- apps/web/src/app/components/evolution/WorkflowEvolutionVisualization.tsx
- packages/core/src/prompts/evaluator/root-cause/rca.ts
- packages/core/README.md
- apps/web/src/lib/workflow_setup_examples/my-workflow-judge.json
The Trace & Invocation Viewer is a web-based interface for observing and analyzing the execution of an agentic workflow. It provides a detailed, step-by-step visualization of a workflow invocation, showing the sequence of agent (node) operations, their inputs and outputs, performance metrics, and internal execution steps. This tool is critical for debugging, performance tuning, and understanding the behavior of the multi-agent system.
The viewer is part of the broader observability infrastructure, which includes features like the Evolution Visualization. The trace data is not only for human analysis but is also consumed by the system's AI for root cause analysis and self-improvement.
Sources: README.md, packages/core/README.md, packages/core/src/prompts/evaluator/root-cause/rca.ts:4
Architecture and Data Flow
The Trace Detail Page is a client-side rendered page in the Next.js application. It fetches and displays all information related to a single workflow invocation, identified by wf_inv_id from the URL.
The following diagram illustrates the component hierarchy and data flow for the viewer.
This diagram shows that the TraceDetailPage uses a query hook to fetch data, processes it into timeline and performanceMetrics objects, and passes them to child components for rendering.
Sources: apps/web/src/app/(protected)/(traces)/trace/[wf_inv_id]/page.tsx:16-80
Data Fetching Sequence
The data fetching process is managed by TanStack Query, which provides features like auto-refresh for running workflows.
This sequence shows the user navigation triggering a data fetch via the useTraceQuery hook, which retrieves all necessary records from the database.
Sources: apps/web/src/app/(protected)/(traces)/trace/[wf_inv_id]/page.tsx:18-19
Core Components
The viewer is composed of several key React components that work together to display the trace information.
| Component | File Path | Description |
|---|---|---|
TraceDetailPage | apps/web/src/app/(protected)/(traces)/trace/[wf_inv_id]/page.tsx | The main page component. It orchestrates data fetching, processes the data, and renders all sub-components. |
PerformanceOverview | apps/web/src/app/(protected)/(traces)/trace/[wf_inv_id]/components/PerformanceOverview.tsx | Displays a summary of key performance metrics for the entire workflow invocation. |
Timeline | apps/web/src/features/trace-visualization/components/Timeline.tsx | A container component that renders a horizontal, scrollable list of TimelineEntry components. |
TimelineEntry | apps/web/src/features/trace-visualization/components/TimelineEntry.tsx | A detailed card for a single node invocation. It shows inputs, outputs, execution steps, tools used, and metadata. |
AgentStepItem | apps/web/src/features/trace-visualization/components/TimelineEntry.tsx | A sub-component within TimelineEntry that renders a single execution step of an agent, such as a tool call or reasoning block. |
Sources: apps/web/src/app/(protected)/(traces)/trace/[wf_inv_id]/page.tsx, apps/web/src/features/trace-visualization/components/TimelineEntry.tsx
TimelineEntry Component
This is the most information-dense component, providing a complete view of a single node's activity within the workflow. Its key features include:
- Header: Displays the
node_id, invocation duration, and a button to inspect the raw database content for the invocation. - System Prompt: A collapsible section to view the
system_promptthat configured the agent for this step. - I/O Payloads: Displays summarized and expandable views of the input message received and the final output message produced.
- Execution Steps: A detailed, expandable log of the agent's internal monologue, including reasoning, planning, and tool calls (
AgentSteps). - Tool Usage: Badges indicate which tools were available to the node and which were actually used during the invocation.
- Memory: Shows the agent's initial memory state and any memory updates that occurred during execution.
- Metadata: Includes the language model used and the total cost (
usd_cost) for the invocation.
Sources: apps/web/src/features/trace-visualization/components/TimelineEntry.tsx:81-496
Data Processing and Transformation
The raw data fetched from the database is not rendered directly. Instead, it undergoes significant processing within the TraceDetailPage component to prepare it for visualization.
Timeline Entry Creation
The nodeInvocations array from the database is transformed into a timeline array of FullTraceEntry objects. This process is handled within a useMemo hook to optimize performance.
The transformation logic includes:
- Mapping each
nodeInvocationto aFullTraceEntry. - Extracting the first message from
inv.outputsto serve as the primary output. - For the final node in the workflow, creating a synthetic "result" message from the
inv.outputfield to ensure the final workflow result is displayed. - Enriching the
nodeDefinitionby retrieving the correctsystemPromptfrom the parentworkflowVersion.dslconfiguration, as the one on the invocation record might be incomplete.
The resulting FullTraceEntry structure is defined as:
interface FullTraceEntry {
invocation: NodeInvocation; // The raw node_invocations record
nodeDefinition: Node; // The node's configuration
inputs: Message[]; // Array of input messages
output: Message | null; // The primary output message
}
Sources: apps/web/src/app/(protected)/(traces)/trace/[wf_inv_id]/page.tsx:25-72
Performance Metrics Calculation
High-level performance metrics are also calculated in a useMemo hook, providing a quick overview of the workflow's efficiency.
| Metric | Calculation |
|---|---|
totalDuration | The time difference in seconds between workflow.end_time and workflow.start_time. |
totalNodes | The total number of entries in the timeline array. |
totalCost | Sum of usd_cost from each node invocation. Uses workflow.usd_cost if available. |
bottleneckNode | The node_id of the node invocation with the longest duration. |
Sources: apps/web/src/app/(protected)/(traces)/trace/[wf_inv_id]/page.tsx:83-125
Agent Execution Steps
The TimelineEntry component can display a detailed breakdown of an agent's internal execution steps. This data is extracted from the extras.agentSteps field of a NodeInvocation record.
Agent Step Types
The agentSteps array contains a sequence of objects, each representing a thought or action by the agent.
| Step Type | Description |
|---|---|
reasoning | The agent's thought process or internal monologue. |
plan | A structured plan of action the agent intends to take. |
tool | A call to an available tool. Includes the tool name, parameters, and the result. |
text | A text-based output generated by the agent. |
error | An error that occurred during the agent's execution. |
These steps are rendered by the AgentStepItem component, which provides expandable views for detailed inspection of tool call arguments and results. The system also supports a legacy toolUsage format, which is normalized into the AgentSteps structure for consistent display.
Sources: apps/web/src/features/trace-visualization/components/TimelineEntry.tsx:28-40, 368-433, apps/web/src/app/(protected)/dev/components/PipelineTester.tsx:22-30
Conclusion
The Trace & Invocation Viewer is an essential tool for developers and operators of the lucky platform. It provides deep insights into the runtime behavior of agentic workflows, enabling rapid debugging, performance analysis, and a clear understanding of how agents collaborate to achieve a goal. By visualizing everything from high-level performance metrics to the finest details of an agent's internal reasoning, the viewer is fundamental to the system's principle of observability and supports its advanced capabilities for autonomous evolution.
Sources: packages/core/README.md, apps/web/src/app/(protected)/(traces)/trace/[wf_inv_id]/page.tsx