Skip to content

Update README and fix settings file #205

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 4 commits into from
Jul 26, 2023
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
62 changes: 58 additions & 4 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -12,19 +12,40 @@
[![PyPI](https://img.shields.io/pypi/l/jupyter-resource-usage)](https://pypi.python.org/pypi/jupyter-resource-usage)
[![GitHub](https://img.shields.io/badge/issue_tracking-github-blue?logo=github)](https://github.com/jupyter-server/jupyter-resource-usage/issues)

![Screenshot with memory limit](screenshot.png)
![Screenshot with memory limit](./doc/statusbar.png)

Jupyter Resource Usage is an extension for Jupyter Notebooks and JupyterLab that
displays an indication of how much resources your current notebook server and
its children (kernels, terminals, etc) are using. This is displayed in the
main toolbar in the notebook itself, refreshing every 5s.
status bar in the JupyterLab and notebook, refreshing every 5s.

Kernel resource usage can be displayed in a sidebar for IPython kernels with
[ipykernel](https://github.com/ipython/ipykernel) >= 6.11.0.

![Screenshot for kernel usage](./doc/kernel-usage.png)

The kernel usage is available for Notebook 7.x too which can be enabled at
`View -> Right Sidebar -> Show Kernel Usage`. In the case of JupyterLab interface, it is
enough to click `tachometer` icon on the right sidebar.

The package provides an alternative frontend for the `jupyter-resource-usage` metrics:

![screencast](./doc/topbar.gif)

Previously, this extension used to be distributed with
[jupyterlab-system-monitor](https://github.com/jtpio/jupyterlab-system-monitor) package.
Starting from `1.0.0`, the alternative frontend has been integrated into the
current repository. Check [Alternative frontend](#enable-alternative-frontend) section
on how to enable and configure this alternative frontend.

**Note** that for JupyterLab 3.x and 2.x, users should install the alternative frontend
from [jupyterlab-system-monitor](https://github.com/jtpio/jupyterlab-system-monitor).

## Installation

You can currently install this package from PyPI.
### JupyterLab 4.x and Notebook 7.x

You should install the latest version `>=1.0.0` for JupyterLab 4 compatability.

```bash
pip install jupyter-resource-usage
Expand All @@ -36,6 +57,20 @@ Or with `conda`:
conda install -c conda-forge jupyter-resource-usage
```

### JupyterLab 3.x and Notebook 6.x

You should pin the versions to `<1.0.0`

```bash
pip install 'jupyter-resource-usage<1.0.0'
```

Or with `conda`:

```bash
conda install -c conda-forge 'jupyter-resource-usage<1.0.0'
```

**If your notebook version is < 5.3**, you need to enable the extension manually.

```
Expand All @@ -60,7 +95,7 @@ The limit needs to be set as an integer in Bytes.

### Memory usage warning threshold

![Screenshot with memory warning](warn-screenshot.png)
![Screenshot with memory warning](./doc/statusbar-warn.png)

The background of the resource display can be changed to red when the user is near a memory limit.
The threshold for this warning can be configured as a fraction of the memory limit.
Expand Down Expand Up @@ -94,6 +129,11 @@ As a command line argument:
jupyter notebook --ResourceUseDisplay.track_cpu_percent=True
```

When `track_cpu_percent` is set to `True`, status will report CPU utilisation along with
memory:

![Screenshot with CPU and memory](./doc/statusbar-cpu.png)

### Disable Prometheus Metrics

There is a [known bug](https://github.com/jupyter-server/jupyter-resource-usage/issues/123) with Prometheus metrics which
Expand All @@ -103,6 +143,20 @@ causes "lag"/pauses in the UI. To workaround this you can disable Prometheus met
--ResourceUseDisplay.enable_prometheus_metrics=False
```

## Enable alternative frontend

By default, the alternative frontend is disabled. To enable it, users should go to
`Settings -> Settings Editor -> Resource Usage Indicator` which will render following
form

![jupyterlab_setting](./doc/settings.png)

By checking "Enable resource usage indicators" and refreshing the browser tab will
render the alternative frontend in the topbar.

Users can change the label and refresh rate for the alternative frontend using settings
editor.

## Resources Displayed

Currently the server extension only reports memory usage and CPU usage. Other metrics will be added in the future as needed.
Expand Down
Binary file added doc/kernel-usage.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added doc/settings.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added doc/statusbar-cpu.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added doc/statusbar-warn.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added doc/statusbar.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added doc/topbar.gif
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
36 changes: 28 additions & 8 deletions packages/labextension/schema/topbar-item.json
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
{
"title": "Resource Usage Menu Bar",
"description": "Resource Usage Menu Bar settings.",
"title": "Resource Usage Indicator",
"description": "Resource Usage Indicator settings.",
"jupyter.lab.toolbars": {
"TopBar": [
{
Expand All @@ -15,8 +15,8 @@
},
"properties": {
"enable": {
"title": "Enable resource usage panels",
"description": "Whether to enable resource usage panels on topbar",
"title": "Enable resource usage indicators",
"description": "Whether to enable resource usage indicators on topbar",
"default": false,
"type": "boolean"
},
Expand All @@ -29,20 +29,40 @@
"memory": {
"title": "Memory Settings",
"description": "Settings for the memory indicator",
"$ref": "#/definitions/memory",
"default": {
"label": "Mem: "
},
"type": "object"
}
},
"cpu": {
"title": "CPU Settings",
"description": "Settings for the CPU indicator",
"$ref": "#/definitions/cpu",
"default": {
"label": "CPU: "
},
"type": "object"
}
}
},
"additionalProperties": false,
"definitions": {
"memory": {
"type": "object",
"properties": {
"label": {
"type": "string",
"description": "Label for the memory indicator"
}
}
},
"cpu": {
"type": "object",
"properties": {
"label": {
"type": "string",
"description": "Label for the cpu indicator"
}
}
}
},
"type": "object"
}
Binary file removed screenshot.png
Binary file not shown.
Binary file removed warn-screenshot.png
Binary file not shown.