jchaos v1.2.1

JCHAOS

This javascript module can be used, both in HTML or as nodejs library to access !CHAOS resources. This package bundles some !CHAOS utility and management applications.

Install

Global installation:

npm install -g jchaos

NPM Will install library and applications

Repository

git@baltig.infn.it:chaos-lnf-control/jchaos.git

Application

jchaosctl

This application will perform management operation on chaos. The basic usage is:

/usr/bin/jchaosctl <--server server:port>
[--upload <config to upload>]
[--download <config output>>]
[--findlive < cu | us | agent | mds | webui | variable | snapshotsof | snapshots | script | zone | class >]
[--find < cu | us | agent | mds | webui | variable | snapshotsof | snapshots | script | zone | class >]
[--op < start | stop | init | deinit| load | unload | kill | shutdown |health>]
[--uid <!CHAOS node UID>]
[--help]

jchaos library

Table of Contents

• jchaos
  • options
    • Properties
  • print
    • Parameters
  • perror
    • Parameters
  • rmtCreateProcess
    • Parameters
  • rmtDownload
    • Parameters
  • rmtUploadScript
    • Parameters
  • rmtSetConsole
    • Parameters
  • rmtGetConsole
    • Parameters
  • progressBar
    • Parameters
  • addLongKey
    • Parameters
  • getLongLong
    • Parameters
  • setLongLong
    • Parameters
  • normalizeDataset
    • Parameters
  • getUS
    • Parameters
  • loadScript
    • Parameters
  • manageInstanceScript
    • Parameters
  • saveScript
    • Parameters
  • rmScript
    • Parameters
  • searchScriptInstance
    • Parameters
  • updateScriptInstance
    • Parameters
  • setAttribute
    • Parameters
• okcb
  • Parameters
• badcb
  • Parameters
• cmdPar
  • Properties
• varpath
  • Properties
• channelid
• call
  • Properties
• createLibrary
• decodeCUPath
  • Parameters
• toHHMMSS
  • Parameters
• setOption
  • Parameters
• basicRmt
  • Parameters
• rmtGetEnvironment
  • Parameters
• rmtSetProp
  • Parameters
• rmtCreateProcess
  • Parameters
• rmtCreateProcess
  • Parameters
• rmtUploadScript
  • Parameters
• rmtListProcess
  • Parameters
• rmtKill
  • Parameters
• rmtPurge
  • Parameters
• basicPost
  • Parameters
• registerCU
  • Parameters
• pushCU
  • Parameters
• mdsBase
  • Parameters
• tag
  • Parameters
  • Examples
• checkRestore
  • Parameters
• checkBurstRunning
  • Parameters
  • Examples
• checkEndBurst
  • Parameters
  • Examples
• snapshot
  • Parameters
  • Examples
• node
  • Parameters
  • Examples
• variable
  • Parameters
  • Examples
• log
  • Parameters
  • Examples
• search
  • Parameters
  • Examples
• findCUByImplementation
  • Parameters
  • Examples
• getCUStatus
  • Parameters
• convertArray2CSV
  • Parameters
• getChannel
  • Parameters
  • Examples
• setProperty
  • Parameters
• loadUnload
  • Parameters
• sendCUCmd
  • Parameters
• sendCUFullCmd
  • Parameters
• getHistory
  • Parameters
• fetchHistoryToZip
  • Parameters
• checkPeriodiocally
  • Parameters
• saveFullConfig
  • Examples
• restoreFullConfigFromFile
• restoreFullConfig
  • Parameters
• activeAgentList
  • Parameters
  • Examples
• getAllProcessInfo
  • Parameters
• findBestServer
  • Parameters
  • Examples
• runScript
  • Parameters
• encodeName
  • Parameters
• checkLive
  • Parameters
  • Examples

jchaos

!CHAOS REST Library

Meta

• version: 1.0
• author: Andrea Michelotti

options

Properties

• updateEachCall boolean =true choose if update each call of history operation
• uri string =localhost:8081 REST server URI
• async boolean =true if false force the call to be synchronous, otherwise depend if the callback is definedd
• limit_on_going integer =10000 limits the concurrent operations
• history_page_len integer =1000 default history page len
• timeout integer =5000 default timeout for operation
• console_log callback redirected on console.log
• console_err callback redirected on console.error

print

Prints a String on the configured console

Parameters

• str string

perror

Prints a String on the configured console error

Parameters

• str string

rmtCreateProcess

Parameters

• server
• name
• cmdline
• ptype
• workdir
• handler
• badhandler

rmtDownload

Retrive a process working directory return a zip file

Parameters

• server
• uid
• workdir
• handler
• badhandler

rmtUploadScript

Parameters

• server
• name
• ptype
• content
• handler
• badhandler

rmtSetConsole

Write on the remote console of the specified process

Parameters

• server string rest process remote management server
• uid string the process uid returned by the rmtCreateProcess
• str string line to send
• handler okcb handler on success
• badhandler badcb handler on failure

rmtGetConsole

Reads the console of the specified process uid

Parameters

• server string rest process remote management server
• uid string the process uid returned by the rmtCreateProcess
• fromline integer get from this line
• toline integer until this line (-1 means end)
• handler okcb handler on success
• badhandler badcb handler on failure

progressBar

Parameters

• msg
• id
• lab

addLongKey

Parameters

• obj
• key
• valuestr

getLongLong

Parameters

• obj
• key

setLongLong

Parameters

• obj
• key
• val

normalizeDataset

Parameters

• obj

getUS

get a US description

Parameters

• _name

loadScript

Parameters

• _name
• seqid
• handleFunc
• errFunc

manageInstanceScript

Parameters

• script_name
• script_seq
• instance_name
• create
• handleFunc

saveScript

Parameters

• value
• handleFunc

rmScript

Parameters

• value
• handleFunc

searchScriptInstance

Parameters

• script_name
• search_string
• handleFunc
• errfunc

updateScriptInstance

Parameters

• script_instance
• script_base_description
• handleFunc

setAttribute

Parameters

• devs (string | Array<string>) CU or array of CU
• attr string attribute name
• value string attribute value
• handleFunc okcb? callback if ok, enable async mode
• handleFuncErr badcb? bad callback

okcb

Callback in asynchronous operations called when the operation is ok

Type: Function

Parameters

• data object depend on the operation (typically a dataset)

badcb

Callback in asynchronous operations called when the operation is fails

Type: Function

Parameters

• data (string | object) description of the error

cmdPar

The command object for sendCU commands

Type: Object

Properties

• cmd string command name
• prio integer Priority
• mode integer mode

varpath

CU variable path

Type: Object

Properties

• cu string CU PATH
• dir string direction (input,output)
• var string variable dataset name
• const string constantco:String
• origin string full path

channelid

Channel idintification mapping: -1 : all 0: output 1: input 2: custom 3: system 4: health 5: cu alarms 6: device alarms 128: status 255: health+system+ alarams

Type: integer

call

Type: object

Properties

• updateEachCall boolean history update each call
• uri string address:port of the REST server

createLibrary

Creates a new jchaos object.

decodeCUPath

Decode a CU dataset element path and return an object

Parameters

• cupath string

Returns varpath

toHHMMSS

translate seconds in days hours minutes seconds string

Parameters

• sec_num integer

Returns string return string xx days hh:mm:ss

setOption

Set Library options options

Parameters

• opt object

basicRmt

Helper function to post commands on the process remote management

Parameters

• server string rest process remote management server
• func string REST function
• param object REST function parameters
• handler okcb handler on success
• badhandler badcb handler on failure

rmtGetEnvironment

Retrive a given environemnt variable

Parameters

• server string rest process remote management server
• varname string environment variable name
• handler okcb handler on success
• badhandler badcb handler on failure

Returns any the value on the specified handler.

rmtSetProp

Set the specified propery

Parameters

• server string rest process remote management server
• prop {uid: String, propname: String} property name
• handler okcb handler on success
• badhandler badcb handler on failure

Returns any the value on the specified handler.

rmtCreateProcess

Launch a process the specified process on the given remote server return a process structure

Parameters

• server string rest process remote management server
• name string program name
• cmdline string command line
• ptype string type ("exec": binary, "C++": C++ script")
• workdir string remote local directory
• handler okcb handler on success
• badhandler badcb handler on failure

Returns object return a process object with many status and information

rmtCreateProcess

Return a zip file contaning the working directory of the specified process can be used to retrieve outputs of remote runs

Parameters

• server string rest process remote management server
• uid string the process uid returned by the rmtCreateProcess
• workdir string working dir to retrieve and zip
• handler okcb handler on success
• badhandler badcb handler on failure

rmtUploadScript

Upload a script/executable on the remote server return the path

Parameters

• server string rest process remote management server
• name string program name
• ptype string type ("exec": binary, "C++": C++ script")
• content string base64 encoded content to upload
• handler okcb handler on success
• badhandler badcb handler on failure

Returns object return the path of the remote process

rmtListProcess

Return a list of process on the given server

Parameters

• server string rest process remote management server
• handler okcb handler on success
• badhandler badcb handler on failure

Returns Array<object> return a list of process descriptors

rmtKill

Kill the specified process

Parameters

• server string rest process remote management server
• uid string the process uid returned by the rmtCreateProcess
• handler okcb handler on success
• badhandler badcb handler on failure

rmtPurge

Purge a list of process to a given level (0 soft (EXCEPTION), 1 medium (ENDED and EXCEPTION), 2 hard (ALL)

Parameters

• server string rest process remote management server
• level integer purge level
• handler okcb? handler on success
• badhandler badcb? handler on failure

basicPost

Helper function that is the base of all commands to the !CHAOS REST SERVER the server is specified in the option

Parameters

• func string REST function to perform
• params string parameters
• handler okcb? handler on success, if present the call will be asynchronous
• badhandler badcb? handler on failure
• server string? override the default server

registerCU

Registers a CU dataset using REST

Parameters

• cuid string
• obj object the CU dataset to register/push
• handleFunc okcb? handler on success, if present the call will be asynchronous
• badhandler badcb? handler on failure

pushCU

Push a CU dataset using REST

Parameters

• cuid string
• obj object the CU dataset to register/push
• handleFunc okcb? handler on success, if present the call will be asynchronous
• badhandler badcb? handler on failure

mdsBase

Helper function that wrap basic post used for query that regards generic MDS operations

Parameters

• cmd string command to send
• opt object options
• handleFunc okcb? handler on success, if present the call will be asynchronous
• errFunc badcb? handler on failure

tag

Start tagging a list of nodes for an interval of given time, expressed in cycles or ms

Parameters

• tagname string
• node_list (string | Array<string>)
• tag_type integer (2= time in ms, 1=cycles)
• tag_value integer numer of ms or cycles
• handleFunc okcb? handler on success, if present the call will be asynchronous
• nok badcb? handler on failure

Examples

//tagging for 10s two CU (cameras), give the name burstbyseconds  
var camera_list=["TEST/FLAME/CMP/CAMERA/FLACMPFF","TEST/FLAME/CMP/CAMERA/FLMCMP01"];
jchaos.tag("burstbyseconds",camera_list,2,10000,function(d){jchaos.print("tagging started");});

checkRestore

Check if a lists of CU have done a correct snapshot restore, the check is performed every timeout/10 ms for maximum timeout

Parameters

• _tagname string name of the tag
• _node_list (string | Array<string>) list of nodes
• _timeout integer timeout
• _okhandler okcb?
• _nokhandler badcb?

checkBurstRunning

Helper function to check if a burst is running

Parameters

• _tagname string name of the tag
• _node_list (string | Array<string>) list of nodes
• _timeout integer timeout
• _okhandler okcb?
• _nokhandler badcb?

Examples

// check the burst is running
var camera_list=["TEST/FLAME/CMP/CAMERA/FLACMPFF","TEST/FLAME/CMP/CAMERA/FLMCMP01"];
jchaos.checkBurstRunning("burstbyseconds",camera_list,10000,function(){jchaos.print("OK");},function(){chaos.error("BAD");})

checkEndBurst

Check if a list of CU ended correct burst, the check is performed every timeout/10 ms for maximum timeout

Parameters

• _tagname string name of the tag
• _node_list (string | Array<string>) list of nodes
• _timeout integer timeout
• _okhandler okcb?
• _nokhandler badcb?

Examples

// check the burst is running
var camera_list=["TEST/FLAME/CMP/CAMERA/FLACMPFF","TEST/FLAME/CMP/CAMERA/FLMCMP01"];
jchaos.checkEndBurst(camera_list,10000,function(){jchaos.print("OK");},function(){chaos.error("BAD");})

snapshot

• See: tag

Performs snapshot operations

Parameters

• _name string name of the snapshot
• _what ("create" | "load" | "set" | "delete" | "restore" | "burst") operation to perform
• _node_list (string | Array<string>) nodes to snapshot
• value_ object? parameter for set command
• handleFunc okcb?
• nok badcb?

Examples

// create a set point programmatically of a set of powersupply
var ps=["BTF/QUADRUPOLE/QUATB001","BTF/QUADRUPOLE/QUATB002","BTF/QUADRUPOLE/QUATB003"];
var powersupply_setpoint = {
"input": {
"ndk_uid": "undefined",
"current": 0.1,
"stby": true,
"polarity": 1
},
"output": {
"ndk_uid": "undefined",
"current": 0.1,
"stby": true,
"polarity": 1,
"local": false
}
};
var snapshot_set = [];
var polarity = 1;
var current = Number(0.0000001);

ps.forEach(function (elem) {
var snap = powersupply_setpoint;
snap.input.stby = true;
snap.input.current = current;
snap.input.ndk_uid = elem;
snap.input.polarity = polarity;
snap.output.ndk_uid = elem;
snap.output.polarity = polarity;
snap.output.stby = true;
snap.output.current = current;
polarity = polarity > 0 ? -1 : 1;
jchaos.snapshot("zero-stby", "set", "", snap, function (d) {
jchaos.print("set setpoint OK:"+JSON.stringify(snap));
});
});

node

Perform and operation specified by '_what' onthe nodes of '_name' of type :'_type'

Parameters

• _name (string | Array<string>) the name of the nodes where to perform the operation
• _what ("init" | "deinit" | "start" | "stop" | "get" | "set" | "del" | "killcmd" | "shutdown" | "kill" | "restart" | "desc" | "getlog" | "health" | "info") operation type
• _type ("us" | "cu" | "agent") target type of the command
• _parent string? some commands needs a parent node to be specified
• value_ object? some commands needs a parameter
• handleFunc okcb
• nok badcb

Examples

// stop|start|init|deinit a cu 
jchaos.node("BTF/QUADRUPOLE/QUATB001","stop","cu");
jchaos.node("BTF/QUADRUPOLE/QUATB001","start","cu");

variable

Allows to manage variables that are persistent (on DB)

Parameters

• _name (string | Array<string>)
• _what ("set" | "get" | "del" | "search") operation type
• value_ object? in case of set the object
• handleFunc okcb? callback if ok, enable async mode
• handleFunc badcb? callback if failure

Examples

// store an object
var point={x:10.34,y:14.0};
jchaos.variable("mypoint","set",point);
// perform list
jchaos.variable("mypoint","search",function(ls){jchaos.print(JSON.stringify(ls));}); 
// get and visualize variable stored
jchaos.variable("mypoint","get",function(ls){jchaos.print(JSON.stringify(ls));});
// delete variable
jchaos.variable("mypoint","del");

log

Search logs for the given CUs

Parameters

• devs (string | Array<string>) to search
• _what "search" operation to perform
• _type ("all" | "Info" | "error" | "warning" | "log" | "command") specify log type
• _start integer epoch in ms start of the search
• _end integer epoch md end of the search (-1 is now)
• handleFunc okcb? callback if ok, enable async mode
• handlerr badcb? callback if error

Examples

// retrieve all logs for a given CU till now
jchaos.log("BTF/QUADRUPOLE/QUATB001","search","all",0,-1,function(ls){jchaos.print(JSON.stringify(ls));});

search

Parameters

• _name string is the substring of what you want search
• _what ("cu" | "us" | "agent" | "cds" | "webui" | "variable" | "snapshotsof" | "snapshots" | "script" | "zone" | "class") operation type
• _alive boolean search among alive (true) or all(false)
• handleFunc okcb? callback if ok, enable async mode
• handlerr badcb? callback if error

Examples

// search all CU alive
jchaos.search("","cu",true,function(ls){jchaos.print(JSON.stringify(ls));});

Returns any an array of strings or objects

findCUByImplementation

Find an array of CU with the given implementation

Parameters

• impl string C++ implementation name to find
• alive bool search from alive or all
• handleFunc okcb? callback if ok, enable async mode

Examples

// find implementation that starts with SCA(ctuators)
jchaos.findCUByImplementation("SCA",true,function(ls){jchaos.print(JSON.stringify(ls));});

getCUStatus

Return an array of CU that match a given status

Parameters

• status_to_search string
• handleFunc okcb? callback if ok, enable async mode

convertArray2CSV

convert an array into a CommaSepareted elements

Parameters

• devs Array<string> array

Returns string

getChannel

Retrive the specified dataset correspoding to a given CU

Parameters

• devs (String | Array<String>) CU or array of CU
• channel_id channelid (-1: all,0: output, 1: input, 2:custom,3:system, 4: health, 5 cu alarm, 6 dev alarms,128 status)
• handleFunc okcb? callback if ok, enable async mode
• badfunc badcb? bad callback

Examples

//retrive all channels of a give CU
chaos.getChannel("BTF/QUADRUPOLE/QUATB001",-1,function(ls){jchaos.print(JSON.stringify(ls));});

Returns object the specified dataset

setProperty

Set a CU property

Parameters

• dev (string | Array<string>) CU or array of CU
• prop string property name
• handleFunc okcb? callback if ok, enable async mode
• errFunc badcb? bad callback

loadUnload

Load or Unload a CU

Parameters

• dev (string | Array<string>) CU or array of CU
• loadunload bool (true = load, false=unload)
• handleFunc okcb? callback if ok, enable async mode
• nok badcb? bad callback

sendCUCmd

Sends a command to a CU

Parameters

• devs (string | Array<string>) CU or array of CU
• cmd cmdPar command to send
• param object? optional and my be included into cmd
• handleFunc okcb? callback if ok, enable async mode
• handleFuncErr badcb? bad callback

sendCUFullCmd

Sends a command to a CU, with explicit params

Parameters

• devs (string | Array<string>) CU or array of CU
• cmd string command to send
• param (string | object)?
• force integer
• prio integer
• handleFunc okcb? callback if ok, enable async mode
• handleFuncErr badcb? bad callback

getHistory

Retrive history of a channel dataset of a group of devices

Parameters

• devs (string | Array<string>) CU or array of CU
• channel integer channel to retrieve
• start (integer | string) epoch timestamp in ms (GMT) of start of search
• stop (integer | string) epoch timestamp in ms (GMT) of start of search
• varname string? optional name of the variable to retrieve (instead of all)
• handleFunc okcb? callback if ok, enable async mode
• tagsv (string | Array<string>)? optional tags
• funcerr badcb? optional bad callback

fetchHistoryToZip

Retrive history and write a local zip

Parameters

• zipname string
• cams (string | Array<string>) array of CU
• start (integer | string) epoch timestamp in ms (GMT) of start of search
• stop (integer | string) epoch timestamp in ms (GMT) of start of search
• tagsv Array<string>? tags
• updateCall okcb
• errCall badcb

checkPeriodiocally

• See: checkLive
• See: checkBurstRunning

Helper function th check a periodically a condition the difference with check live is the check function don't receive a dataset in input

Parameters

• str string string to display each time the check is performed
• retry integer retry the check for a maximum of number of time
• checkFreq integer check frequency in ms
• checkFunc okcb check function, should return true if ok or false if fails
• okhandle okcb callback to call if test succeed
• nokhandle badcb callback to call if fails

saveFullConfig

saveFullConfig Save to local disk the state of fundamental configurations

Examples

//save the infrastructure info.
saveFullConfig();

restoreFullConfigFromFile

Restore a full configuration from file

restoreFullConfig

Restore a previously a configuration into the infrastructure

Parameters

• config object
• configToRestore Array<string> array of things to restore "us","agents","snapshots","graphs","custom_group","cu_templates"

activeAgentList

activeAgentList return a list of agents addresses in the callback

Parameters

• cb okcb callback called with the agent object list

Examples

jchaos.activeAgentList(function(cb){jchaos.print(JSON.stringify(cb));})

Returns Array<object> return in the callback the list descriptor of the agents

getAllProcessInfo

Return a vector of process information in the callback

Parameters

• agl Array<string> list of agents info
• cb okcb callback called with the agent object list

findBestServer

findBestServer return a list of agents ordered by occupation in the callback NOTE: this function use a tcp port the is different from REST server one (it goes directly on the server)

Parameters

• cb okcb : return a list of active agents

Examples

// find the best server to run a script:
jchaos.findBestServer(function(cb){jchaos.print(JSON.stringify(cb));})

Returns string return the best server

runScript

runScript Run the specified script on the chaos infrastructure

Parameters

• name string the name of the script present in the DB
• parm object? optional parameters
• okhandle okcb? called when ok
• errorhandle badcb? called when failed

encodeName

Encode a path name removes trailing

Parameters

• str string string to encode

Returns string encoded string

checkLive

This function used mainly in tests. It checks for a variable change on a 'devlist', for 'retry' times, checking every 'checkFreq' 'checkFunc' takes in input the live and realize the check okhandle is called if success nokhandle if fails

Parameters

• str string string to display when the check is peformed
• devlist Array<string> list of CU to check
• retry integer retry the ckeck for the given number of times
• checkFreq integer check frequency expressed in ms
• checkFunc okcb call back to call that perform the check, it takes in input the dataset to check, should return true if the check succeed or false if not
• okhandle okcb callback to call if the test complete successfully
• nokhandle badcb callback to call if the test fails

Examples

// check if the list of CUs are in start
 var cu_status=["BTF/QUADRUPOLE/QUATB001","BTF/QUADRUPOLE/QUATB002","BTF/QUADRUPOLE/QUATB003"];
 jchaos.checkLive('check Start',cu_status, 20, 1000, function (ds) {jchaos.print("testing..."); return (ds!=null)&&ds.hasOwnProperty("health")&&ds.health.hasOwnProperty("nh_status")&&(ds.health.nh_status == "Start"); }, function () { jchaos.print("CHECK OK"); }, function () { jchaos.error("CHECK FAILED"); });