Interactive Shell / CLI for Jopr

Work is ongoing at a feverish pace to complete the new Jopr CLI. It is filling out quite nicely. What is this CLI, you ask? It's the long-awaited and often-requested command line interface utility for the Jopr Server.

Up until now, the only user interface into the Jopr system is via the web-based GUI. The new CLI now provides a scripting interface that allows users to tap into the Jopr system from their shell.

The CLI is actually a two-in-one utility - it can act as what people typically think of as a CLI but it is also an interactive shell (this is analogous to say, perl or python). The underlying scripting language is JavaScript - its the default Java scripting implementation found in the Java6 runtime.

Under the covers, the CLI utilizes the remote client API - this remote client API can be used by developers to write their own Jopr clients (anyone out there interested in writing a CLI GUI? :-) You can use the Java client or you can rely on the Web Services API that is exposed by the Jopr Server, allowing a client to consume the Jopr WSDLs and perform remote commands over Web Services.

I'll briefly show you just a few things you can do with the CLI. This should give you a taste for how you can interact with the CLI and some of its basic features.

First, here's the "long way" to query a list of resources and filter the results based on some custom criteria. Here I will ask the Jopr Server for all resources that have "mazzthink" in their name:

[mazz@mazzfedora bin]$ ./rhq-cli.sh -u rhqadmin -p rhqadmin -s mazzthink
RHQ - RHQ Enterprise Remote CLI 1.3.0-SNAPSHOT
Login successful
rhqadmin@mazzthink:7080$ criteria = new ResourceCriteria();
ResourceCriteria:

rhqadmin@mazzthink:7080$ criteria.addFilterName('mazzthink');

rhqadmin@mazzthink:7080$ ResourceManager.findResource

findResourceComposites    findResourceLineage       findResourcesByCriteria
rhqadmin@mazzthink:7080$ ResourceManager.findResourcesByCriteria(criteria);
id    name                                                            version        curre
ntAvailability resourceType
------------------------------------------------------------------------------------------
----------------------------------------------------------------------
10001 mazzthink                                                       Win32 5.1      UP
             Windows
10002 Trapd (mazzthink)                                                              DOWN
             SnmpTrapd
10004 mazzthink RHQ Agent                                             1.3.0-SNAPSHOT UP
             RHQ Agent
10005 mazzthink Jopr Server,  JBossAS 4.2.3.GA default (0.0.0.0:2099) 4.2.3.GA       UP
             JBossAS Server
10007 mazzthink Apache 2.2.9 (C:\mazz\apache-httpd\)                  2.2.9          DOWN
             Apache HTTP Server
10008 mazzthink Apache 2.2.9 (C:\apache\)                             2.2.9          DOWN
             Apache HTTP Server
10035 mazzthink  File System (local) C:\                                             UP
             File System
10059 mazzthink  Embedded JBossWeb Server 2.0.1.GA  (0.0.0.0)         2.0.1.GA       UP
             Embedded Tomcat Server
8 rows

A couple things to note from above. I created a ResourceCriteria that allows me to set filters, sorting and paging controls. Here I just filter on the name "mazzthink".

Second, I used the CLI interactive shell's auto-complete feature to help me figure out what methods are available on the ResourceManager. I simply typed "ResourceManager.findResource" then hit the Tab key and you see the suggestions printed out by the auto-completer. I then chose to use the findResourcesByCriteria method.

Since this is one of the most common things to want to do in the CLI (that is, query for resources), there is a shortcut method you can use for this - findResources. Below you will see me doing the same query as above, only using the "short way":

rhqadmin@mazzthink:7080$ findResources('mazzthink')
id    name                                                            version        curre
ntAvailability resourceType
------------------------------------------------------------------------------------------
----------------------------------------------------------------------
10001 mazzthink                                                       Win32 5.1      UP
             Windows
10002 Trapd (mazzthink)                                                              DOWN
             SnmpTrapd
10004 mazzthink RHQ Agent                                             1.3.0-SNAPSHOT UP
             RHQ Agent
10005 mazzthink Jopr Server,  JBossAS 4.2.3.GA default (0.0.0.0:2099) 4.2.3.GA       UP
             JBossAS Server
10007 mazzthink Apache 2.2.9 (C:\mazz\apache-httpd\)                  2.2.9          DOWN
             Apache HTTP Server
10008 mazzthink Apache 2.2.9 (C:\apache\)                             2.2.9          DOWN
             Apache HTTP Server
10035 mazzthink  File System (local) C:\                                             UP
             File System
10059 mazzthink  Embedded JBossWeb Server 2.0.1.GA  (0.0.0.0)         2.0.1.GA       UP
             Embedded Tomcat Server
8 rows

Now that I got my list of resources, I can use the results to help perform additional work. Suppose I want to know how much free memory I have on my "mazzthink" machine. I can see from my query above that the "mazzthink" Windows platform has an id of 10001. I'll pass that to the ProxyFactory.getResource method to retrieve a resource object that I can use to access information about that resource (such as its free memory metric):

rhqadmin@mazzthink:7080$ myResource = ProxyFactory.getResource(10001);
rhqadmin@mazzthink:7080$ myResource.

OSName                          OSVersion
architecture                    children
createdDate                     description
freeMemory                      freeSwapSpace
getChild                        getMeasurement
handler                         hostname
id                              idle
manualAutodiscovery             measurementMap
measurements                    modifiedDate
name                            operations
pluginConfiguration             pluginConfigurationDefinition
systemLoad                      toString
totalMemory                     totalSwapSpace
usedMemory                      usedSwapSpace
userLoad                        version
viewProcessList                 waitLoad
rhqadmin@mazzthink:7080$ myResource.freeMemory
Measurement:
              name: Free Memory
      displayValue: 872.8MB
       description: The total free system memory

Notice above I illustrate the usage of the auto-completer again. I hit Tab after typing in "myResource." and the CLI showed me all the valid measurements, operations and other methods that are available for that resource. I chose to get the "freeMemory" measurement, and you can see above that this resource has 872.8MB of free memory.

In addition to getting measurement data, another thing I can use the CLI for is to execute operations on managed resources. Continuing our example with the mazzthink platform resource, suppose I wanted to get a list of all the processes running on that box. The platform resource has a "viewProcessList" operation available to it (as you can see above from the auto-completer output). If you are unsure what operations are available on a resource, you can use the "operations" method on your resource proxy object to get the list:

rhqadmin@mazzthink:7080$ myResource.operations
name                description
------------------------------------------------------------------------------------------
----------------------------------------------------------------------
viewProcessList     View running processes on this system
manualAutodiscovery Run an immediate discovery to search for resources
2 rows

Using the CLI, we can invoke that viewProcessList operation on the mazzthink Windows platform and have the results shown on the CLI console:

rhqadmin@mazzthink:7080$ myResource.viewProcessList()
Invoking operation viewProcessList
Configuration [12186] - null
processList [99] {
  process [5] {
    kernelTime = 25140
    name = winlogon.exe
    pid = 1836
    userTime = 8156
    size = 95723520
  }
  process [5] {
    kernelTime = 31
    name = httpd.exe
    pid = 516
    userTime = 31
    size = 25780224
  }
  process [5] {
    kernelTime = 2296
    name = postgres.exe
    pid = 1572
    userTime = 937
    size = 75284480
  }
  process [5] {
    kernelTime = 159421
    name = javaw.exe
    pid = 2776
    userTime = 380347
    size = 1215180800
  }
  process [5] {
    kernelTime = 91190
    name = firefox.exe
    pid = 6088
    userTime = 251285
    size = 876466176
  }
  ...
}

And finally, to illustrate that the CLI is really a CLI and not just an interactive shell, you can pass a script command directly on the command line via the -c option:

[mazz@mazzfedora bin]$ ./rhq-cli.sh -u rhqadmin -p rhqadmin -s mazzthink -c "Pr
oxyFactory.getResource(10001).freeMemory;"
RHQ - RHQ Enterprise Remote CLI 1.3.0-SNAPSHOT
Login successful
Measurement:
              name: Free Memory
      displayValue: 884.5MB
       description: The total free system memory

The CLI also has a -f option that allows you to specify a script file to be executed - allowing you to write and prepackage scripts for execution later.

That's the CLI in a nutshell. It's still a work in progress - the remote API is still being flushed out and being enhanced to support the many use-cases we expect people are going to want to support.

The community documentation is also currently being worked on. But there is some documentation now, with more to come at the following pages:

CLI Install Documentation
Running the CLI documentation