N|Solid Documentation

Versions

Custom Commands

As a developer, you can trigger your own custom commands 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.

You can implement a custom command by creating a function to handle the command, and then registering the 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:

Parameter 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 Agent will reply with the value passed as a parameter.
request.throw(error) A function to call if an error is encountered. The 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.

A custom command handler is registered using the nsolid.on() method. You can get access to N|Solid's built-in nsolid module, by calling require("nsolid"). The nsolid.on() function takes the following parameters:

nsolid.on(commandName, handler)
Parameter Description
commandName The string name of the command to implement
handler The custom command function implementing the command

The structure of implementing and registering a custom command will look like the code below:

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

Example: 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"}

In this example you have directed a command at a single instance of your app. If you have multiple copies of this app running and you want to set all of their log levels to "verbose" simultaneously, omit the id parameter and use the app parameter instead.

nsolid-cli --app my-verbose-app custom --name verbose --data on
nsolid-cli --app my-verbose-app custom --name verbose --data off

This time multiple instances of the app might respond to the request.

{"verbose":false,"time":1472496720956,"timeNS":"1472496720956429760","id":"69d916ad395061f80589e20bef9af3cb50ece9cb","app":"my-verbose-app","hostname":"titania"}
{"verbose":false,"time":1472496720961,"timeNS":"1472496720961042976","id":"f1a6492b6bdf44db003a163430c7c7244ae28212","app":"my-verbose-app","hostname":"titania"}
{"verbose":false,"time":1472496720972,"timeNS":"1472496720972132564","id":"54153b774190fa24672708120b94b10fd41f75b8","app":"my-verbose-app","hostname":"titania"}