Parca Profiler for VS Code

View profiling data from Parca or Polar Signals Cloud directly in VS Code with inline code annotations.

Features

Dual-mode support: Connect to self-hosted Parca (OSS) or Polar Signals Cloud
Inline annotations: See CPU time, memory allocations, and other metrics directly in your code
Preset queries: Quick access to common profiling scenarios (On-CPU, Off-CPU, Memory, etc.)
Deep linking: Open VS Code from Parca/Polar Signals Cloud.
Session caching: Annotations persist as you navigate between files

Installation & Development

Prerequisites

VS Code 1.85.0 or later
Node.js and pnpm

Setup

Install dependencies:

cd ui/packages/shared/vscode-source-viewer
pnpm install

Compile the extension:

pnpm run compile

Test the extension:
- Open this directory in VS Code
- Press F5 to launch Extension Development Host
- In the new window, open a source file from your project
- On first use, a setup wizard will guide you through configuration

Configuration

First-Time Setup

On first use, the extension will prompt you to choose a mode:

Polar Signals Cloud: Requires an API token from your Polar Signals account
Self-hosted Parca: Connects to a local or remote Parca instance (no authentication)

Settings

The extension supports the following settings (prefix: parca.*):

Setting	Description	Default
`parca.mode`	Connection mode (`cloud` or `oss`)	(set during setup)
`parca.cloudUrl`	Polar Signals Cloud API URL	`https://api.polarsignals.com`
`parca.parcaUrl`	Self-hosted Parca URL	`http://localhost:7070`
`parca.defaultTimeRange`	Default time range for queries	`1h`
`parca.profileType`	Default profile type	`parca_agent:samples:count:cpu:nanoseconds:delta`
`parca.presets`	Custom query presets	`[]`

API Token (Cloud Mode)

For Polar Signals Cloud, you'll need an API token:

Go to your Polar Signals project settings
Generate a new API token
Enter it when prompted during setup

The token is securely stored using VS Code's Secret Storage API.

Usage

Quick Start with Presets

Open a source file in VS Code
Open Command Palette (Cmd+Shift+P / Ctrl+Shift+P)
Run: Parca: Select Preset
Choose a preset (e.g., "On-CPU (15min)")
Profiling annotations appear inline in your code

Fetch Profile with Custom Query

Open a source file in VS Code
Open Command Palette
Run: Parca: Fetch Profile for Current File
Configure the query (profile type, time range, labels)
The extension fetches and displays profiling data

Deep Linking

In Parca or Polar Signals Cloud, right click on any node in the flame graph or in the Source View (only in Polar Signals Cloud) and click on the "Open in VS Code" option.
VS Code opens with profiling data for that file and line
Make sure VS Code has the correct workspace open and is in focus so the extension can actually open the file in the correct context.

Import from URL

Copy a URL from Parca or Polar Signals Cloud
Run: Parca: Import from URL
Paste the URL
The extension imports the query configuration

Commands

Command	Description
`Parca: Fetch Profile for Current File`	Fetch profiling data with full configuration
`Parca: Select Preset`	Quick fetch using a preset configuration
`Parca: Quick Actions`	Show status bar menu with common actions
`Parca: Import from URL`	Import query from a Parca or Polar Signals Cloud URL
`Parca: Clear Profiling Annotations`	Remove all profiling annotations
`Parca: Configure Defaults`	Open extension settings
`Parca: Setup Mode`	Re-run the setup wizard to change mode
`Parca: Clear API Token`	Remove stored API token

Built-in Presets

Available in Both Modes

On-CPU: CPU profile samples (15min, 1h, 24h)
Off-CPU: Time spent waiting/blocked (15min, 1h)
Memory Allocations: Memory allocations during time period
Memory In-Use: Currently allocated memory
Goroutines: Goroutine creation stack traces
Mutex Contention: Time spent waiting on mutex locks
Block Contention: Time spent blocked on synchronization

OSS Mode Only

Process CPU: CPU samples from Go runtime pprof
Fgprof: Full goroutine profiler (on + off CPU combined)
Block Contentions Count: Number of blocking events

Architecture

Components

Extension (extension.ts): Main entry point, registers commands
API Client (api/profiler-client.ts): Queries Parca/Polar Signals Cloud API
Settings (config/settings.ts): Manages dual-mode configuration and secrets
Setup Wizard (onboarding/setup-wizard.ts): First-use onboarding flow
Presets (presets/preset-definitions.ts): Built-in and user-defined query presets
Annotations (annotations/profiling-annotations.ts): Inline code decorations
Session Store (state/session-store.ts): Caches profiling data per file

Development

Watch Mode

Run TypeScript compiler in watch mode:

pnpm run watch

Testing

Make code changes
Press F5 in VS Code to launch Extension Development Host
Test your changes in the new window
Use Developer Tools (Help → Toggle Developer Tools) to debug

Packaging

Build a .vsix package for distribution:

pnpm run package

Troubleshooting

"No profiling data found"

Ensure the file you're viewing has profiling data
Check that the time range includes data for this file
Verify your query labels match the profiled application

Connection errors (OSS mode)

Verify Parca is running at the configured URL
Check parca.parcaUrl in settings
Ensure the URL uses the correct protocol (HTTP for localhost, HTTPS for remote)

Authentication errors (Cloud mode)

Verify your API token is valid
Run Parca: Clear API Token and re-enter your token
Ensure your token has read permissions

Extension not loading

Check VS Code version (must be 1.85.0+)
Run pnpm run compile to rebuild
Check the Output panel (View → Output → Parca Profiler) for errors

Migration from Previous Versions

If you previously used the extension with polarsignals.* settings, they will be automatically migrated to parca.* on first launch. Your API token will also be migrated to the new secret storage key.

License

Apache-2.0