Determine in realtime what's happening inside your node process from the terminal. No need to instrument code to get the deets. Also splits stderr/stdout to help spot errors sooner.
Install, Setup, Usage, Using with other programs, CLI options, Customizing layouts
---------------, ---------------------, -----------------, -----------------, ------------------------------------------, ----------------------
NOTE: This module isn't designed for production use and should be limited to development environments.
Install
The preferred method is global install. npm install -g nodejs-dashboard
Local install works also; just use ./node_modules/.bin/nodejs-dashboard instead of nodejs-dashboard to execute.
Setup
The dashboard agent needs to be required by your app. There are two ways to do this:
Including via code
From within a dev.index.js script or other dev entry point simply require the nodejs-dashboard module.
// dev.index.js
require("nodejs-dashboard");
require("./index");
To launch: nodejs-dashboard node dev.index.js
Including via preload argument
This method utilizes Node's -r flag to introduce the nodejs-dashboard module. In this setup no code modifications are required. This is functionally equivalent to the above example.
To launch: nodejs-dashboard -- node -r nodejs-dashboard index.js
Fonts
nodejs-dashboard uses the Braille Unicode character set to show graphs via the node-drawille dependancy. Ensure your terminal program's font supports this character set.
Environment variables
nodejs-dashboard uses several environment variables to modify its behavior. These include some required values to prevent mangled output.
Variable, Required, Source, Description, ---, ---, ---, ---, TERM, required, blessed, Terminal value matching terminal program, LANG, required, blessed, Matches encoding of terminal program to display font correctly, FORCE_COLOR, optional, chalk, Used to force color output by the subprocess, ### Usage
Press ? to see a list of keybindings. Use arrow keys to change the layout.
You may want to add an npm script to to your package.json to launch your app using nodejs-dashboard using one of the options above. Example:
"scripts": {
"dev": "nodejs-dashboard -- node -r nodejs-dashboard index.js"
}
Passing arguments
If your app requires additional arguments you'll need to use the -- flag to separate them from nodejs-dashboard options. For example:
nodejs-dashboard --port=8002 -- node -m=false --bar=true index.js
Launching your app with something other than node
Most CLI interfaces provide a mechanism for launching other tools. If you're looking to use something like nodemon or babel checkout the exec options provided by the CLI.
% nodemon --exec "nodejs-dashboard babel-node" src/index.js
Docker and Docker Compose support
nodejs-dashboard can run inside a container if that container has a TTY allocated to it. The Docker documentation shows how to run a container with an interactive terminal session. Additional the Docker Compose documentation indicates that docker-compose run defaults to allocating a TTY and docker-compose up defaults to not allocating one.
CLI options
Usage: nodejs-dashboard [options] -- [node] [script] [arguments]
Options:
-h, --help output usage information
-e, --eventdelay [ms] Minimum threshold for event loop reporting, default 10ms
-l, --layouts [file] Path to file or npm module with layouts
-p, --port [port] Socket listener port
-r, --refreshinterval [ms] Metrics refresh interval, default 1000ms
-s, --settings [settings] Overrides layout settings for given view types
-V, --version output the version number
--eventdelay
This tunes the minimum threshold for reporting event loop delays. The default value is 10ms. Any delay below this value will be reported at 0.
--layouts
Optionally supply a custom layout configuration (for details, see Customizing Layouts). Default: lib/default-layout-config.js
--port
Under the hood the dashboard utilizes SocketIO with a default port of 9838. If this conflicts with an existing service you can optionally change this value.
--refreshinterval
Specifies the interval in milliseconds that the metrics should be refreshed. The default is 1000 ms (1 second).
--settings
Overrides default or layout settings for views. Option value settings should have a format <view_type.setting.path>=<value>,.... For example --settings log.scrollback=100 will override scrollback setting for any view of log type (nested paths can be used if needed). For details about layouts, see Customizing Layouts).