Custom Commands

Custom commands can be triggered via the N|Solid Command Line Interface (CLI). Custom commands allow you to interact with your application's processes in ways specific to your business needs.

Create A Custom Command

To implement a custom command, create a function to handle the command, and register that function with N|Solid.

The custom command function should be defined to take a single parameter, request:

function customCommandHandler(request) { ... }

The request parameter is an object with the following properties/functions:

Property	Description
request.value	An optional piece of data sent with the command, using the nsolid-cli parameter --data
request.return(value)	The function to call when you are ready to return the result of this command. The N|Solid Agent will reply with the value passed as a parameter
request.throw(error)	A function to call if an error is encountered. The N|Solid Agent will reply with the error passed as a parameter

Your function you must call either request.return() or request.throw() to signal completion of the command.

To get access to N|Solid's built-in nsolid module, call require("nsolid"). A custom command handler is registered using the nsolid.on() function:

The nsolid.on() function takes the following parameters:

Parameter	Description
commandName	The string name of the command to implement
handler	The custom command function implementing the command

nsolid.on(commandName, handler)

Example Custom Command Registration

const nsolid = require("nsolid")
...
nsolid.on("foo", fooCommand)
...
function fooCommand(request) { ... }

Sample Case: Log Level Custom Command

Below is an example of how you can use custom commands to dynamically change the configuration state of the application, specifically the log level. The example assumes that a global boolean variable Verbose is used to indicate whether to log verbosely or not.

//------------------------------------------------------------------------------
// This program is a simple "server" which does nothing, but does implement
// an N|Solid custom command, named `verbose`.  Once you've started this program
// with the N|Solid agent enabled, you can send the `verbose` command as in:
//
// nsolid-cli --id $NSOLID_AGENTID custom --name verbose
// nsolid-cli --id $NSOLID_AGENTID custom --name verbose --data on
// nsolid-cli --id $NSOLID_AGENTID custom --name verbose --data off
//
// All these forms get or set the "verbose" level of logging in the program.
//
// The server logs a message every second when "verbose" is off, and logs
// an additional message after that one when "verbose" is on.  The default
// setting of "verbose" is false.
//------------------------------------------------------------------------------

"use strict"

// get access to N|Solid's built-in module `nsolid`
const nsolid = require("nsolid")

// the current "verbose" level
let Verbose = false

// register the `verbose` command for nsolid-cli
nsolid.on("verbose", verboseCommand)

// your server which doesn't do much
setInterval(onInterval, 2000)

console.log("N|Solid custom command demo - log-level - started")
console.log("")
console.log("to use the verbose command with `nsolid-cli`, run:")
console.log("   nsolid-cli --id $NSOLID_AGENTID custom --name verbose")
console.log("   nsolid-cli --id $NSOLID_AGENTID custom --name verbose --data on ")
console.log("   nsolid-cli --id $NSOLID_AGENTID custom --name verbose --data off ")

//------------------------------------------------------------------------------
function onInterval() {
  log("interval event!")
  logVerbose("some extra logging here")
}

//------------------------------------------------------------------------------
// implements the `verbose` command  for nsolid-cli
//------------------------------------------------------------------------------
function verboseCommand(request) {

  // if "on" or "off" passed in with --data, set Verbose appropriately
  if (request.value == "on") {
    Verbose = true
  }
  else if (request.value == "off") {
    Verbose = false
  }
  else if (request.value) {
    return request.throw("expecting data of `on` or `off`, got " + request.value)
  }

  // return current value of Verbose
  return request.return({verbose: Verbose})
}

//------------------------------------------------------------------------------
function log(message) {
  console.log(message)
}

//------------------------------------------------------------------------------
function logVerbose(message) {
  if (!Verbose) return
  log(message)
}

When running your application with the N|Solid agent active, you can use the following command to return the current value of the Verbose setting:

$ nsolid-cli --id $NSOLID_AGENTID custom --name verbose

To set Verbose on or off, use one of the following commands:

$ NSOLID_AGENTID="69d916ad395061f80589e20bef9af3cb50ece9cb" # This will change
$ nsolid-cli --id $NSOLID_AGENTID custom --name verbose --data on
$ nsolid-cli --id $NSOLID_AGENTID custom --name verbose --data off

The output of these three CLI commands looks like the following:

{"verbose":false,"time":1472496720972,"timeNS":"1472496720972042976","id":"69d916ad395061f80589e20bef9af3cb50ece9cb","app":"my-verbose-app","hostname":"titania"}