FormidableLabs

Telemetry dashboard for node.js apps from the terminal!

3.9K Stars 161 Forks Last release: Not found MIT License 238 Commits 12 Releases

Available items

No Items, yet!

The developer of this repository has not created any items for sale yet. Need a bug fixed? Help with integration? A different license? Create a request here:

Readme

nodejs-dashboard

Name: nodejs-dashboard
Brand: nodejs-dashboard
SKU: //FormidableLabs/nodejs-dashboard
Rating: 4.318555555555555 (3867 reviews)

Telemetry dashboard for node.js apps from the terminal!

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

--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

. 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

=,...

. 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).