NVIDIA Nsight Tools JupyterLab Extension

A JupyterLab extension for profiling cells execution using NVIDIA Nsight tools.

Demo

Click on the image to launch the video

Requirements

• JupyterLab >= 4.0.0
• Docker (optional, for GUI support)
• nvtx (Required for Nsight Compute support)

Nsight tools are not shipped with this extension. The required tool(s) should be installed separately on the JupyterLab server machine.

Install and setup

• To install the extension, execute:

pip install jupyterlab-nvidia-nsight

• Install Nsight Systems and/or Nsight Compute (these tools are not shipped with this extension).

• Set Nsight Systems and/or Nsight Compute installation location in the extension settings.

  • Example: If Nsight Systems installation location is set to /opt/nvidia/nsight-systems/<version>, then the extension will look for nsys executable in /opt/nvidia/nsight-systems/<version>/target-linux-x64
  • If not set, PATH environment variable should contain the locations of the tool's executables.

Profile JupyterLab cells

1. Enable Nsight tool by using the Profiling with Nsight Systems/Compute... command under the NVIDIA Nsight menu, or by using the command palette.
   • Note: This operation restarts the JupyterLab kernel.
2. Profile cells execution by using the Run and profile selected cells... command.
3. The cell's profiling info is displayed in the cell output area.

Analyzing the profile session in Nsight tools GUI

• GUI display is disabled by default. To use Nsight Systems GUI for analysis of report files, check the Enable Nsight Systems UI checkbox in the extension settings.
• Open Nsight tools report files in a tab inside JupyterLab.
• Display of Nsight tools GUI requires a WebRTC docker image. Build the GUI WebRTC docker image by executing:

<nsys_install_dir>/host-linux-x64/Scripts/WebRTCContainer/build.sh

Supported Tools

Nsight Systems

• Supports Nsight Systems release 2024.1.1 or later. It is recommended to use the latest release.
• Use --stats=true when profiling cells execution to see textual output of nsys stats.

List of NSYS CLI flags that can't be used within the extension:

• --help, -h
• --hotkey-capture
• --output, -o
• --session-new
• --session
• --stop-on-exit, -x

Nsight Compute

• Supports Nsight Compute release 2024.3 or later. It is recommended to use the latest release.

List of NCU CLI flags that can't be used within the extension:

• --app-replay-buffer
• --app-replay-match
• --app-replay-mode
• --check-exit-code
• --chips
• --config-file-path
• --config-file
• --export, -o
• --force-overwrite, -f
• --help, -h
• --hostname
• --import, -i
• --kill
• --list-chips
• --list-metrics
• --list-rules
• --list-sections
• --list-sets
• --log-file
• --mode
• --null-stdin
• --open-in-ui
• --profile-from-start
• --query-metrics-collection
• --query-metrics-mode
• --query-metrics
• --quiet
• --range-filter
• --range-replay-options
• --rename-kernels-export
• --replay-mode
• --section-folder-restore
• --version, -v

List of NCU CLI flags that can be used only when enabling NCU:

• --apply-rules
• --cache-control
• --call-stack-type
• --call-stack
• --clock-control
• --disable-profiler-start-stop
• --graph-profiling
• --import-source
• --injection-path-32
• --injection-path-64
• --max-connections
• --metrics
• --pm-sampling-buffer-size
• --pm-sampling-interval
• --pm-sampling-max-passes
• --port, -p
• --preload-library
• --rule
• --section-folder-recursive
• --section-folder
• --section
• --set
• --source-folders
• --support-32bit
• --target-processes-filter
• --target-processes
• --verbose
• --warp-sampling-buffer-size
• --warp-sampling-interval
• --warp-sampling-max-passes

List of NCU CLI flags that can be used only when profiling cells:

• --csv
• --devices
• --disable-extra-suffixes
• --filter-mode
• --kernel-id
• --kernel-name-base
• --kernel-name, -k
• --launch-count, -c
• --launch-skip-before-match
• --launch-skip, -s
• --nvtx-exclude
• --nvtx-include
• --page
• --print-details
• --print-fp
• --print-kernel-base
• --print-metric-attribution
• --print-metric-instances
• --print-metric-name
• --print-nvtx-rename
• --print-rule-details
• --print-source
• --print-summary
• --print-units
• --rename-kernels-path
• --rename-kernels
• --resolve-source-file

Uninstall

To remove the extension, execute:

pip uninstall jupyterlab-nvidia-nsight

Troubleshooting

If you are seeing the frontend extension, but it is not working, check that the server extension is enabled:

jupyter server extension list

If the server extension is installed and enabled, but you are not seeing the frontend extension, check the frontend extension is installed:

jupyter labextension list

Known Issues

• While Nsight Compute is enabled, interrupting the JupyterLab kernel with the "Interrupt Kernel" command (by using the command palette, kernel menu or the stop-button) causes the kernel to terminate and restart.

Release Notes

0.6.0

• Support displaying Nsight Compute UI inside JupyterLab.
• Fix keyboard interaction with Nsight tools UI.

0.5.2

• Added Nsight Compute section in the project description.
• Verify server connection on extension load.

0.5.1

• Initial release.