The end of life (EOL) date for this module is on 31 January, 2020.
Executing Commands
Snoozing an item
In this example, we want to snooze the problematic DataViewET-VenueConnectivity. In the ActiveConsole, items are snoozed from the right-click menu:
We will choose manual snoozing and enter a comment explaining why we snoozed the item:
In the API, this is performed by submitting a CommandExecuteQuery, passing in the XPath of the item to snooze and the comment:
OpenAccess.Connection conn = OpenAccess.connect("geneos.cluster://localhost:2551?username=user&password=password");
String itemID = XPathBuilder.xpath()
.gateway("Montage Demo")
.probe("Electronic Trading Probe")
.entity("Electronic Trading Entity")
.sampler("ET-VenueConnectivity", "Electronic Trading")
.view("ET-VenueConnectivity").get();
CommandExecuteQuery execQuery = CommandExecuteQuery.create(itemID, "/SNOOZE:manualAllMe");
execQuery.putArgument("User comment", new CommandArgument("too noisy"));
Closable handle = conn.execute(execQuery, new Callback<CommandExecutionChange>() {
@Override
public void callback(final CommandExecutionChange data) {
if (data.getStatus() == CommandExecution.Status.COMPLETE) {
// item snoozed!
}
}
},
new ErrorCallback() {
@Override
public void error(final Exception exception) {
LOGGER.severe("Unable to execute command: " + exception);
}
});
The XPath passed to CommandExecuteQuery must uniquely identify a data item. See Paths that uniquely identify items for more information and how to check a path for uniqueness. Paths returned from API methods such as DataView.getId are guaranteed to be unique.
By changing the command name passed to the query, any other commands can be executed using the API.
Working with command output
Some commands return output from the action they perform. Examples include FKM viewFileNearTrigger and the Gateway2 Show Rules command. This output can be captured using the API.
The CommandExecution object passed to the Callback contains all the output received so far from executing the command, as well as the MIME type of the output. Most commands return text/plain, although some, like Show Rules, return text/html and others, like Licence Info, return text/uri-list.
This example grabs the output from running “Show Top 20 Processes” against a cell in a ‘hardware’ plug-in:
OpenAccess.Connection conn = OpenAccess.connect("geneos.cluster://localhost:2551?username=user&password=password");
String itemID = XPathBuilder.xpath()
.gateway("Montage Demo")
.probe("Basic Probe")
.entity("Basic Entity")
.sampler("hardware", "Basic")
.view("hardware")
.row("hostname")
.cell("Value").get();
CommandExecuteQuery execQuery = CommandExecuteQuery.create(itemID, "/PLUGIN:HARDWARE:top20Processes");
Closable handle = conn.execute(execQuery, new Callback<CommandExecutionChange>() {
@Override
public void callback(final CommandExecutionChange data) {
if (data.getStatus() == CommandExecution.Status.COMPLETE) {
LOGGER.info(data.getContent());
}
}
},
new ErrorCallback() {
@Override
public void error(final Exception exception) {
LOGGER.severe("Unable to execute command: " + exception);
}
});
When run, you should see output similar to below:
Sep 03, 2013 3:56:25 PM examples.ExecuteCommandExample$1 callback
INFO: CPU Utilisation Kernel Time System Time User Time State Clock-Speed
average 0.00% 0.00% 0.00% 0.00%
0 0.00% 0.00% 0.00% 0.00% on-line 2771.068 Mhz
Average CPU loading 0.00%
Heaviest CPU loading 0.00% on CPU 0
___________________________________________________________________________________________________
PROCESS PID USER CPU-USAGE MEM-USAGE TOTAL-MEM(KB) THREADS STATE UP-TIME ARGS
gateway2.linux 5476 geneos 1.23 % 6.33 % 0 4 Sleeping 00 Days 00:52:29 /opt/gatew ... ay2/config/gateway.setup.xml -licd-host devprodsrv01.ldn.itrs
netprobe.linux 5775 geneos 0.41 % 3.32 % 0 1 Runnable 00 Days 00:51:52 /opt/netprobe/latest/netprobe.linux -port 20001
netprobe.linux 5628 geneos 0.27 % 2.56 % 0 1 Sleeping 00 Days 00:52:08 /opt/netprobe/latest/netprobe.linux -port 20006
netprobe.linux 5520 geneos 0.14 % 2.45 % 0 1 Sleeping 00 Days 00:52:24 /opt/netprobe/latest/netprobe.linux -port 20005
netprobe.linux 5664 geneos 0.14 % 2.61 % 0 1 Sleeping 00 Days 00:52:03 /opt/netprobe/latest/netprobe.linux -port 20004
netprobe.linux 5715 geneos 0.14 % 2.45 % 0 1 Sleeping 00 Days 00:51:58 /opt/netprobe/latest/netprobe.linux -port 20007
netprobe.linux 5884 geneos 0.14 % 2.61 % 0 1 Sleeping 00 Days 00:51:33 /opt/netprobe/latest/netprobe.linux -port 20008
init 1 root 0.00 % 0.23 % 0 1 Sleeping 00 Days 00:54:47 /sbin/init
kthreadd 2 root 0.00 % 0.00 % 0 1 Sleeping 00 Days 00:54:47 kthreadd
migration/0 3 root 0.00 % 0.00 % 0 1 Sleeping 00 Days 00:54:47 migration/0
ksoftirqd/0 4 root 0.00 % 0.00 % 0 1 Sleeping 00 Days 00:54:47 ksoftirqd/0
migration/0 5 root 0.00 % 0.00 % 0 1 Sleeping 00 Days 00:54:47 migration/0
watchdog/0 6 root 0.00 % 0.00 % 0 1 Sleeping 00 Days 00:54:47 watchdog/0
events/0 7 root 0.00 % 0.00 % 0 1 Sleeping 00 Days 00:54:47 events/0
cgroup 8 root 0.00 % 0.00 % 0 1 Sleeping 00 Days 00:54:47 cgroup
khelper 9 root 0.00 % 0.00 % 0 1 Sleeping 00 Days 00:54:47 khelper
netns 10 root 0.00 % 0.00 % 0 1 Sleeping 00 Days 00:54:47 netns
async/mgr 11 root 0.00 % 0.00 % 0 1 Sleeping 00 Days 00:54:47 async/mgr
pm 12 root 0.00 % 0.00 % 0 1 Sleeping 00 Days 00:54:47 pm
sync_supers 13 root 0.00 % 0.00 % 0 1 Sleeping 00 Days 00:54:47 sync_supersHandling execution failure
Many things can occur to cause a command execution to fail. Some more common reasons are:
- The XPath passed to CommandExecuteQuery does not match an item/uniquely identify an item
- A CommandArgument is missing or has a value that is not correct
In these situations, the execution will finish with a FAILURE status. The reason for the failure will be passed to the ErrorCallback passed when submitting the query.
In the example below, the path passed to snooze does not match anything, causing a failure:
String itemID = XPathBuilder.xpath()
.gateway("not real")
.probe("not real")
.entity("not real")
.sampler("not real", "")
.view("not real").get();
CommandExecuteQuery execQuery = CommandExecuteQuery.create(itemID, "/SNOOZE:manualAllMe");
execQuery.putArgument("User comment", new CommandArgument("too noisy"));
Closable handle = conn.execute(execQuery, new Callback<CommandExecutionChange>() {
@Override
public void callback(final CommandExecutionChange data) {
if (data.getStatus() == CommandExecution.Status.COMPLETE) {
// item snoozed!
}
}
},
new ErrorCallback()
{
@Override
public void error(final Exception exception) {
LOGGER.severe("Unable to execute command: " + exception);
}
});
Sep 03, 2013 4:37:21 PM examples.ExecuteCommandExample$1 callback
SEVERE: Unable to execute command: com.itrsgroup.activemodel.commands.CommandException: Command /SNOOZE:manualAllMe does not exist for given item ID
/geneos/gateway[(@name="not real")]/directory/probe[(@name="not real")]/managedEntity[(@name="not real")]/sampler[(@name="not real")][(@type="")]/dataview[(@name="not real")]Stopping long running commands
Most commands complete relatively quickly, however some take longer and others can be configured to run continuously until terminated.
To stop a command mid-execution, call Closable.close:
String itemID = XPathBuilder.xpath()
.gateway("Montage Demo")
.probe("Electronic Trading Probe")
.entity("Electronic Trading Entity")
.sampler("ET-VenueConnectivity", "Electronic Trading")
.view("ET-VenueConnectivity").get();
CommandExecuteQuery execQuery = CommandExecuteQuery.create(itemID, "/SNOOZE:manualAllMe");
execQuery.putArgument("User comment", new CommandArgument("too noisy"));
Closable handle = conn.execute(execQuery, new Callback<CommandExecutionChange>() {
...
});
// Later on
handle.close();
There may still be some output left to process from the command so you may see a few more events on the Callback before completion.
Execute Command Code Example
This example demonstrates how to start executing a command, how to obtain the results and how to stop a long running execution.
We start viewing the probe log, receive some output from the log, then call close to stop the command.
Note: The code is included with the open access client.
The output will look something like below:
New probe log output:
Aug 23, 2013 5:30:58 PM examples.ExecuteCommandExample$1 callback
INFO: ERROR: TOP[top] No threshold parameter in setup
<Fri Aug 23 08:48:24> INFO: Inserting TOP[top] (Basic Entity) 20 secs
<Fri Aug 23 08:48:24> INFO: Inserting DISK[disk] (Basic Entity) 20 secs
<Fri Aug 23 08:48:24> INFO: SamplerManager ___________________________________
<Fri Aug 23 08:58:30> INFO: CONMGR Details: writeData(); None; 0; -808; getSockOpt() failed on fd 5 returns 32
;
<Fri Aug 23 08:58:30> INFO: ORB Master Gateway disconnected from localhost6. Gateway is STAND-ALONE.
<Fri Aug 23 08:59:30> INFO: GW Accepting connection from gateway named 'Montage Demo'.
<Fri Aug 23 08:59:30> INFO: ORB Master Gateway connected from localhost6. Gateway is STAND-ALONE.
<Fri Aug 23 08:59:30> INFO: ORB Gateway generation is 2
<Fri Aug 23 08:59:31> INFO: CACHE_PROCESS_NAMES = True
<Fri Aug 23 08:59:31> INFO: Max number of database connections defaulting to 10
<Fri Aug 23 08:59:31> INFO: CONMANAGER SLEEP_IN_TRY_HEARTBEAT is true
<Fri Aug 23 08:59:31> INFO: CONMANAGER TRY_HEARTBEAT_ITERATIONS is set to 10
<Fri Aug 23 08:59:31> INFO: CONMANAGER HEARTBEAT_INTERVAL is set to 70
<Fri Aug 23 08:59:31> INFO: CONMANAGER CONNECT_WAIT time is set to 15
<Fri Aug 23 08:59:31> INFO: CONMANAGER LISTEN_IP address is set to ALL INTERFACES on the machine
<Fri Aug 23 08:59:31> INFO: SamplerManager _________Merging Samplers_______
<Fri Aug 23 08:59:31> INFO: Inserting CPU[cpu] (Basic Entity) 1 secs
<Fri Aug 23 08:59:31> INFO: Inserting HARDWARE[hardware] (Basic Entity) 1 secs
<Fri Aug 23 08:59:31> INFO: Inserting NETWORK[network] (Basic Entity) 1 secs
<Fri Aug 23 08:59:31> INFO: Inserting TOP[top] (Basic Entity) 20 secs
<Fri Aug 23 08:59:31> INFO: Inserting DISK[disk] (Basic Entity) 20 secs
<Fri Aug 23 08:59:31> INFO: SamplerManager ___________________________________