Tuesday, August 4, 2009

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