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