vdash 0.12.0

Safe Network safenode Dashboard
vdash-0.12.0 is not a library.

Safe Network node Dashboard

vdash is a terminal based dashboard for monitoring Safe Network nodes. It is written in Rust, using tui-rs to create the terminal UI and linemux to monitor node logfiles on the local machine.

Status: working on Windows, MacOS and Linux with local and public test networks.

vdash is already capable of monitoring multiple logfiles on the local machine so it wouldn't be hard to monitor multiple remote nodes by having a script pull logfiles from remote nodes to local copies monitored by vdash, but this is not on the roadmap. There may be existing tools that could do this so if anyone wants to look into that it would be great as I'm only making minor changes at the moment.

Here's an early vdash (v0.2.0) working with a local testnet node:

Features

vdash will load historic metrics from one or more Safe node logfiles and display these with live updates in the terminal (see above).

'<-' and '->': When monitoring multiple safenode logfiles you can cycle through the different nodes using left/right arrow keys.

'i' and 'o': Zoom the timeline scale in/out using 'i' and 'o' (or '+' and '-').

't' and 'T': Three timelines are visible at any one time but you can cycle through all timelines to bring them all into view by pressing 't' (forward) and 'T' (backward).

'm' or 'M': The Storage Cost timeline displays minimum, mean and maximum values in each time-slot. To cycle through the min, mean and max displays press 'm' or 'M'.

'q': Press 'q' to quit.

Feature requests and discussion are currently summarised in the opening post of the Safe Network forum topic: node Dashboard ideas please!.

For more details and progress see Roadmap (below).

Operating Systems

  • Linux: works on Linux (tested on Ubuntu).
  • Windows: works on Windows 10.
  • MacOS: works on MacOS.

Install from crates.io

1 Install Rust via https://doc.rust-lang.org/cargo/getting-started/installation.html

2a. Linux (Ubuntu)

sudo apt-get install build-essential

2b. Linux/MacOS install vdash:

cargo install vdash
vdash --help

2c. Windows install vdash-crossterm:

To install on Windows you must build manually and use the 'nightly' compiler until the 'itarget' feature becomes part of 'stable', so install Rust nightly using rustup:

rustup toolchain install nightly

To build vdash-crossterm on Windows, clone vdash, build with +nightly and use the binary it creates under ./taget/release:

git clone https://github.com/happybeing/vdash
cd vdash
cargo +nightly build -Z features=itarget --bin vdash-crossterm --release --no-default-features

./target/release/vdash-crossterm --help

Using vdash - a Safe Network node Dashboard

vdash provides a terminal based graphical dashboard of Safe Network node activity on the local machine. It parses input from one or more node logfiles to gather live node metrics which are displayed using terminal graphics.

Status: useful work-in-progress, help welcome!

Get Safe Network pre-requisites

  1. Get Rust: see: https://doc.rust-lang.org/cargo/getting-started/installation.html

  2. Get the Safe CLI: either download using an install script or build the Safe CLI locally. Instructions for both options are here.

  3. Get the Safe node: when you have the Safe CLI working you can install the node software with the command safe node install (details here).

You are now ready to install vdash and can test it by running a local test network.

Usage

For help:

vdash --help

Typically you can just pass the paths of one or more node logfiles you want to monitor. For example, to run vdash first start your Safe Network node(s) with one or more safenode commands. Then, assuming their logfiles are in the standard location start vdash with:

Linux:

vdash ~/.local/share/safe/node/*/logs/safenode.log

Mac:

vdash "/Users/<username>/Library/Application Support/safe/node/*/logs/safenode.log"

Windows:

vdash C:\Users\<username>\AppData\Roaming\safe\node\*\logs\safenode.log

Keyboard commands for vdash are summarised in the introduction above.

Safe Node Setup

IMPORTANT: Ignore this section until the Safe Network CLI has been restored to work with the changes being implemented to Safe Network code in 2023/Q2. For now, see Using vdash With a Local Test Network below.

IMPORTANT: You must ensure the node logfile includes the telemetry information used by vdash by setting the logging level to 'trace' when you start your node (as in the example below). You control the node logging level by setting the environment variable SN_LOG.

killall safenode
rm -f ~/.safe/node/local-test-network/
SN_LOG=all safenode

To start a node using safenode you should check you are using the correct parameters for your system setup.

When your node has started run vdash, typically in a different terminal:

vdash ~/.safe/node/local-node/safenode.log

Note:

  • killall safenode makes sure no existing nodes are still running, and deleting the local-test-network directory prevents you picking up statistics from previous logfiles. If you leave the logfile in place then vdash will waste time processing that, although you can skip that process using a command line option.

  • setting SN_LOG ensures the logfiles contain the data which vdash needs, and excludes some that gets in the way.

  • On Windows to set SN_LOG environment variable:

    Using Windows Command Line:

     set SN_LOG="all"
 safe node join

    Using Windows PowerShell:

     $env:SN_LOG="all"
 safe node join

Using vdash With a Local Test Network

  1. Start a local test network: follow the instructions to Run a local network, for example:

    rm -rf ~/.safe/node/local-test-network/
cd safe_network
killall safenode || true && SN_LOG=all cargo run --bin testnet -- -b --interval 100

    Windows: see "Note" immediately above for how to set SN_LOG on Windows.

  2. Run vdash: in a different terminal window, start vdash with: You can then run vdash, typically in a different terminal:

    vdash ~/.safe/node/local-test-network/safenode-*/safenode.log

    Or with a live network:

    vdash ~/.safe/node/local-node/safenode.log

  3. Upload files using Safe CLI: using the Safe CLI you can perform operations on the local test network that will affect the node and the effects will be shown in vdash. For example, to use the Safe CLI to upload files:

    safe files put ./<some-directory>/ --recursive

If you want to try vdash with a live network, check to see if one is running at the Safe Network community forum: https://safenetforum.org

Build

See Get Safe Network Pre-requisites.

Get code

git clone https://github.com/happybeing/vdash
cd vdash

Build - Linux / MacOS / Windows 10

Note: MacOS and Windows are untested but may 'just work' - please report success or failure in an issue.

cargo build --release

If built for target 'musl' vdash uses considerably less memory:

rustup target add x86_64-unknown-linux-musl
cargo build --release --target x86_64-unknown-linux-musl

Comparing memory use (using htop on Linux):

VIRT   RES  SHR
803M  9372 4716 x13 threads (release)
32768 6848 2440 x13 threads (release/musl)

Note: the above figures are out of date but illustrate the point.

Roadmap

Where vdash is headed:

  • implement ability to parse logfiles
    • add --debug-parser to show results in second logfile
    • implement parsing log file for simple metrics and timeline
    • keep the debug UI available (selected with 'D' when using --debug-parse)
  • change events to use tokio mpsc (unbounded) channel
  • does tokio mpsc fix loss of updates from linemux (see linemux issue #17)
  • implement node dashboard
    • node status summary page (single node)
    • debug window (--debug-window)
    • add basic node stats (age/PUTs/GETs)
    • scroll node logfile (arrow keys)
    • multiple nodes (navigate with tab and arrow keys)
    • add a timeline
      • simple timeline with PUTS and GETS
      • implement multiple timeline durations (hour, minute etc)
      • add status/timeline for ERRORS
      • anchor 'now' to right border
      • mod sparkline widget to have a minimum Y scale (e.g. 10 units)
    • reduce lag in processing logfile changes
      • implement simple rate limit on redraws
      • implement update/redraw tick (for timeline and stats)
      • fix load from logfile to timeline (currently all ends up in last bucket)
      • change timeline scaling to use +/- an i/o keys rather than s, m, d etc
      • optimise redraw rate limit
      • make a CLI option for redraw rate limit
    • track safenode issue #1126 (maintain Get/Put response in)
    • implement storage 'meter'
      • code to get node storage used
      • code to get free space on same device
      • implement storage used/free 'progress' bar
    • implement bandwidth 'meter'
      • code to get node bandwidth
      • code to get total bandwidth
      • implement bandwidth node/total/max in last day 'progress' bar
  • Implement DashOverview: all nodes on one page (rename from DashSummary)
  • trim NodeMetrics timeline
  • logtail-dash Issue #1: Implement popup help on ?, h, H
  • FIXED by upate to tui-rs v0.11.0 Issue #382: Window titles corrupted when using --debug-window
  • Implement --features="vdash" / --features="logtail" to select app and UI
  • switch to crossterm only (v0.9.0)
  • port from tui-rs (deprecated) to ratatui (supported fork of tui-rs)

LICENSE

Everything is GPL3.0 unless otherwise stated. Any contributions are accepted on the condition they conform to this license.

See also ./LICENSE