Drop-in Node.js admin endpoint to help you analyze production issues.
Clone or download
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
dev Add an environment variable plugin Mar 7, 2017
example example: Update Node.js to 6.11.1 due to severe security issues in pr… Jul 13, 2017
lib Use get-logger for easy log configuration May 1, 2017
plugins report: 1.0.1 Jun 8, 2017
.editorconfig Get started with config handling Mar 2, 2017
.gitignore Add an environment variable plugin Mar 7, 2017
.nvmrc Get started with config handling Mar 2, 2017
.travis.yml Switch to NPM and enable travis Mar 6, 2017
CHANGELOG.md admin: 1.4.0 May 1, 2017
CONTRIBUTING.md Add admin-plugin-terminate to commonSetup Apr 2, 2017
LICENSE Add a footer so that users know where to get support and how to find … Mar 7, 2017
PLUGINS.md
README.md Add faq links Apr 5, 2017
package.json

README.md

admin   Build Status js-semistandard-style Greenkeeper badge

Drop-in Node.js admin endpoint to help you analyze production issues.

Live Demo | Usage | FAQ | Plugins | Example project | Changelog


Running apps in production can be challenging. Applications may crash, run into bugs or get slow. There are a variety of ways to approach such issues. Admin is a tool to help troubleshoot application issues. It is designed to provide detailed debugging information about running Node.js apps.

Admin provides debugging endpoints via an HTTP server. The functionality provided by this server is extensible as admin is a plugin system.

Instead of describing this at length, check out the live demo system on Heroku!

Contents

Installation

To use admin, the admin Node.js package and at least one plugin needs to be installed. The following example shows a typical setup.

npm install --save admin \
  admin-plugin-config \
  admin-plugin-healthcheck \
  admin-plugin-environment \
  admin-plugin-index \
  admin-plugin-profile \
  admin-plugin-report \
  admin-plugin-terminate

Usage

To use admin, it needs to be configured and started with your application. The folowing code listing shows how this can be done.

const admin = require('admin');

admin.configure({
  http: { // optional
    bindAddress: '127.0.0.1', // default
    port: 2999 // default
  },

  plugins: [
    require('admin-plugin-index')(),
    require('admin-plugin-report')(),
    require('admin-plugin-environment')(),
    require('admin-plugin-profile')(),
    require('admin-plugin-terminate')(),
    require('admin-plugin-config')({
      config: {
        // An application config goes here. This config object will be
        // visible in the admin UI and via the admin REST endpoints.
        secret: '42',
        port: 8080
      }
    }),
    require('admin-plugin-healthcheck')({
      checks: {
        // Define multiple healthchecks which check critical components
        // in the system. The following example shows valid return values.
        random() {
          const v = Math.random();
          if (v > 0.8) {
            throw new Error('Random value >0.8');
          } else if (v > 0.3) {
            return "Healthy like an application that isn't used.";
          } else {
            return Promise.reject('Something bad happened here…');
          }
        }
      }
    })
  ]
});

admin.start();

FAQ

How do I inspect the admin UI when it only binds to localhost?

The easiest solution is to setup an SSH tunnel to the machine:

SSH_KEY="~/.ssh/<my_key>"
REMOTE_USER="<user>"
REMOTE_HOST="<host>"
ADMIN_PORT="<port>"

ssh -i "$SSH_KEY" -Nf -L "$ADMIN_PORT:localhost:$ADMIN_PORT" "$REMOTE_USER@$REMOTE_HOST"
curl "localhost:$ADMIN_PORT"