SF Veritas Flamechart Visualizer

Visualize function span traces from sf-veritas instrumentation as interactive flamecharts directly in VS Code.

Features

✅ Custom Interactive Flamechart: Built-in HTML5 Canvas visualization for blazing-fast performance
✅ Click-to-Navigate: Click any function in the flamechart to jump directly to source code
✅ Automatic Process Detection: Automatically detects running Node.js processes using sf-veritas instrumentation
✅ Real-time Visualization: Watch function spans as they're captured with automatic updates
✅ Hover Tooltips: See function name, file location, and duration on hover
✅ Horizontal Zoom & Pan: Zoom into time ranges and pan across the timeline
✅ Source Map Support: Automatically resolves dist/ files back to src/ TypeScript
✅ JSONL File Monitoring: Watches files for changes with intelligent incremental reading
✅ Multi-process Support: Switch between multiple instrumented processes in real-time
✅ Process Status Monitoring: Visual indicators show when processes are running or terminated
✅ High Performance: Handles 10,000+ spans with viewport culling and spatial indexing
✅ Theme-Aware: Adapts colors to Light, Dark, and High Contrast themes

Screenshots

The extension displays an interactive flamechart showing:

Function call hierarchy
Execution time distribution
Parent-child relationships
Real-time statistics (span count, frames, duration)

Requirements

VS Code: 1.74.0 or higher
Node.js: 16+ (for your application)
sf-veritas: Instrumented Node.js application
Platform: macOS or Linux (Windows support coming soon)

Quick Start

1. Instrument Your Application

Add sf-veritas instrumentation to your Node.js application:

# Using environment variable for JSONL output
SF_FUNCSPAN_JSONL_FILE=true node --import @sailfish-ai/sf-veritas/runtime/register-loader app.js

Or with a custom JSONL file path:

SF_FUNCSPAN_JSONL_FILE=./my-spans.jsonl node --import @sailfish-ai/sf-veritas/runtime/register-loader app.js

2. Open VS Code Extension

In VS Code with the extension installed:

Open Command Palette: Cmd/Ctrl+Shift+P
Run: SF Veritas: Show Flamechart
Select your process from the dropdown
View the interactive flamechart!

3. Interact with the Flamechart

Click-to-Navigate: Click any function bar to jump to its source code
Zoom (Horizontal): Scroll mouse wheel to zoom into time periods
Pan: Click and drag to move around the flamechart
Hover: Move mouse over any bar to see function details (name, file:line, duration)
Reset View: Click "Reset View" button to return to default zoom/position
Auto-Update: Flamechart updates automatically as new spans are captured

4. Working with Multiple Processes

When multiple sf-veritas processes are detected:

Process Selector: A dropdown appears in the webview header showing all available processes
Switch Processes: Select a different process from the dropdown to switch instantly
Status Indicators:
- 🟢 Green dot = Process is running
- 🔴 Red dot = Process has terminated
Data Preservation: Each process maintains its own data - switching doesn't lose captured spans
Auto-monitoring: The extension checks process status every 5 seconds and updates indicators
Terminated Processes: You can still view flamecharts from terminated processes (last captured state)

Commands

Command	Description
`SF Veritas: Show Flamechart`	Detect processes and visualize function spans
`SF Veritas: Refresh Processes`	List all detected sf-veritas processes with details

Extension Settings

Configure the extension via VS Code settings:

sfVeritas.autoRefresh: Automatically refresh flamechart as new spans are captured (default: true)
sfVeritas.debugMode: Enable debug logging for troubleshooting (default: false)

How It Works

Architecture

┌─────────────────┐
│ Node.js Process │ → Captures function spans
└────────┬────────┘
         │ Writes JSONL
         ▼
┌─────────────────┐
│ funcspans.jsonl │ ← Watched by extension
└────────┬────────┘
         │ Parses & converts
         ▼
┌─────────────────┐
│  VS Code Panel  │ → Displays Speedscope
└─────────────────┘

Components

ProcessManager: Detects running Node.js processes with sf-veritas
- Uses ps command to find processes
- Extracts working directory and environment variables
- Resolves JSONL file paths
JsonlParser: Monitors JSONL files in real-time
- Uses chokidar for reliable file watching
- Incremental reading (tracks byte position)
- Graceful error handling for malformed lines
SpanConverter: Transforms spans to Speedscope format
- Frame deduplication
- Proper parent-child nesting
- Open/close event generation
- Time normalization
WebviewManager: Displays the flamechart
- Custom HTML5 Canvas renderer
- Click-to-navigate integration with VS Code
- Hover tooltips and visual feedback
- Horizontal zoom and pan controls
- Message passing for interactivity
- Automatic updates on new spans
- Multi-process state management
- Process status monitoring (5-second intervals)
- Resource cleanup
FlamechartRenderer: Custom canvas visualization
- Stack-based algorithm for event-to-rectangle conversion
- Viewport culling for high performance (only renders visible elements)
- Spatial indexing for O(log n) click detection
- Theme-aware colors with HSL hashing
- Request animation frame for smooth 60fps rendering
- Device pixel ratio support for high-DPI displays

Data Flow

Function Call → Span Captured → JSONL Write →
File Change → Parser Reads → Converter Transforms →
Webview Updates → Flamechart Renders

Supported Platforms

Platform	Process Detection	File Watching	Status
macOS	✅ Yes (lsof)	✅ Yes	Full support
Linux	✅ Yes (pwdx)	✅ Yes	Full support
Windows	❌ Not yet	✅ Yes	Partial (manual file selection)

Troubleshooting

No Processes Detected

Problem: Extension shows "No sf-veritas processes detected"

Solutions:

Verify your application is running with the correct flags:

SF_FUNCSPAN_JSONL_FILE=true node --import @sailfish-ai/sf-veritas/runtime/register-loader app.js

Check that SF_FUNCSPAN_JSONL_FILE environment variable is set
Enable debug mode in settings to see detailed logs
Try running SF Veritas: Refresh Processes to see all environment variables

No JSONL File Found

Problem: Process detected but no JSONL file found

Solutions:

Ensure SF_FUNCSPAN_JSONL_FILE is set to true or a file path
Check file permissions (extension must be able to read the file)
Verify the file exists in the process working directory

Flamechart Not Updating

Problem: Flamechart doesn't show new spans

Solutions:

Check that sfVeritas.autoRefresh is enabled
Click the "Refresh" button manually
Verify new spans are being written to the JSONL file
Enable debug mode to see parser logs

Extension Performance

Problem: Extension feels slow with many spans

Solutions:

The extension handles thousands of spans efficiently
Speedscope may slow down with 100,000+ spans
Consider filtering spans at the instrumentation level
Use the refresh button instead of auto-refresh for very large files

Development

Building from Source

git clone <repository-url>
cd vscode-extension
npm install
npm run compile

Running in Development

Open the extension folder in VS Code
Press F5 to launch Extension Development Host
Test the extension in the new window

Testing

Run the test parsers:

# Test JSONL parser
node test-parser-sync.js

# Test Speedscope converter
node test-converter.js

Project Structure

vscode-extension/
├── src/
│   ├── extension.ts          # Entry point
│   ├── processManager.ts     # Process detection
│   ├── jsonlParser.ts        # JSONL file monitoring
│   ├── spanConverter.ts      # Speedscope conversion
│   ├── webviewManager.ts     # Webview lifecycle
│   ├── sourceMapResolver.ts  # Source map resolution
│   └── types.ts              # TypeScript types
├── webview-src/              # React webview source (console + flamechart)
├── dist/                     # Compiled JavaScript + built webviews
├── package.json              # Extension manifest
└── README.md                 # This file

Implementation Status

Phase	Status	Description
Phase 1	✅ Complete	Process detection & infrastructure
Phase 2	✅ Complete	File watching & JSONL parsing
Phase 3	✅ Complete	Speedscope format conversion
Phase 4	✅ Complete	Webview integration
Phase 5	✅ Complete	Interactive features
Phase 6	✅ Complete	Real-time updates
Phase 7	✅ Complete	Multi-process support
Phase 8	✅ Complete	Polish & documentation

Future Enhancements

Windows Support: Full process detection on Windows
Bundled Speedscope: Local Speedscope instead of iframe
Custom Visualizations: Additional chart types (timeline, call graph)
Filtering: Filter spans by function name, duration, etc.
Export: Save flamecharts as images or JSON
Comparison: Compare multiple trace sessions
Test Integration: Automatic tracing for test runs
Cloud Integration: Connect to cloud platform for historical traces

Known Limitations

Windows process detection not implemented (can still visualize if file path is known)
Very large traces (100k+ spans) may have some performance impact
Arrow functions in TypeScript may not be instrumented (use function declarations)
Source map resolution uses heuristics (works for most TypeScript projects)

Release Notes

0.3.0 (Current)

Custom Flamechart with Click-to-Navigate

This is a major update replacing the Speedscope iframe with a custom-built HTML5 Canvas flamechart.

New Features:

✅ Click-to-Navigate: Click any function bar to jump directly to source code
✅ Custom Canvas Renderer: High-performance visualization built from scratch
✅ Horizontal-Only Zoom: Zoom into time periods while keeping call depth fixed
✅ Hover Tooltips: Rich tooltips showing function name, file location, and duration
✅ Viewport Culling: Only renders visible elements for 60fps even with 10,000+ spans
✅ Spatial Indexing: O(log n) click detection using grid-based lookup
✅ Theme Support: Automatically adapts colors to Light, Dark, and High Contrast themes
✅ Source Maps: Automatic resolution of dist/ files to src/ TypeScript files
✅ No External Dependencies: Pure vanilla JavaScript, no D3.js or other libraries
✅ Offline Support: No internet connection required (was needed for Speedscope iframe)

Performance:

Handles 1,000 spans: 60fps rendering
Handles 5,000 spans: 30fps minimum
Handles 10,000 spans: usable with smooth interactions
Click latency: <50ms

Technical Details:

Stack-based algorithm for event-to-rectangle conversion
Request animation frame for debounced rendering
Device pixel ratio support for Retina displays
Message passing for seamless VS Code integration

0.2.0

Enhanced Multi-Process Support

New Features:

✅ In-webview process selector dropdown
✅ Real-time process switching without closing the webview
✅ Per-process state management (each process maintains its own data)
✅ Process status monitoring with visual indicators
- Green dot for running processes
- Red dot for terminated processes
✅ Automatic process health checks (every 5 seconds)
✅ Graceful handling of process termination
✅ View flamecharts from terminated processes (last captured state)

Improvements:

Better resource management for multiple processes
Enhanced webview UI with status indicators
Improved cleanup on panel disposal

0.1.0

MVP Release - All core phases complete!

Features:

✅ Automatic process detection (macOS/Linux)
✅ Real-time JSONL file monitoring
✅ Speedscope flamechart visualization
✅ Interactive span details
✅ Jump to definition
✅ Multi-process support
✅ Auto-refresh on new spans

Bug Fixes:

Proper resource cleanup on panel close
Graceful handling of malformed JSONL lines
Orphaned span detection

Contributing

This is part of the SF Veritas project. Contributions are welcome!

Reporting Issues

Please include:

VS Code version
Extension version
Operating system
Node.js version
Steps to reproduce
Debug logs (enable sfVeritas.debugMode)

Development Setup

See the Development section above for setup instructions.

License

MIT

Credits

Chokidar: File watching by @paulmillr
SF Veritas: Function span instrumentation
Speedscope Format: Inspired by the excellent Speedscope project by @jlfwong

Support

For questions and support:

GitHub Issues: [Report bugs or request features]
Documentation: See this README
Debug Mode: Enable sfVeritas.debugMode for detailed logs

Happy debugging! 🔥📊

SF Veritas

Sailfish AI

SF Veritas Flamechart Visualizer

Features

Screenshots

Requirements

Quick Start

1. Instrument Your Application

2. Open VS Code Extension

3. Interact with the Flamechart

4. Working with Multiple Processes

Commands

Extension Settings

How It Works

Architecture

Components

Data Flow

Supported Platforms

Troubleshooting

No Processes Detected

No JSONL File Found

Flamechart Not Updating

Extension Performance

Development

Building from Source

Running in Development

Testing

Project Structure

Implementation Status

Future Enhancements

Known Limitations

Release Notes

0.3.0 (Current)

0.2.0

0.1.0

Contributing

Reporting Issues

Development Setup

License

Credits

Support