Settings & Commands Reference

Complete reference for all ncprof settings, commands, and keyboard shortcuts.

VS Code Settings

Configure ncprof by opening Settings (Ctrl+, or Cmd+,) and searching for “ncprof”, or by editing your settings.json directly.

Profiler Settings

`ncprof.profiler.profileName`

Type: string
Default: .default

The name of the profile to use for tracepoint registrations.

Usage:

Allows organizing registrations into different profiles
Useful for separating regions by module, feature, or team member
Must be alphanumeric, underscore, or hyphen characters only

Example:


{
  "ncprof.profiler.profileName": "my_feature_profile"
}

Effect when changed:

Profile Regions view automatically refreshes to show the new profile
Editor decorations update to reflect regions in the new profile
New registrations are added to the new profile

`ncprof.profiler.profileType`

Type: string
Default: .default

The type identifier for the profiler being used.

Usage:

Distinguishes between different profiling frameworks (e.g., pytorch, tensorflow, custom)
Works in conjunction with profileName to organize configurations
Must be alphanumeric, underscore, or hyphen characters only

Example:


{
  "ncprof.profiler.profileType": "pytorch"
}

Configuration location:


.cache/ncompass/profiles/<profileName>/<profileType>/current/config.json

Effect when changed:

Profile Regions view refreshes
Editor decorations update
New registrations use the new type

Backend Settings

`ncprof.backend.autoStart`

Type: boolean
Default: false

Automatically start the Docker backend when VS Code activates the extension.

Usage:

Enable if you use ncprof frequently throughout your workday
Disable if you prefer manual control or want to conserve resources

Example:


{
  "ncprof.backend.autoStart": true
}

Notes:

Backend starts only if Docker is available
Failure to start doesn’t prevent extension activation
You can manually start/stop even with auto-start enabled

Complete settings.json Example


{
  "ncprof.profiler.profileName": "my_model",
  "ncprof.profiler.profileType": "pytorch",
  "ncprof.traceDirectory": "/home/user/my_project/traces",
  "ncprof.backend.autoStart": true
}

Note: User email is stored in globalState (not in settings.json) and can be changed using the “NCProf: Update User Email” command.

Commands

All commands are accessible via the Command Palette (Ctrl+Shift+P or Cmd+Shift+P).

Code Registration Commands

NCProf: Add Region to Profile

ID: ncprof.addRegionToProfile
Keyboard Shortcut: Ctrl+Alt+R (Windows/Linux), Cmd+Alt+R (Mac)

Registers the currently selected code as a tracepoint for profiling.

Prerequisites:

Text must be selected in the editor
Backend must be running
File must be in the workspace

Behavior:

Sends the selected region to the backend
Region appears in the Profile Regions view
Editor decorations are added at the registered lines
Success notification shows the region ID

Example workflow:

Select a function or code block
Press Ctrl+Alt+R
See confirmation notification

NCProf: Remove Profile Region

ID: ncprof.removeProfileRegion
Keyboard Shortcut: None (use context menu in Profile Regions view)

Removes a specific registered tracepoint from the current profile.

Usage:

Click on “Remove profile” CodeLens above highlighted tracepoints
Hover over a region in the Profile Regions view and click on “Remove profiles”

Effect:

Region is removed from the backend configuration
Profile Regions view updates
Editor decorations are cleared

NCProf: Clear All Profiler Registrations

ID: ncprof.clearAllRegistrations
Keyboard Shortcut: None

Removes all registered tracepoints for the current profile.

Warning: This action cannot be undone.

Effect:

All tracepoints are removed from the configuration
Profile Regions view becomes empty
All editor decorations are cleared

When to use:

Starting a fresh profiling session
Switching to a different profiling strategy
Cleaning up after experimentation

Backend Management Commands

NCProf: Start Profiler Backend (Docker)

ID: ncprof.startBackend
Keyboard Shortcut: None

Starts the Docker Compose backend infrastructure.

Prerequisites:

Docker and Docker Compose installed
Docker daemon running

Behavior:

Checks Docker availability
Pulls images if needed (first time only)
Creates .cache/ncompass directory

First-time start:

May take 2-5 minutes to pull images
Subsequent starts are much faster (~10 seconds)

NCProf: Stop Profiler Backend

ID: ncprof.stopBackend
Keyboard Shortcut: None

Stops all backend Docker containers.

Effect:

All containers are stopped
Data in .cache/ncompass is preserved
Resources are freed

Does not:

Delete registered tracepoints
Remove Docker images
Delete configuration files

NCProf: Restart Profiler Backend

ID: ncprof.restartBackend
Keyboard Shortcut: None

Stops and then starts the backend.

Equivalent to:

“NCProf: Stop Profiler Backend”
Wait for containers to stop
“NCProf: Start Profiler Backend (Docker)”

When to use:

After updating the extension
If the backend becomes unresponsive
To reload backend configuration changes

NCProf: Check NCProf Backend Status

ID: ncprof.checkBackendStatus
Keyboard Shortcut: None

Displays the status of all backend containers.

Output shows:

Container names
Current status (running/stopped)
Health status
Port mappings
Uptime

Example output:


NAME                    STATUS
nc-ncprof-redis         Up 5 minutes
nc-ncprof-server        Up 5 minutes (healthy)
nc-ncprof-register      Up 5 minutes (healthy)

Use to troubleshoot:

Backend connection issues
Container health problems
Port conflicts

Trace Viewer Commands

NCProf: Open GPU Trace

ID: ncprof.openTrace
Keyboard Shortcut: None

Opens a trace file in the integrated Perfetto viewer.

Supported formats:

.json - Chrome trace format
.json.gz - Compressed traces (automatically extracted)

Usage:

Execute command
Select trace file from file picker
Trace opens in Perfetto viewer

Alternative:

Right-click trace file → “Open With…” → “GPU Trace Viewer”

Configuration Commands

NCProf: Change Trace Directory

ID: ncprof.changeTraceDirectory
Keyboard Shortcut: None

Changes the directory where traces are stored/accessed.

Behavior:

Opens a folder picker dialog
Updates ncprof.traceDirectory setting
Directory is passed to backend as USER_TRACE_DIR

When to use:

Moving trace files to a different location
Working on a different project
Initial setup if you skipped the prompt

NCProf: Update User Email

ID: ncprof.updateUserEmail
Keyboard Shortcut: None

Updates the user email used for crash logging and analytics.

Behavior:

Prompts for a new email address
Validates email format
Stores in VS Code globalState (not in settings.json)

Usage:

Update email for crash report tracking
Correct a mistyped email from initial setup

Note: Email is required for backend operations and stored separately from workspace settings.

View Commands

NCProf: Refresh Profile Regions

ID: ncprof.refreshProfileRegions
Keyboard Shortcut: None

Manually refreshes the Profile Regions view.

When to use:

If view doesn’t update automatically
After changing profile settings

Note: The view usually updates automatically when you:

Register a new tracepoint
Remove a tracepoint
Change profileName or profileType settings

Next Steps

Detailed breakdown of profiling workflow: Learn how to use these commands in practice
Managing the Backend: Deep dive into backend management