Metadata-Version: 2.4
Name: jupyterlab_nvidia_nsight
Version: 0.7.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

- Open Nsight tools report files in a tab inside JupyterLab.
- Display of Nsight tools GUI requires [NVIDIA Nsight Streamer](https://catalog.ngc.nvidia.com/orgs/nvidia/teams/devtools/resources/nsight-streamer-resources).
- When JupyterLab is running inside a Docker container, displaying Nsight tools UI requires to have
  the Docker daemon socket mounted
  (i.e., `docker run -v /var/run/docker.sock:/var/run/docker.sock ...`).

  - **SECURITY ALERT:** The Docker daemon socket should not be mounted when using untrusted sources,
    as it may provide root access to the host system.
  - See also [Docker Example](#docker-example).

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

## Docker Example

This example demonstrates how to use the extension in a [Jupyter Docker Stacks](https://jupyter-docker-stacks.readthedocs.io/en/latest/) image.

The following Dockerfile defines a Docker image based on `pytorch-notebook` with cuda12,
and includes the extension and cuda-toolkit.\
**It is recommended to use the latest cuda-toolkit** - https://developer.nvidia.com/cuda-downloads

```dockerfile
FROM quay.io/jupyter/pytorch-notebook:cuda12-python-3.11.8

# Install cuda-tookit
ADD https://developer.download.nvidia.com/compute/cuda/repos/ubuntu2404/x86_64/cuda-keyring_1.1-1_all.deb /tmp/
USER root
RUN dpkg -i /tmp/cuda-keyring_1.1-1_all.deb && apt-get -y update && \
    apt-get -y install cuda-toolkit-12-8
USER ${NB_UID}

# Install jupyterlab-nvidia-nsight and set the default settings
ARG HOST_IP
RUN pip install --no-cache-dir jupyterlab-nvidia-nsight nvtx && \
    fix-permissions "${CONDA_DIR}" && fix-permissions "/home/${NB_USER}" && \
    mkdir -p /home/${NB_USER}/.jupyter/lab/user-settings/jupyterlab-nvidia-nsight && echo ' \
{ \
    "ui": { \
        "enabled": true, \
        "suppressServerAddressWarning": true, \
        "dockerHost": "'"$HOST_IP"'" \
    }, \
    "nsys": { \
        "installationPath": "/opt/nvidia/nsight-systems/2024.6.2", \
        "args": "--trace=cuda,nvtx,osrt --python-sampling=true --python-backtrace=cuda --cudabacktrace=all" \
    }, \
    "ncu": { \
        "installationPath": "/opt/nvidia/nsight-compute/2025.1.1" \
    } \
}' > /home/${NB_USER}/.jupyter/lab/user-settings/jupyterlab-nvidia-nsight/plugin.jupyterlab-settings
```

Build the image:

```bash
docker build --rm --tag <your-image-name> --build-arg HOST_IP="$(hostname -i | cut -d' ' -f1)" .
```

Run the container:

```bash
# SECURITY ALERT: Remove `-v /var/run/docker.sock:/var/run/docker.sock` when using untrusted sources
docker run -it --rm --group-add $(getent group docker | cut -d: -f3) --runtime=nvidia -p 8888:8888 -v /var/run/docker.sock:/var/run/docker.sock <your-image-name>
```

Note: Using `--runtime=nvidia` requires [NVIDIA Container Toolkit](https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/latest/).

## 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.7.0

- New setting for configuring the location of the generated reports.
- Support displaying Nsight UI when running inside a docker container.
- Use (and pull if required) the latest NVIDIA Nsight Streamer for displaying Nsight UI.
  - See [Nsight Streamer for Nsight Systems](https://catalog.ngc.nvidia.com/orgs/nvidia/teams/devtools/containers/nsight-streamer-nsys) and [Nsight Streamer for Nsight Compute](https://catalog.ngc.nvidia.com/orgs/nvidia/teams/devtools/containers/nsight-streamer-ncu).
- Support displaying an external WebRTC streamer.

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