Flamechart

The Flamechart provides an interactive visualization of function execution traces. It helps you understand your code's execution flow, identify performance bottlenecks, and navigate to source code.

Video Demo

Watch this demonstration of the non-overlapping hierarchical flame graph:

Opening the Flamechart

Use any of these methods:

1. Command Palette: Ctrl+Shift+P / Cmd+Shift+P → SF Veritas: Show Flamechart
2. Activity Bar: Click the SF Veritas icon → Flamechart option

Understanding the Visualization

What is a Flamechart?

A flamechart shows function calls as horizontal bars stacked vertically:

• Horizontal Position: Time (left = earlier, right = later)
• Horizontal Width: Duration (wider = longer execution)
• Vertical Position: Call depth (top = entry point, lower = nested calls)
• Color: Consistent color per function name

Time →
┌────────────────────────────────────────────────────────┐
│                    main()                               │ ← Entry point
├────────────┬───────────────────────────┬───────────────┤
│ initApp()  │      processRequest()     │   cleanup()   │ ← First level calls
├────────────┼───────┬───────────────────┼───────────────┤
│            │query()│   validateData()  │               │ ← Nested calls
└────────────┴───────┴───────────────────┴───────────────┘

Reading the Chart

• Wide bars: Functions that took a long time
• Deep stacks: Functions with many nested calls
• Gaps: Time between function calls (I/O, async operations)

Navigation Controls

Zoom

• Scroll wheel: Zoom in/out on the timeline
• Pinch gesture: Zoom on trackpad
• Zoom to fit: Click the "Fit" button to see all data

Pan

• Click and drag: Move around the visualization
• Arrow keys: Pan left/right

Reset View

Click the Reset button to return to the default zoom and position.

Undo/Redo

Navigation history is preserved:

• Undo: Go back to previous view
• Redo: Go forward if you've undone

Interacting with Functions

Hover

Hover over any function bar to see:

• Function name
• File location
• Duration
• Start/end timestamps

Click to Navigate

Click any function bar to jump directly to its definition in your source code.

This is one of the most powerful features - you can explore execution flow and immediately see the relevant code.

Context Menu

Right-click a function for additional options:

• Jump to definition
• Add to Console filter
• Add to Console focus

Multi-Process Support

When running multiple instrumented services:

Process Selector

1. Look for the Process Dropdown in the header
2. Select a specific process to view its traces
3. Each process has its own flamechart

Process Status

The status indicator shows:

• Green dot: Process is running
• Red dot: Process has terminated (showing last captured state)

Status is checked every 5 seconds.

Switching Processes

Select a different process from the dropdown to instantly switch views. Each process maintains its own data separately.

Real-Time Updates

Auto-Refresh

By default, the flamechart updates automatically as new traces are captured.

To toggle auto-refresh:

1. Check the sfVeritas.autoRefresh setting
2. Or use the refresh button for manual updates

Manual Refresh

Click the Refresh button to update the display with the latest data.

Performance Table

Below the visualization, a performance table shows:

Column	Description
Function	Function name
Duration	Total execution time
Call Count	Number of times called

Table Interaction

• Click column headers to sort
• Click rows to navigate to the function
• Colors match the flamechart visualization

Layout Controls

Worker Pool Toggle

Show or hide worker pool operations:

• When enabled: Shows parallel worker executions
• When disabled: Hides worker-related spans

Non-Overlapping Layout

Toggle vertical arrangement of the call stack:

• Overlapping (default): Traditional flamechart layout
• Non-overlapping: Spreads functions vertically without overlap

This can help when functions overlap in time (parallel execution).

Source Map Support

The flamechart automatically resolves source maps:

• dist/ files are mapped back to src/ TypeScript files
• Click to navigate goes to the original source, not compiled output
• Function names show the original names

This requires proper source map configuration in your project.

Performance

The flamechart is optimized for large datasets:

• Custom Canvas Renderer: Smooth 60fps rendering
• Viewport Culling: Only visible elements are rendered
• Spatial Indexing: Fast click detection

Performance Guidelines

Span Count	Performance
1,000	60fps rendering
5,000	30fps minimum
10,000	Usable with smooth interactions

Tips for Large Traces

1. Use zoom to focus on specific time periods
2. Filter by process if running multiple services
3. Use the performance table to find slow functions

Troubleshooting

No traces appearing

1. Verify function tracing is enabled in your .sailfish config
2. Check that the application is running and instrumented
3. Look in the Console for related errors

Flamechart is empty after clicking

1. Wait for the application to execute some code
2. Check that the local server is running
3. Try the manual refresh button

Click-to-navigate not working

1. Verify source maps are generated (for TypeScript)
2. Check that file paths are correct
3. Ensure the file exists in your workspace

Rendering issues

1. Try toggling the non-overlapping layout
2. Zoom out to see if the issue is visible
3. Refresh the view

Keyboard Shortcuts

Action	Shortcut
Pan left	Left arrow
Pan right	Right arrow
Zoom in	Scroll up
Zoom out	Scroll down

Next Steps

• Review the Console documentation for log analysis
• Check settings (sfVeritas.*) for configuration options