Skip to content

Add live profiling support with flame graph visualization #1

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom
Draft
Copilot wants to merge 7 commits into
base: main
Choose a base branch
from
Draft

Add live profiling support with flame graph visualization #1

Copilot wants to merge 7 commits into from

Conversation

Copy link

Copilot AI commented Feb 3, 2026 •
edited by vilterp
Loading

Implements live profiling for Python debug sessions, consuming the profiling API from debugpy via DAP custom requests/events.

Dependent on vilterp/debugpy#1

Implementation

Core profiling flow:

  • ProfilingService sends startProfiling/stopProfiling DAP requests
  • ProfilingEventHandler receives profilingSamples events, routes to aggregator
  • ProfileDataAggregator builds weighted call tree incrementally from stack samples
  • ProfileViewerManager renders webview with flame graph and sortable function table
  • Real-time updates via postMessage as samples arrive

UI integration:

  • Debug toolbar buttons (⏺ start, ⏹ stop) visible during active Python sessions
  • Automatic webview creation on profiling start
  • Flame graph: bottom=entry point, top=hot code, width=time proportion
  • Function table: sortable by self/total time with percentages
  • Session cleanup on debug termination

Architecture:

Debug toolbar → ProfilingService → debugpy (DAP)
                                        ↓
         profilingSamples events → ProfileDataAggregator
                                        ↓
                          ProfileViewerManager → Webview

Files Added

Implementation (6 TypeScript services, 837 lines):

  • profilingService.ts - DAP communication layer
  • profileDataAggregator.ts - Weighted tree builder
  • profileViewerManager.ts - Webview lifecycle + embedded HTML/CSS/JS
  • profilingEventHandler.ts - Event routing
  • profilingCommands.ts - Command registration
  • types.ts - Type definitions

Tests:

  • profileDataAggregator.unit.test.ts - 7 tests covering aggregation logic (100% passing)

Documentation:

  • PROFILING_USAGE.md - User guide
  • PROFILING_UI.md - UI specification
  • DEBUGPY_SETUP.md - Custom debugpy installation (3 methods: environment install, launch.json path, custom extension)
  • IMPLEMENTATION_SUMMARY.md - Architecture overview
  • profiling_demo.py - Test script

Configuration Changes

  • package.json - Commands, debug toolbar menu contributions, React dependencies
  • serviceRegistry.ts - DI registration for profiling services
  • constants.ts, commands.ts - Command definitions and type mappings

debugpy Resolution Order

Documentation clarifies that ms-python.debugpy checks the active Python environment for debugpy before using its bundled version:

  1. Explicit debugAdapterPath in launch.json (highest priority)
  2. debugpy in active interpreter (via import debugpy)
  3. Bundled debugpy (fallback)

This means pip install git+https://github.com/vilterp/debugpy.git@profiling-support in a venv automatically takes priority - no configuration needed.

Original prompt

this PR adds support for 'live profiling' to the debugpy python debugger backend, exposing it over DAP: vilterp/debugpy#1

Now I want to consume this API from the VSCode Python extension. This should involve:

  1. adding a button to the debug sidebar (not sure which panel) to start profiling, once VSCode is already connected to a debugpy session
  2. when the button is pressed, start profiling and open a new profile viewer tab
  3. in the profile viewer tab, render a live flame graph. i.e. maintain a weighted tree of stack frames, and for each new batch of samples received over the wire, (1) incorporate each stack into the weighted tree, (2) rerender the flame graph from the new tree.

The profile viewer tab should include

  1. a flame graph viewer, using react-flame-graph
  2. a sortable table, where each row is a function, with self and total time. allow sorting by self or total time.

✨ Let Copilot coding agent set things up for you — coding agent works faster and does higher quality work when set up for your repo.

Copilot AI and others added 4 commits February 3, 2026 19:06
@vilterp
Add core profiling infrastructure and webview UI
05c2dd7 
- Add profiling commands (Start/Stop Profiling) with record/stop icons
- Create profiling service for DAP communication
- Implement profile data aggregator with weighted tree
- Create profile viewer manager with embedded webview
- Add profiling event handler for DAP custom events
- Register profiling services in debugger service registry
- Add profiling buttons to debug toolbar
- Install React and react-flame-graph dependencies
- Update icon to use "record" icon for start profiling button

Co-authored-by: vilterp <7341+vilterp@users.noreply.github.com>
@vilterp
Add session cleanup and comprehensive unit tests
4986aa3 
- Add handleTerminateEvent to close profile viewers when debug session ends
- Create comprehensive unit tests for ProfileDataAggregator
- Fix frame iteration order to build correct flame graph (bottom-to-top)
- Fix function table aggregation to properly sum self/total counts
- Fix percentage calculation to happen after all data is collected
- All 7 profiling tests now passing

Co-authored-by: vilterp <7341+vilterp@users.noreply.github.com>
@vilterp
Add comprehensive documentation and demo script
a1eab52 
- Create detailed README explaining architecture and components
- Add quick start guide for users (PROFILING_USAGE.md)
- Include example Python script for testing (profiling_demo.py)
- Document DAP protocol, data flow, and interpretation
- Add troubleshooting tips and best practices

Co-authored-by: vilterp <7341+vilterp@users.noreply.github.com>
@vilterp
Add UI specification and implementation summary
53d1375 
- Create detailed UI layout specification (PROFILING_UI.md)
- Add comprehensive implementation summary
- Document all files created and modified
- Provide testing instructions and success criteria
- Include architecture diagrams and design decisions

Co-authored-by: vilterp <7341+vilterp@users.noreply.github.com>
Copilot AI changed the title [WIP] Add live profiling support to VSCode Python extension Add live profiling support with DAP integration Feb 3, 2026
Copilot AI requested a review from vilterp February 3, 2026 19:19
@vilterp
Add comprehensive debugpy setup guide
4acc6bb 
- Create DEBUGPY_SETUP.md with 3 methods for installing custom debugpy
- Document Method 1: Install in Python environment (recommended)
- Document Method 2: Use debugAdapterPath in launch.json (advanced)
- Document Method 3: Build custom ms-python.debugpy extension (expert)
- Add troubleshooting section with common issues and solutions
- Include platform-specific notes (Windows, macOS, Linux, Docker)
- Update PROFILING_USAGE.md with quick setup and link to guide
- Update IMPLEMENTATION_SUMMARY.md to reference new documentation
- Update profiling README.md with documentation index

Co-authored-by: vilterp <7341+vilterp@users.noreply.github.com>
Copilot AI changed the title Add live profiling support with DAP integration Add documentation for using custom debugpy versions Feb 3, 2026
@vilterp
Clarify debugpy resolution order and virtual environment priority
2e1f535 
- Add "How debugpy is Resolved" section explaining priority order
- Clarify that ms-python.debugpy checks environment BEFORE bundled version
- Add "Understanding debugpy Resolution Order" section with detailed explanation
- Emphasize that installing in venv/virtualenv takes priority automatically
- Add FAQ section answering "Does the debugpy extension check my virtual environment first?" (YES!)
- Add verification steps to confirm which debugpy is being used
- Update Method 1 explanation with "Why This Works" subsection
- Make it crystal clear that environment debugpy has priority over bundled version

This directly answers the user's question: "So the vscode python extension (or the
debugpy extension it uses) looks for a version of debugpy in the debugee's virtual
environment, before falling back to its own internal version?" - YES, it does!

Co-authored-by: vilterp <7341+vilterp@users.noreply.github.com>
Copilot AI changed the title Add documentation for using custom debugpy versions Document debugpy resolution order and custom installation methods Feb 3, 2026
Copilot AI changed the title Document debugpy resolution order and custom installation methods Add live profiling support with flame graph visualization Feb 3, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@vilterp vilterp Awaiting requested review from vilterp

Assignees

@vilterp vilterp

Copilot code review Copilot

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

2 participants

@vilterp