# SmartDashboard
SmartDashboard is an add-on to SmartSim that provides a dashboard to help users understand and monitor their SmartSim experiments in a visual way. Configuration, status, and logs are available for all launched entities within an experiment for easy inspection, along with memory and client data per shard for launched orchestrators.
A ``Telemetry Monitor`` is a background process that is launched alongside the experiment.
It is responsible for generating the data displayed by SmartDashboard. The ``Telemetry Monitor`` can be disabled globally by
adding ``export SMARTSIM_FLAG_TELEMETRY=0`` as an environment variable. When disabled, SmartDashboard
will not display entity status data. To re-enable, set the ``SMARTSIM_FLAG_TELEMETRY`` environment variable to ``1``
with ``export SMARTSIM_FLAG_TELEMETRY=1``. For workflows involving multiple experiments, SmartSim provides the attributes
``Experiment.telemetry.enable`` and ``Experiment.telemetry.disable`` to manage the enabling or disabling of telemetry on a per-experiment basis.
`Orchestrator` memory and client data can be collected by enabling database telemetry. To do so, add ``Orchestrator.telemetry.enable``
after creating an `Orchestrator` within the driver script. Database telemetry is enabled per `Orchestrator`, so if there are multiple
`Orchestrators` launched, they will each need to be enabled separately in the driver script.
```python
# enabling telemetry example
from smartsim import Experiment
exp = Experiment("experiment", launcher="auto")
exp.telemetry.enable()
db = exp.create_database(db_nodes=3)
db.telemetry.enable()
exp.start(db, block=True)
exp.stop(db)
```
Experiment metadata is stored in the ``.smartsim`` directory, a hidden folder used by the internal api and accessed by the dashboard.
This folder can be found within the created experiment directory.
Deletion of the experiment folder will remove all associated metadata.
## Installation
It's important to note that SmartDashboard only works while using SmartSim, so SmartSim will need to be installed as well.
SmartSim installation docs can be found [here](https://www.craylabs.org/docs/installation_instructions/basic.html).
### User Install
Run `pip install smartdashboard` to install SmartDashboard without cloning the repository.
### Developer Install
Clone the `SmartDashboard` repository at https://github.com/CrayLabs/SmartDashboard.git
Once cloned, `cd` into the repository and run:
```pip install -e .```
## Running SmartDashboard
After launching a SmartSim experiment, the dashboard can be launched using SmartSim's CLI.
```smart dashboard --port <port number> --directory <experiment directory path>```
The port can optionally be specified, otherwise the dashboard port will default to `8501`.
The directory must be specified and should be a relative or absolute path to the created experiment directory.
Example workflow:
```bash
# directory before running experiment
├── hello_world.py
```
```python
# hello_world.py
from smartsim import Experiment
exp = Experiment("hello_world_exp", launcher="auto")
exp.telemetry.enable()
run = exp.create_run_settings(exe="echo", exe_args="Hello World!")
run.set_tasks(60)
run.set_tasks_per_node(20)
model = exp.create_model("hello_world", run)
exp.start(model, block=True, summary=True)
```
```bash
# in interactive terminal
python hello_world.py
```
```bash
# directory after running experiment
├── hello_world.py
└── hello_world_exp
```
By default, `hello_world_exp` is created in the directory of the driver script.
```bash
# in a different interactive terminal
smart dashboard --port 8888 --directory hello_world_exp
```
The dashboard will automatically open in a browser at port 8888 when `smart dashboard ...`
is invoked locally.
> If the dashboard is executed remotely, establishing port-forwarding to the
> remote machine will be necessary. This may be accomplished with ssh as follows:
>
> ```bash
> # using ssh to establish port forwarding
> ssh -L [local-addr]:<local-port>:<remote-addr>:<remote-port> <user-id>@<remote-addr>
> # example forwarding the remote port 8888 to localhost:8000
> ssh -L localhost:8000:super1.my.domain.net:8888 smartdash@super1.my.domain.net
> ```
>
> After establishing the port-forwarding, a local browser can be pointed at the appropriate
> URL, such as `http://localhost:8000` for the example above.
The dashboard is also persistent, meaning that a user can still launch and use the dashboard even after the experiment has completed.
## Using SmartDashboard
Once the dashboard is launched, a browser will open to `http://localhost:<port>`. SmartDashboard currently has two tabs on the left hand side.
`Experiment Overview:` This tab is where configuration information, statuses, and logs are located for each launched entity of the experiment. The `Experiment` section displays configuration information for the overall experiment and its logs. In the `Applications` section, also known as SmartSim `Models`, select a launched application to see its status, what it was configured with, and its logs. The `Orchestrators` section also provides configuration and status information, as well as logs per shard for a selected orchestrator. Finally, in the `Ensembles` section, select an ensemble to see its status and configuration. Then select any of its members to see its status, configuration, and logs.
`Database Telemetry:` This tab provides additional details about `Orchestrators`.
The `Orchestrator Summary` section shows configuration and status information of the selected. The `Memory`
section provides memory usage data per shard within the `Orchestrator`. The `Clients`
section displays client data per shard within the `Orchestrator`.
`Help:` This tab links to SmartSim documentation and provides a SmartSim contact for support.
Raw data
{
"_id": null,
"home_page": null,
"name": "smartdashboard",
"maintainer": null,
"docs_url": null,
"requires_python": "<3.12,>=3.9",
"maintainer_email": null,
"keywords": "scientific, ai, workflow, hpc, analysis",
"author": null,
"author_email": "\"CrayLabs: a Hewlett Packard Enterprise OSS Organization\" <craylabs@hpe.com>",
"download_url": "https://files.pythonhosted.org/packages/c5/6b/b1fdd69ccbdaa5ccf7721c9f1c6d020b2a8f5b0b6643ede76729d9feccf6/smartdashboard-0.0.4.tar.gz",
"platform": null,
"description": "# SmartDashboard\n\nSmartDashboard is an add-on to SmartSim that provides a dashboard to help users understand and monitor their SmartSim experiments in a visual way. Configuration, status, and logs are available for all launched entities within an experiment for easy inspection, along with memory and client data per shard for launched orchestrators.\n\nA ``Telemetry Monitor`` is a background process that is launched alongside the experiment.\nIt is responsible for generating the data displayed by SmartDashboard. The ``Telemetry Monitor`` can be disabled globally by\nadding ``export SMARTSIM_FLAG_TELEMETRY=0`` as an environment variable. When disabled, SmartDashboard\nwill not display entity status data. To re-enable, set the ``SMARTSIM_FLAG_TELEMETRY`` environment variable to ``1``\nwith ``export SMARTSIM_FLAG_TELEMETRY=1``. For workflows involving multiple experiments, SmartSim provides the attributes\n``Experiment.telemetry.enable`` and ``Experiment.telemetry.disable`` to manage the enabling or disabling of telemetry on a per-experiment basis.\n\n`Orchestrator` memory and client data can be collected by enabling database telemetry. To do so, add ``Orchestrator.telemetry.enable``\nafter creating an `Orchestrator` within the driver script. Database telemetry is enabled per `Orchestrator`, so if there are multiple\n`Orchestrators` launched, they will each need to be enabled separately in the driver script.\n\n```python\n# enabling telemetry example\n\nfrom smartsim import Experiment\n\nexp = Experiment(\"experiment\", launcher=\"auto\")\nexp.telemetry.enable()\n\ndb = exp.create_database(db_nodes=3)\ndb.telemetry.enable()\n\nexp.start(db, block=True)\nexp.stop(db)\n```\n\nExperiment metadata is stored in the ``.smartsim`` directory, a hidden folder used by the internal api and accessed by the dashboard.\nThis folder can be found within the created experiment directory.\nDeletion of the experiment folder will remove all associated metadata.\n\n## Installation\n\nIt's important to note that SmartDashboard only works while using SmartSim, so SmartSim will need to be installed as well.\nSmartSim installation docs can be found [here](https://www.craylabs.org/docs/installation_instructions/basic.html).\n\n### User Install\n\nRun `pip install smartdashboard` to install SmartDashboard without cloning the repository.\n\n### Developer Install\n\nClone the `SmartDashboard` repository at https://github.com/CrayLabs/SmartDashboard.git\n\nOnce cloned, `cd` into the repository and run:\n\n```pip install -e .```\n\n## Running SmartDashboard\n\nAfter launching a SmartSim experiment, the dashboard can be launched using SmartSim's CLI.\n \n```smart dashboard --port <port number> --directory <experiment directory path>```\n \nThe port can optionally be specified, otherwise the dashboard port will default to `8501`.\nThe directory must be specified and should be a relative or absolute path to the created experiment directory.\n\nExample workflow:\n\n```bash\n# directory before running experiment\n\u251c\u2500\u2500 hello_world.py\n```\n\n```python\n# hello_world.py\nfrom smartsim import Experiment\n\nexp = Experiment(\"hello_world_exp\", launcher=\"auto\")\nexp.telemetry.enable()\nrun = exp.create_run_settings(exe=\"echo\", exe_args=\"Hello World!\")\nrun.set_tasks(60)\nrun.set_tasks_per_node(20)\n\nmodel = exp.create_model(\"hello_world\", run)\nexp.start(model, block=True, summary=True)\n```\n\n```bash\n# in interactive terminal\npython hello_world.py\n```\n\n```bash\n# directory after running experiment\n\u251c\u2500\u2500 hello_world.py\n\u2514\u2500\u2500 hello_world_exp\n```\n\nBy default, `hello_world_exp` is created in the directory of the driver script.\n\n```bash\n# in a different interactive terminal\nsmart dashboard --port 8888 --directory hello_world_exp\n```\n\nThe dashboard will automatically open in a browser at port 8888 when `smart dashboard ...` \nis invoked locally.\n\n> If the dashboard is executed remotely, establishing port-forwarding to the\n> remote machine will be necessary. This may be accomplished with ssh as follows:\n>\n> ```bash\n> # using ssh to establish port forwarding \n> ssh -L [local-addr]:<local-port>:<remote-addr>:<remote-port> <user-id>@<remote-addr>\n> # example forwarding the remote port 8888 to localhost:8000\n> ssh -L localhost:8000:super1.my.domain.net:8888 smartdash@super1.my.domain.net\n> ```\n>\n> After establishing the port-forwarding, a local browser can be pointed at the appropriate \n> URL, such as `http://localhost:8000` for the example above.\n\nThe dashboard is also persistent, meaning that a user can still launch and use the dashboard even after the experiment has completed.\n\n## Using SmartDashboard\n\nOnce the dashboard is launched, a browser will open to `http://localhost:<port>`. SmartDashboard currently has two tabs on the left hand side.\n \n`Experiment Overview:` This tab is where configuration information, statuses, and logs are located for each launched entity of the experiment. The `Experiment` section displays configuration information for the overall experiment and its logs. In the `Applications` section, also known as SmartSim `Models`, select a launched application to see its status, what it was configured with, and its logs. The `Orchestrators` section also provides configuration and status information, as well as logs per shard for a selected orchestrator. Finally, in the `Ensembles` section, select an ensemble to see its status and configuration. Then select any of its members to see its status, configuration, and logs.\n \n`Database Telemetry:` This tab provides additional details about `Orchestrators`.\nThe `Orchestrator Summary` section shows configuration and status information of the selected. The `Memory`\nsection provides memory usage data per shard within the `Orchestrator`. The `Clients`\nsection displays client data per shard within the `Orchestrator`. \n\n`Help:` This tab links to SmartSim documentation and provides a SmartSim contact for support.\n",
"bugtrack_url": null,
"license": "BSD 2-Clause License",
"summary": "Visualize SmartSim Experiments",
"version": "0.0.4",
"project_urls": {
"Documentation": "https://github.com/CrayLabs/SmartDashboard",
"Homepage": "https://www.craylabs.org",
"Repository": "https://github.com/CrayLabs/SmartDashboard"
},
"split_keywords": [
"scientific",
" ai",
" workflow",
" hpc",
" analysis"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "80f102299d7164d64243ddf75d532368609cf21ee4f32817b0c879f00106b81e",
"md5": "ce580e6b26641bc242aeba0a81325060",
"sha256": "647db5bdaa17d1bc4f6c38b78fb688e2b9f913a1e5ce79cedd69a41628c6547f"
},
"downloads": -1,
"filename": "smartdashboard-0.0.4-py3-none-any.whl",
"has_sig": false,
"md5_digest": "ce580e6b26641bc242aeba0a81325060",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<3.12,>=3.9",
"size": 57691,
"upload_time": "2024-05-14T21:32:21",
"upload_time_iso_8601": "2024-05-14T21:32:21.606997Z",
"url": "https://files.pythonhosted.org/packages/80/f1/02299d7164d64243ddf75d532368609cf21ee4f32817b0c879f00106b81e/smartdashboard-0.0.4-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "c56bb1fdd69ccbdaa5ccf7721c9f1c6d020b2a8f5b0b6643ede76729d9feccf6",
"md5": "1f380b9d47e0a4ae945369a4d3b119d0",
"sha256": "475d80094751d64726226f218456016462c10e7c5dab4ee343fdea45d73aabd1"
},
"downloads": -1,
"filename": "smartdashboard-0.0.4.tar.gz",
"has_sig": false,
"md5_digest": "1f380b9d47e0a4ae945369a4d3b119d0",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<3.12,>=3.9",
"size": 45723,
"upload_time": "2024-05-14T21:32:23",
"upload_time_iso_8601": "2024-05-14T21:32:23.228745Z",
"url": "https://files.pythonhosted.org/packages/c5/6b/b1fdd69ccbdaa5ccf7721c9f1c6d020b2a8f5b0b6643ede76729d9feccf6/smartdashboard-0.0.4.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-05-14 21:32:23",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "CrayLabs",
"github_project": "SmartDashboard",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "smartdashboard"
}
JSON
