Geneos ["Geneos"]
"1"


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:

../../ImportedGeneosImages/snooze_menu.png

We will choose manual snoozing and enter a comment explaining why we snoozed the item:

../../ImportedGeneosImages/snooze_dialog.png

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_supers

Handling execution failure

Many things can occur to cause a command execution to fail. Some more common reasons are:

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 ___________________________________