Metadata-Version: 2.3
Name: jupyterlab_nvidia_nsight
Version: 0.6.0
Dynamic: Keywords
Summary: A JupyterLab extension for profiling cells execution using NVIDIA Nsight tools.
Project-URL: Homepage, https://pypi.org/project/jupyterlab-nvidia-nsight
Project-URL: Bug Tracker, https://forums.developer.nvidia.com/c/developer-tools/nsight-systems/profiling-linux-targets
Author-email: NVIDIA Corporation <devtools-support@nvidia.com>
License: NVIDIA Proprietary Software
License-File: License.txt
Classifier: Framework :: Jupyter
Classifier: Framework :: Jupyter :: JupyterLab
Classifier: Framework :: Jupyter :: JupyterLab :: 4
Classifier: Framework :: Jupyter :: JupyterLab :: Extensions
Classifier: Framework :: Jupyter :: JupyterLab :: Extensions :: Prebuilt
Classifier: License :: Other/Proprietary License
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.8
Requires-Dist: docker
Requires-Dist: jupyter-server<3,>=2.0.1
Provides-Extra: test
Requires-Dist: coverage; extra == 'test'
Requires-Dist: pytest; extra == 'test'
Requires-Dist: pytest-asyncio; extra == 'test'
Requires-Dist: pytest-cov; extra == 'test'
Requires-Dist: pytest-jupyter[server]>=0.6.0; extra == 'test'
Description-Content-Type: text/markdown

# 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

[![Demo](https://img.youtube.com/vi/YHloC_py1QM/maxresdefault.jpg)](https://www.youtube.com/embed/YHloC_py1QM)

## Requirements

- JupyterLab >= 4.0.0
- Docker (optional, for GUI support)
- [nvtx](https://pypi.org/project/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:

```bash
pip install jupyterlab-nvidia-nsight
```

- Install [Nsight Systems](https://developer.nvidia.com/nsight-systems) and/or [Nsight Compute](https://developer.nvidia.com/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](https://docs.nvidia.com/nsight-systems/UserGuide/index.html#gui-webrtc-container) by executing:

```bash
<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](https://developer.nvidia.com/nsight-systems).
- 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](https://developer.nvidia.com/nsight-compute).

#### 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:

```bash
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:

```bash
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:

```bash
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.
