| Name | jupyter-resource-usage JSON |
| Version |
1.1.1
JSON |
| download |
| home_page | None |
| Summary | Jupyter Extension to show resource usage |
| upload_time | 2025-02-04 13:13:27 |
| maintainer | None |
| docs_url | None |
| author | Jupyter Development Team |
| requires_python | >=3.8 |
| license | Copyright (c) 2016, Yuvi Panda
All rights reserved.
Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are met:
* Redistributions of source code must retain the above copyright notice, this
list of conditions and the following disclaimer.
* Redistributions in binary form must reproduce the above copyright notice,
this list of conditions and the following disclaimer in the documentation
and/or other materials provided with the distribution.
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. |
| keywords |
ipython
jupyter
jupyterlab
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
|
| coveralls test coverage |
No coveralls.
|
**[Installation](#installation)** |
**[Configuration](#configuration)** |
**[Resources Displayed](#resources-displayed)** |
**[Contributing](#contributing)**
# jupyter-resource-usage
[](https://mybinder.org/v2/gh/jupyter-server/jupyter-resource-usage/main)
[](https://pypi.python.org/pypi/jupyter-resource-usage)
[](https://anaconda.org/conda-forge/jupyter-resource-usage)
[](https://pypi.python.org/pypi/jupyter-resource-usage)
[](https://github.com/jupyter-server/jupyter-resource-usage/issues)
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
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.
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:
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
### 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
```
Or with `conda`:
```bash
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.
```
jupyter serverextension enable --py jupyter_resource_usage --sys-prefix
jupyter nbextension install --py jupyter_resource_usage --sys-prefix
jupyter nbextension enable --py jupyter_resource_usage --sys-prefix
```
## Configuration
### Memory Limit
`jupyter-resource-usage` can display a memory limit (but not enforce it). You can set this
in several ways:
1. `MEM_LIMIT` environment variable. This is set by [JupyterHub](https://github.com/jupyterhub/jupyterhub/)
if using a spawner that supports it.
2. In the commandline when starting `jupyter notebook`, as `--ResourceUseDisplay.mem_limit`.
3. In your Jupyter notebook [traitlets](https://traitlets.readthedocs.io/en/stable/) config file
The limit needs to be set as an integer in Bytes.
### Memory usage warning threshold
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.
If you want to flash the warning to the user when they are within 10% of the memory limit, you
can set the parameter `--ResourceUseDisplay.mem_warning_threshold=0.1`.
### Host information
If you want to hide host information from the Kernel Usage sidebar
you can set `--ResourceUseDisplay.show_host_usage=False` to hide `Host CPU` and `Host Virtual Memory` information.
The default is set as `True`, i.e. show all the information.
### CPU Usage
`jupyter-resource-usage` can also track CPU usage and report a `cpu_percent` value as part of the `/api/metrics/v1` response.
You can set the `cpu_limit` in several ways:
1. `CPU_LIMIT` environment variable. This is set by [JupyterHub](https://github.com/jupyterhub/jupyterhub/)
if using a spawner that supports it.
2. In the command line when starting `jupyter notebook`, as `--ResourceUseDisplay.cpu_limit`.
3. In your Jupyter notebook [traitlets](https://traitlets.readthedocs.io/en/stable/) config file
The limit corresponds to the number of cpus the user has access to, but does not enforce it.
Additionally, you can set the `track_cpu_percent` trait to enable CPU usage tracking (disabled by default):
```python
c = get_config()
c.ResourceUseDisplay.track_cpu_percent = True
```
As a command line argument:
```bash
jupyter notebook --ResourceUseDisplay.track_cpu_percent=True
```
When `track_cpu_percent` is set to `True`, status will report CPU utilisation along with
memory:
### Disk [partition] Usage
`jupyter-resource-usage` can also track disk usage [of a defined partition] and report the `total` and `used` values as part of the `/api/metrics/v1` response.
You enable tracking by setting the `track_disk_usage` trait (disabled by default):
```python
c = get_config()
c.ResourceUseDisplay.track_disk_usage = True
```
The values are from the partition containing the folder in the trait `disk_path` (which defaults to `/home/jovyan`). If this path does not exist, disk usage information is omitted from the display.
Mirroring CPU and Memory, the trait `disk_warning_threshold` signifies when to flag a usage warning, and like the others, it defaults to `0.1` (10% remaining)
### Disable Prometheus Metrics
There is a [known bug](https://github.com/jupyter-server/jupyter-resource-usage/issues/123) with Prometheus metrics which
causes "lag"/pauses in the UI. To workaround this you can disable Prometheus metric reporting using:
```
--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
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.
(The vertical bars are included by default, to help separate the three indicators.)
## Resources Displayed
Currently the server extension reports disk usage, memory usage and CPU usage. Other metrics will be added in the future as needed.
Memory usage will show the PSS whenever possible (Linux only feature), and default to RSS otherwise.
The notebook extension currently doesn't show CPU usage, only memory usage.
## Contributing
If you would like to contribute to the project, please read the [`CONTRIBUTING.md`](CONTRIBUTING.md). The `CONTRIBUTING.md` file
explains how to set up a development installation and how to run the test suite.
Raw data
{
"_id": null,
"home_page": null,
"name": "jupyter-resource-usage",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "IPython, Jupyter, JupyterLab",
"author": "Jupyter Development Team",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/1b/03/e5fa16040408b5c33adb870e82f380dcb7fbdb16bcf61d6bc46f2b58e415/jupyter_resource_usage-1.1.1.tar.gz",
"platform": null,
"description": "**[Installation](#installation)** |\n**[Configuration](#configuration)** |\n**[Resources Displayed](#resources-displayed)** |\n**[Contributing](#contributing)**\n\n# jupyter-resource-usage\n\n\n[](https://mybinder.org/v2/gh/jupyter-server/jupyter-resource-usage/main)\n[](https://pypi.python.org/pypi/jupyter-resource-usage)\n[](https://anaconda.org/conda-forge/jupyter-resource-usage)\n[](https://pypi.python.org/pypi/jupyter-resource-usage)\n[](https://github.com/jupyter-server/jupyter-resource-usage/issues)\n\n\n\nJupyter Resource Usage is an extension for Jupyter Notebooks and JupyterLab that\ndisplays an indication of how much resources your current notebook server and\nits children (kernels, terminals, etc) are using. This is displayed in the\nstatus bar in the JupyterLab and notebook, refreshing every 5s.\n\nKernel resource usage can be displayed in a sidebar for IPython kernels with\n[ipykernel](https://github.com/ipython/ipykernel) >= 6.11.0.\n\n\n\nThe kernel usage is available for Notebook 7.x too which can be enabled at\n`View -> Right Sidebar -> Show Kernel Usage`. In the case of JupyterLab interface, it is\nenough to click `tachometer` icon on the right sidebar.\n\nThe package provides an alternative frontend for the `jupyter-resource-usage` metrics:\n\n\n\nPreviously, this extension used to be distributed with\n[jupyterlab-system-monitor](https://github.com/jtpio/jupyterlab-system-monitor) package.\nStarting from `1.0.0`, the alternative frontend has been integrated into the\ncurrent repository. Check [Alternative frontend](#enable-alternative-frontend) section\non how to enable and configure this alternative frontend.\n\n**Note** that for JupyterLab 3.x and 2.x, users should install the alternative frontend\nfrom [jupyterlab-system-monitor](https://github.com/jtpio/jupyterlab-system-monitor).\n\n## Installation\n\n### JupyterLab 4.x and Notebook 7.x\n\nYou should install the latest version `>=1.0.0` for JupyterLab 4 compatability.\n\n```bash\npip install jupyter-resource-usage\n```\n\nOr with `conda`:\n\n```bash\nconda install -c conda-forge jupyter-resource-usage\n```\n\n### JupyterLab 3.x and Notebook 6.x\n\nYou should pin the versions to `<1.0.0`\n\n```bash\npip install 'jupyter-resource-usage<1.0.0'\n```\n\nOr with `conda`:\n\n```bash\nconda install -c conda-forge 'jupyter-resource-usage<1.0.0'\n```\n\n**If your notebook version is < 5.3**, you need to enable the extension manually.\n\n```\njupyter serverextension enable --py jupyter_resource_usage --sys-prefix\njupyter nbextension install --py jupyter_resource_usage --sys-prefix\njupyter nbextension enable --py jupyter_resource_usage --sys-prefix\n```\n\n## Configuration\n\n### Memory Limit\n\n`jupyter-resource-usage` can display a memory limit (but not enforce it). You can set this\nin several ways:\n\n1. `MEM_LIMIT` environment variable. This is set by [JupyterHub](https://github.com/jupyterhub/jupyterhub/)\n if using a spawner that supports it.\n2. In the commandline when starting `jupyter notebook`, as `--ResourceUseDisplay.mem_limit`.\n3. In your Jupyter notebook [traitlets](https://traitlets.readthedocs.io/en/stable/) config file\n\nThe limit needs to be set as an integer in Bytes.\n\n### Memory usage warning threshold\n\n\n\nThe background of the resource display can be changed to red when the user is near a memory limit.\nThe threshold for this warning can be configured as a fraction of the memory limit.\n\nIf you want to flash the warning to the user when they are within 10% of the memory limit, you\ncan set the parameter `--ResourceUseDisplay.mem_warning_threshold=0.1`.\n\n### Host information\n\nIf you want to hide host information from the Kernel Usage sidebar\nyou can set `--ResourceUseDisplay.show_host_usage=False` to hide `Host CPU` and `Host Virtual Memory` information.\nThe default is set as `True`, i.e. show all the information.\n\n\n\n### CPU Usage\n\n`jupyter-resource-usage` can also track CPU usage and report a `cpu_percent` value as part of the `/api/metrics/v1` response.\n\nYou can set the `cpu_limit` in several ways:\n\n1. `CPU_LIMIT` environment variable. This is set by [JupyterHub](https://github.com/jupyterhub/jupyterhub/)\n if using a spawner that supports it.\n2. In the command line when starting `jupyter notebook`, as `--ResourceUseDisplay.cpu_limit`.\n3. In your Jupyter notebook [traitlets](https://traitlets.readthedocs.io/en/stable/) config file\n\nThe limit corresponds to the number of cpus the user has access to, but does not enforce it.\n\nAdditionally, you can set the `track_cpu_percent` trait to enable CPU usage tracking (disabled by default):\n\n```python\nc = get_config()\nc.ResourceUseDisplay.track_cpu_percent = True\n```\n\nAs a command line argument:\n\n```bash\njupyter notebook --ResourceUseDisplay.track_cpu_percent=True\n```\n\nWhen `track_cpu_percent` is set to `True`, status will report CPU utilisation along with\nmemory:\n\n\n\n### Disk [partition] Usage\n\n`jupyter-resource-usage` can also track disk usage [of a defined partition] and report the `total` and `used` values as part of the `/api/metrics/v1` response.\n\nYou enable tracking by setting the `track_disk_usage` trait (disabled by default):\n\n```python\nc = get_config()\nc.ResourceUseDisplay.track_disk_usage = True\n```\n\nThe values are from the partition containing the folder in the trait `disk_path` (which defaults to `/home/jovyan`). If this path does not exist, disk usage information is omitted from the display.\n\nMirroring CPU and Memory, the trait `disk_warning_threshold` signifies when to flag a usage warning, and like the others, it defaults to `0.1` (10% remaining)\n\n\n\n### Disable Prometheus Metrics\n\nThere is a [known bug](https://github.com/jupyter-server/jupyter-resource-usage/issues/123) with Prometheus metrics which\ncauses \"lag\"/pauses in the UI. To workaround this you can disable Prometheus metric reporting using:\n\n```\n--ResourceUseDisplay.enable_prometheus_metrics=False\n```\n\n## Enable alternative frontend\n\nBy default, the alternative frontend is disabled. To enable it, users should go to\n`Settings -> Settings Editor -> Resource Usage Indicator` which will render following\nform\n\n\n\nBy checking \"Enable resource usage indicators\" and refreshing the browser tab will\nrender the alternative frontend in the topbar.\n\nUsers can change the label and refresh rate for the alternative frontend using settings\neditor.\n\n(The vertical bars are included by default, to help separate the three indicators.)\n\n## Resources Displayed\n\nCurrently the server extension reports disk usage, memory usage and CPU usage. Other metrics will be added in the future as needed.\n\nMemory usage will show the PSS whenever possible (Linux only feature), and default to RSS otherwise.\n\nThe notebook extension currently doesn't show CPU usage, only memory usage.\n\n## Contributing\n\nIf you would like to contribute to the project, please read the [`CONTRIBUTING.md`](CONTRIBUTING.md). The `CONTRIBUTING.md` file\nexplains how to set up a development installation and how to run the test suite.\n",
"bugtrack_url": null,
"license": "Copyright (c) 2016, Yuvi Panda\n All rights reserved.\n \n Redistribution and use in source and binary forms, with or without\n modification, are permitted provided that the following conditions are met:\n \n * Redistributions of source code must retain the above copyright notice, this\n list of conditions and the following disclaimer.\n \n * Redistributions in binary form must reproduce the above copyright notice,\n this list of conditions and the following disclaimer in the documentation\n and/or other materials provided with the distribution.\n \n THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS \"AS IS\"\n AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE\n IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE\n DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE\n FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL\n DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR\n SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER\n CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,\n OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE\n OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.",
"summary": "Jupyter Extension to show resource usage",
"version": "1.1.1",
"project_urls": {
"Homepage": "https://github.com/jupyter-server/jupyter-resource-usage"
},
"split_keywords": [
"ipython",
" jupyter",
" jupyterlab"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "5a805a1162f784142988bbdfed16afa4354eadd1710148a0d4f7619fdafbfbd1",
"md5": "e9471183f101472dd2141d4c52c6f5c4",
"sha256": "1f163b51b1960801c84d01753907be695e4b23e6ce3f3291f6b03cab09cc438d"
},
"downloads": -1,
"filename": "jupyter_resource_usage-1.1.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "e9471183f101472dd2141d4c52c6f5c4",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 48247,
"upload_time": "2025-02-04T13:13:24",
"upload_time_iso_8601": "2025-02-04T13:13:24.782349Z",
"url": "https://files.pythonhosted.org/packages/5a/80/5a1162f784142988bbdfed16afa4354eadd1710148a0d4f7619fdafbfbd1/jupyter_resource_usage-1.1.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "1b03e5fa16040408b5c33adb870e82f380dcb7fbdb16bcf61d6bc46f2b58e415",
"md5": "6f3b10d286f7c366ee4e7a241d6f3b91",
"sha256": "f7a3451caec9f5e6343f60b0a8e4034652138df65ece7a9153242115845f9bbb"
},
"downloads": -1,
"filename": "jupyter_resource_usage-1.1.1.tar.gz",
"has_sig": false,
"md5_digest": "6f3b10d286f7c366ee4e7a241d6f3b91",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 434317,
"upload_time": "2025-02-04T13:13:27",
"upload_time_iso_8601": "2025-02-04T13:13:27.622754Z",
"url": "https://files.pythonhosted.org/packages/1b/03/e5fa16040408b5c33adb870e82f380dcb7fbdb16bcf61d6bc46f2b58e415/jupyter_resource_usage-1.1.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-02-04 13:13:27",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "jupyter-server",
"github_project": "jupyter-resource-usage",
"travis_ci": true,
"coveralls": false,
"github_actions": true,
"lcname": "jupyter-resource-usage"
}
