Foglight 5.9.2 - Administration and Configuration Guide

Script Console

Use the Script Console dashboard to inspect the collected data by selecting the objects of a particular topology type and viewing the data that they contain. You can use it to, for example, see the result of a scoping query, or to run scripts at the request of Quest Support, or for other maintenance functions. You can also test sample scripts from this dashboard. This feature is available to users with the Administrator and Cartridge Developer roles.

This dashboard allows you to select an object type and list the instances of that type either by listing all instances of a type or by scoping on specific instances using a query.

For more information, see the following sections:

Use the Script Console to inspect collected data by selecting an object and viewing the property values of the related data. You can also use it to see the result of a scoping query whose results appear in the list of object instances. This information is displayed in the top part of the Script Console. When you specify a query, and click Do Query, the list is populated. It contains the following columns:

In addition to inspecting objects and collected data, the Script Console allows you to write and run scripts, and save them for future use. For example, you can test sample scripts, or run scripts at the request of Quest Support, or for other maintenance functions. This feature is available to users with the Administrator and Cartridge Developer roles.

The Scripts tab displays the following columns:

A note in the top-left indicates the existence of a scoped object: No Scoping Object Selected or Current Scope Object is object name (type). Scoping on an object allows you to reference the selected object in your script using the scope variable.

Clicking Launch Service Layer Documentation opens the Java API documentation for the Foglight Service Layer. If you are using Foglight services in your script, use this information as reference.

The Add button opens the Run Script dialog box that allows you to quickly write, run scripts, and save them for future use. A collection of saved scripts is user-specific: a saved script is only accessible by the user who created it.

TIP: Click the maximize icon in the upper right corner to increase the size of the working area for writing scripts in the Run Script dialog box. Clicking this icon increases the Run Script dialog box to the full size of your browser window. By default, the working area is sized to display fifteen rows.

Clicking a script name also opens the Run Script dialog box that allows you to quickly edit and run the script.

The left-most column in the table contains check boxes that allow you to select one or more scripts, and delete the selected script by clicking Remove Selected. Select All and Select None selects all scripts and clears all selections, respectively.

NOTE: If you scoped on a topology object in Step 2, this is indicated in the title of the Run Script dialog box.

The Script Console allows you to export existing scripts to XML format, and to import scripts into the system.

Exported script files use the following XML format:

The XML file name uses the following format: exportedScripts<file_ID>.xml. For example: exportedScripts988888578404711052.xml.

It is possible to export multiple scripts into a single XML file. This causes every script to be enclosed in its own <script> element. The XML can include as many <script> elements as required.

Imported scripts take precedence over the existing scripts, so an imported script overwrites any scripts of the same name if they exist on the system. You can import any scripts that are exported from the Script Console. Alternatively, you can write XML files containing one or more scripts, and import them into the system, assuming that the file content follows the supported XML format.

NOTE: The appearance of the dialog box may be different, depending on the type and version of your Web browser.

IMPORTANT: Imported scripts take precedence over existing scripts, so an imported script overwrites any script of the same name if it exists on the system.

Your scripts often need to reference named scripts, service layer methods, and topology objects. The Service Layer API documentation can be quickly launched from the Script Console, but it does not give you syntax information for calling named scripts or invoking object-related methods.

The Help tab, available in the Run Script dialog quickly provides the information you need after typing a desired help command in the Enter Script Text box and clicking Run.

Also, if a script returns an object, unless the returned object is a String, the Help tab displays the object’s type along with a collapsible list containing the public methods defined in the object’s class and their prototypes. This on-hand reference information can help you quickly write additional scripts to obtain additional information about the retrieved object.

The help command allows you to display its syntax, list named scripts, service layer methods, class methods, and to drill down on a named script, service, or service layer method. For complete information, see the following sections:

This command provides syntax information for the help command.

This command lists all named scripts, including the scripts that come with the server, and any installed cartridges. The list is alphabetically sorted and includes a search tool. Clicking or hovering over a script name on the Help tab shows the script’s syntax information, description, and argument descriptions in a separate dialog box.

The completeness of this information depends on how well the script is documented.

With a script name passed as an argument, this command displays the script’s syntax information, description, argument descriptions, and examples.

The script name is case sensitive and does not include script arguments. For example, to display information about the script adjustHostName(arg), type help("adjustHostName"). Typing help("AdjustHostName") or help("adjustHostName(arg)") results in an error: AdjustHostName is not a valid script name.

The completeness of the displayed information depends on how well the script is documented.

This command shows the server services and the methods available for each service in a navigation tree.

Expanding a service node in the tree displays the methods defined in the service. The list of services provides a search tool.

Syntax information is provided for each method, including the return type, method name, and arguments. Clicking a service or method shows Java documentation for the selected component in a new browser tab or window.

When a fully qualified class name or a specific object instance is passed as an argument, this command lists the public methods defined in that class and provides their syntax. The methods appear as nodes in the navigation tree, with the class name as a collapsible root node. A search tool is also provided.

For example, scoping on a object instance in the Script Console and typing help(scope) displays the scoped object’s class name in a navigation tree. When expanded, the class node shows a list of public methods available for that class.

The Agent Manager Adapter, included with the Management Server, includes the agent_restore script that allows you to restore agents that appear disconnected after a server failure. It recreates any agent instances that are known to the Management Server that were deleted on a Agent Manager host. Use the Script Editor dashboard to run the script.

Table 92. Options and arguments available for restoring agents with the agent_restore script.

Option	Argument	Description
activate	true or false	Activates the agents after recreating them. Setting this value to false restores the agents to their last known state. The default is false. NOTE: If the agents are being restored asynchronously (by setting runAsync to true), they cannot be activated.
batchSize	int value	Specifies the number of agents to restore in each batch. The default is 25 agents per batch, -1 disables the operation. NOTE: When runAsync is set to true, it is recommended to have a lower number of agents per batch to prevent the server from being overloaded, as under this mode, the script sets the incoming agents to their last known state. This may involve not only recreating the agents but also activating them.
batchSleep	int value in ms	Specifies the time in milliseconds to sleep between batch runs. The default is 30000 ms.
help		Prints the syntax and argument usage information.
runAsync	true or false	Initializes the agent’s restore operation asynchronously. The default is false. NOTE: Setting this argument to true forces the activate parameter to false. This is because an asynchronous restore operation has no means to determine when an agent is restored.

Query Language

Foglight collects data from host systems and uses that data to build topology models at run-time. Each monitoring environment can include one or more topology models. The basic building blocks of each topology model are nodes, that represent object instances, and their logical relationships. Additionally, each monitoring environment includes a collection of topology types. A node in a topology model is always associated with a topology type.

The nature of the monitored environment dictates the structure and complexity of each topology model and the collection of available topology types. A basic installation of the Foglight Management Server includes a set of core topology types and each separately distributed cartridge adds to that collection.

In the browser interface, the Data dashboard shows the available topology models, their data nodes, and the hierarchical relationships between the nodes. Similarly, the Schema Browser dashboard shows the topology types and allows you to view the parent-child relationships, properties, and instances for each topology type. Use these dashboards to better understand the collected data, as reference points. For more information, see the online help pages associated with these dashboards.

The topology can be thought of as a directed graph with nodes representing topology objects and edges representing topology property relations. This sectiontopic shows how to form queries on an abstract graph regardless of how properties are set up, or in the abstract world, edge direction. In the following graphs, it is assumed that a property of name x (lower case) is of type X (upper case).

Consider a topology type B that has an observation property a and a regular property c. c has a property d that is a String.

In the following queries, we retrieve a using an important filter consisting of a literal matching pattern between the d property and the d literal value (d = 'd'). In the following examples, note how the positions of the nodes in each graph are the same, while the edge directions are different.

Table 93. Examples of query graphs for topology objects.

Graph	Query
‘a’ contains an observation
	a from B where c.d = 'd'
	Explanation: This query filters all topology objects of B type and retrieves their a observations.
	a from (C where d = 'd').b
	Explanation: The query filters all topology objects of type C, retrieves their b properties followed by retrieving the a observations from that set of b properties.
‘a’ contains a topology object or an object property
	(B where c.d = 'd').a
	Explanation: The query filters all topology objects of type B and then retrieves the a objects from that set of b properties.
	A where b.c.d = 'd'
	Explanation: The query filters all topology objects of type A.
	A where b in (C where d = 'd').b
	Explanation: The query filters all topology objects of type C, and forms a set S of the results’ b property objects. Then it filters all objects of type A by checking that their b property is in S.
	(C where d = 'd').b.a
	Explanation: The query filters all topology objects of type C and uses the resulting set as the base to find the desired a properties.

Topology queries can be in a simple form, or become as complex as needed to find just the topology objects you want.

This tutorial begins with a query for the set of all EJBInstance topology objects that exist in your environment. The syntax for this query is:

The exclamation mark says that this is a topology query, and is followed by the Topology type name. The above expression illustrates a very compact syntax.

NOTE: In rule conditions and derived metric expressions, queries are enclosed in number signs '#'. They mark the beginning and the end of a query. In addition to their use rule conditions and derived metric expressions, some Foglight commands take query expressions as arguments. Those types of queries are not enclosed in number signs '#' and do not require the exclamation mark '!' to mark the beginning of the query. For more information about Foglight commands and their syntax, see the Command-Line Reference Guide.

You can filter topology objects by their properties. For example, if you want just those EJBInstances who have their name property set to inst1-1, express your query in the following way.

The where is a filter, functionally similar to an SQL WHERE. If you like keeping your query compact, you can replace the where keyword with a colon. It has the same meaning.

In addition to querying properties with specific values, you can also write queries that select objects with null properties. To do that, use the null keyword preceded with a dollar sign ‘$’. Depending on the context in which the query is used, in some cases you need to escape the dollar sign ‘$’ with a backslash ‘\’. For example:

qs = server.get("QueryService")

objs = qs.queryTopologyObjects("Host where os = \$null");

When searching for null values in embedded queries, there is no need to use the backslash ‘\’. For example:

To write fast queries, it is important to know how the Query Service works. Let’s examine how our query is evaluated.

When the Query Service evaluates this query, it first retrieves the set of all EJBInstance objects, checks each one to see if the name is equal to inst1-1, and finally returns the subset of objects that match.

Without knowing anything about the topology, it is impossible to say whether this query completes quickly or slowly, depending on the number of EJBInstance objects in your environment. This could be a fast query if the set of EJBInstance objects is small, or a slow query if the set of EJBInstance objects is large.

As a query writer your rule-of-thumb is to keep the set small. To do this you need to understand the topology model, and any options you have available in writing queries.

For example, let’s say you want those objects whose type contains the word Catalyst. A common first attempt would be to make a query for all TopologyObject instances whose topologyTypeName property contains Catalyst.

Another way to achieve the same goal is with this next query.

Which form of the query should you choose? The first query scans the set of all topology object, of every type, checking each object’s topologyTypeName property. In a typical system there will be hundreds of thousands of topology objects so the set is quite large.

The second query scans the set of topology types, matches them against the regular expression /.*Catalyst.*/, and finally returns all topology objects on the matching types. The scanned set here is typically only hundreds of types, so it’s relatively small. You should choose the second query.

If you know the exact names of the data types that you want to query, using those name is the most efficient way. For example, the following expression retrieves all hosts and agents that exist in your system:

Filters can contain multiple conditions. The following query retrieves those EJBInstance objects whose name is Alice, Bob, Carol, or Dave in an inefficient manner.

For every EJBInstance Topology object, the query engine performs the following steps:

The above query assesses the name property four times, once per condition (Alice, Bob, Carol, or Dave). You can make your query faster by reducing the number of conditions, and therefore, the number times you access the name property. For example:

The second query takes the full set of EJBInstance topology objects, and for each object will perform the following operation.

In this case the name property is retrieved only once per object, rather than four times.

This section is a catalogue of the options you have to make queries. It is broken down by the structure of how a query is put together. Every query has the same common form:

Let’s look at each part of the form separately.

There are several ways to describe the SetOfTopologyObjects element:

This is the basic way to define a set of topology objects.

This query element goes to the Topology Service with the ExampleType topology type, including all its sub-types, and retrieving all the topology objects of those types.

This is an advanced form of the topology type name. What it does is it builds a topology type definition and then retrieves the objects that meet that definition. There are many different options that you can use to extend and restrict the topology type definition that you are building. The general form for the $objectsbytype() element is as follows:

The $objectsbytype() element reads the list of type specifications and generates a resulting set of topology types. Once the type reading is complete, it retrieves all topology objects for each of the types it finds. Objects from the sub-types are automatically collected if a super-type makes it into the resulting set, even when the objects of the sub-type themselves do not directly meet the specification. We will see how this works soon in Multiple type specifications.

Next, you learn about the The type specification format.

The type specification format

The simplest type specification is just a basic topology type name.

So far, this is functionally identical to the !ExampleType syntax. The difference is that it can now be made more exact by restricting the object types to those that came from a certain cartridge and version. If you just want to just specify the cartridge, add the cartridge name with a colon:

It can be further restricted by specifying the cartridge version:

If you are not sure of these names, or you want to match multiple types or versions with a single specification, cartridge names or versions can be replaced with a Java regular expression:

The above query returns all of the objects of the matching types and their sub-type objects, regardless of their sub-type names and cartridges.

Regular expressions that use this element can also be specified without $objectsbytype. For example, both of the following expressions are valid:

!$objectsbytype(/T/)

!/T/

Multiple type specifications

Additional types can be added with a comma. For example:

This will get you all the objects of ExampleType from any ExampleCart, plus the CatalystService objects.

Besides adding on more types you can remove types from the match:

$objectsbytype(CatalystService, !/.*Data.*/)

The above query returns all of the CatalystService objects excluding those with Data in their type name. The exclamation point here means exclude.

How multiple type specifications work

Processing a multiple type specification works by parsing the list of specifications from left to right and keeping a set of types that make the match so far. Each positive specification (without an exclamation mark) adds new types to a set of types, while each negative specification (with an exclamation mark) subtracts from that set.

This approach gives a lot of flexibility. Consider a type hierarchy A?B?C, where A is the super-type of B, and B is the super-type of C. If we want to query for objects of types A, B, and C, then we can write the following:

IMPORTANT: Keep in mind that querying on a super type returns the objects of the sub-types.

Let’s change it a bit. Suppose we want objects of types A and C, but not B. In that case, form the query in the following way:

As the query parser scans the multiple type specifications from left to right, it performs the following actions and maintains the working set in the following states.

Table 94. Changing the order of type specifications changes the output.

Element	Action	Working set of types
$objectsbytype (	Initialize working set	{}
A	Add A, B, C	{A,B,C}
!B	Remove B,C	{A}
C)	Add C	{A,C}

As you can see, the order of the type specifications is important. For example, switching around !B and C to $objectsbytype(A, C, !B) returns a working set of types that contains only the A type ({A}).

If a query appears within a rule or a script, it includes a scoped topology object. For example, a rule can be scoped to the set of JVMs you are monitoring. Prior to this rule being evaluated, the set of all JVMs is retrieved with the following query:

Then, at evaluation time, the rule executes its evaluation code for each JVM object in that set. In this example, queries within that evaluation code can use the $scope variable to get their particular JVM object against which they are run.

$objectsbyid() can be used to explicitly point to certain objects by their unique IDs:

Here is an example that identifies a set of three topology objects by their IDs:

It works by directly asking the Topology Service for the latest versions of these objects.

Negation of $objectsbyid is ignored. For example, the following expressions are equivalent:

and

A topology model is a set of object nodes and links between them. The links are called properties, and as a whole, the set of topology objects and their properties form a model that you monitor with the Foglight Management Server. For any topology object, its properties can point to other topology objects, which in turn have properties that point to other topology objects, and so on.

The result of evaluating a property path is a SetOfTopologyObjects. The general form of the property path is:

The root of the path can be any of the forms for defining a SetOfTopologyObjects. Here are examples of each element with property path examples.

NOTE: Although these examples are just one or two properties in length, paths in general do not have limited length.

Table 95. Examples of elements and their property paths.

Element	Example
Basic type	(JVMGarbageCollector).jvm.localStateSeverity
Advanced type	$objectsbytype(/JVM.*GarbageCollector/).jvm
$scope	$scope.jvm.localStateSeverity
$objectsbyid	$objectsbyid('0193339a9c27').jvm

The result of walking a path is the set of objects from the end of the path. For example, the path in the first example, (JVMGarbageCollector).jvm.localStateSeverity, returns a set of AlarmSeverity objects. These are the localStateSeverities from the JVMs of all JVMGarbageCollectors that exist in the topology model.

Property typing

Property paths are static in nature. Properties are associated with topology types and not the topology objects.Topology objects contain property values. The query engine interprets property paths by evaluating properties from the topology types, and then populating the resulting path with the values associated with the related topology objects.

When you write a query, you are working with type properties. It doesn’t matter if all of the selected objects all have the property referenced in a query, what counts is the property type. This illustrated in the following example:

In this query, we find every TopologyObject object whose topologyTypeName property matches the regular expression '.*GarbageCollector', and from that set of objects, we retrieve the 'jvm' property. It is very likely that every TopologyObject object whose name matches '.*GarbageCollector' does have a jvm property, but the query engine is not aware of this. Instead, while it builds the path, it looks strictly at declared types, and sees that you are trying to reference the jvm property from a TopologyObject object.

The following example results in an error:

That is because the TopologyObject type does not include a jvm property. The right way to do this query is by using $objectsbytype():

In this version of the query, we are working directly with types. The query engine finds the least common ancestor of all types that match the regular expression. If that type has a jvm property, then the query retrieves one or more values, otherwise it throws an error.

Collection properties

Collection properties hold more than one topology object. Usually the type of this collection property is the TopologyObject type, so that it can act as a collector of objects. Unfortunately, this makes it hard to reference properties out of them. An example collection property is a Host object’s detail property:

The detail property is a collection of TopologyObject objects. They can all be RemoteClient objects that include agentAdapterName properties, but you cannot get to that agentAdapterName property because you are trying to de-reference it from the TopologyObject type. For that reason, the following query is invalid.

The right way to perform this query is as follows.

In the above example, agentAdapterName is now referenced from the RemoteClient type. This query also introduces logical operators and the $object keyword. These are explored in Properties .

The Basic type example from A walk along a property path is actually a special case of a more general use. Instead of putting a topology type name in the parentheses, you can insert a complete topology query.

Or:

This allows you to introduce filters along the property path.

The first example finds those JVMGarbageCollector objects and filters them to obtain only those which contain the Gen sub-string for Generational collectors. It then goes from that set, off to their jvm objects, and finally to the localStateSeverity objects.

The second example starts at the scoping object, walks to its jvm objects and then filters those by names ending with a 1. After filtering, the query uses the remaining topology objects to find their localStateSeverity objects.

For sub-queries without filters, there is no need to enclose them in parenthesis. For example:

And:

This concludes what you can do to create a SetOfTopologyObjects. The next topics cover the WHERE clause, breaking it down into two parts:

The query engine interprets properties and property paths in filters just like property paths in the definition of the SetOfTopologyObjects with some differences. The basic behaviors are described in Property typing and Collection properties .

The differences between how property paths are interpreted in SetOfTopologyObjects and those in filters are as follows:

Our first example query in this tutorial illustrated the first two differences. When we say the following:

This means that name is a property of the EJBInstance topology type, and each topology object of the EJBInstance type includes a value for that property. In this case, the property path length is one, and the tail value is a String.

There are cases where you want to make checks against topology objects coming out of the SetOfTopologyObjects themselves, rather than one of their named properties. In this case you can use $object instead of the property name. We have an example in Collection properties that uses $object.

To simplify the example, you can drop the condition on the agentAdapterName property:

The above statement instructs Foglight to retrieve all RemoteClient topology objects, where those objects ($object) appear in Host objects’ detail property.

In a sense, there is an implicit $object prefix in all property uses. The query !EJBInstance : name = 'inst1-1' can be rewritten to use an explicit $object. There is no difference, it is just more verbose:

The $object.name property is actually a property path. There is no length limitation on property paths within the filter. The only difference from SetOfTopologyProperty paths is that you cannot introduce filtering WHERE clauses into these property paths. For example, the following query is incorrect:

Instead, re-write the above query in the following manner:

This query returns those JVMGarbageCollector topology objects whose jvm name is x and the localStateSeverity property is the scoping topology object.

This topic describes the following operators that you can use in queries:

The in operator has two meanings. It can mean that the tail of the property path appears in:

Explicit set of strings

We use the first form of in when we want to say that a property has one of a number of String values:

The above query returns those EJBInstance topology objects whose name property matches inst1-1 or inst1-2. It is preferable, to saying:

A set of topology objects

The second form of in is used to say that the tail of a walk along a property path is a member of another set of topology objects:

The like operator tests the equivalence of a property value and a SQL-type expression. For example, the following query retrieves one or more hosts whose name uses the pattern %.mydomain.com.

Similar to like, matches tests the equivalence of a property value and a Java regular expression. For example, the following query retrieves object instances of the J2EEExecuteQueue type whose name uses the pattern Nexus.*.

For more information about regular expressions and the syntax that you can use in Foglight, see the Command-Line Reference Guide.

The isa and instanceof operators check if an object instance is an instance of a particular type. For example, the following query returns all Host object instances whose detail property if of the type RemoteClient.

The topology model has a tree-like structure. In that structure, an object can contain one or more child objects, that, in turn can contain one or more child objects, and so on. The existence of these parent-child relationships can be tested using the contains and within operators. These operators are followed by an indicator that defines the number of levels in the topology model that are selected by the query, relative to target object. The indicator is comprised of the caret sign, ‘^’, followed by a number that specifies the number of levels, or inf, that stands for no limit. For example, ^2 indicates that the query is issued against two levels above (in the case of within) or below (in the case of contains) the selected object in the topology model, while ^inf indicates that all levels are selected.

The contains operator checks if an object contains a particular child object within a specific set of the topology model. For example:

The within operator checks the if an object is contained within particular a parent object. For example:

The equals operator tests the equivalence between a property value and a given literal value. For example, the following query retrieves those EJBInstance object instances whose name property is set to inst1-1:

The union operator is used to combine results of several sub-queries.

!union( Host, JVM )

!TopologyObject where $object in union( Host, JVM )

NOTE: When a sub-query contains a WHERE clause, it should be enclosed in parentheses: !union( (Host where name='foo'), JVM )

A query can contain one or more numeric comparisons in the WHERE clause. They can be used to compare two numeric values. For example, the following query returns those Host object instances that have no existing warning alarms.

Additionally, to compare date and size values, you can use the Date and size functions.

Any of the above operators can be negated by prefixing the operator with either an exclamation mark ‘!’ or NOT. The following statements are all equivalent.

You can use the logical operators AND and OR. For example, the following says that either of the conditions is met.

If you want to write a complex condition with numerous AND and OR operators, you should use parentheses to explicitly define how the logic works. The two following examples show how different parentheses can yield different logic.

Example A

Example B

Examples of using OR

Examples of using AND

These functions create date types for comparison with date properties.

date( year, month, day )

NOTE: The timezone parameter is the same as the time zone ID in the TimeZone class. For more information, visit: http://download.oracle.com/javase/1.4.2/docs/api/java/util/TimeZone.html

collectionOrArrayOrStringProperty.size()

!Type where collectionOrArrayOrStringProperty.size() = 1

NOTE: When using the size(stringNamedParameter) format, only String-type parameters are accepted. In practice, this limitation means that instead of: !Type where prop.size = size(:collection) you should pass the collection size as the parameter: !Type where prop.size = :collectionSize

Parameter values are set using com.quest.nitro.service.sl.interfaces.query.IQueryStatement.setParam(String, Object).

NOTE: Automatic collection expansion in IN {}, $objectsbyXXX: The new query engine expands collection values when appropriate for the named parameter usage.

The use of syntax shortcuts such as ‘->’, ‘:’, ‘,’, ‘|’, ‘||’, ‘&’, ‘&&’, and ‘!’) is supported, but not recommended. With that in mind, the following expression is still a valid query:

The above expression is equivalent to:

The use of syntax shortcuts is supported but discouraged.

Table 96. Syntax shortcuts.

Short form	Proper form
:	where
->	instanceOf
|	or
||
&	and
&&
!	not

The query engine supports escaping of query elements to enable backward compatibility. For example, \char is replaced by char. Additional examples:

Table 97. Escaped elements and their translations.

Escaped element	Translates to
\\	\
\"	"
\'	'
\y	y

The syntax reference described in this section uses the following conventions:

Table 98. Syntax definition reference.

Element	Description
RESERVEDWORD	In this section, reserved words are written using upper case to improve readability. In general, reserved words are case insensitive. For example, both of the following expressions are valid: !$objectsbytype(T) where $object instanceof Q and: !$objectsByType(T) where $object instanceOf Q
'{'	Character literal.
[ element ]	Optional element.
element1 | element2	Element 1 or element 2.
( grouped elements )	Grouping of elements.
element*	The element is repeated zero or more times.
element+	The element is repeated zero or more times.
(* Comment *)	Comment.

Begin by looking at the queries that are strictly within the domain of the Topology Service. A simple example would be querying for all topology objects of type EJBInstance.

NOTE: Queries against the topology service return topology objects. For example, querying the topology service for a list of agents returns a set of topology objects instead of agent objects as it may be anticipated. Any methods exposed in the Foglight API that are available to objects of other types can not be applied to the set of topology objects returned by the query. Only those methods that are available to topology objects only can be applied to the returned topology objects.

We will now look at the following example.

Type the following:

You can filter the set of topology objects that you get back based on their properties. For example, if you want all EJBInstances who have their property name set to inst1-1, then you would express your query in the following manner.

Additional property conditions can be added using a comma as a separator, as follows:

Add an extra condition is with an and instead of the comma:

The query language also supports ‘or’ and precedence with parentheses.

The and/or keywords have convenient shortcuts. In place of an and you can use & or && and in place of an or you can use | or ||. There is also an alternative syntax for not equals (!=), which is <>.

So far, we have only used exact string matching. We can also use limited regular expressions with the like operator. To get all the EJBInstances where the name starts with “inst”, write the following query:

Besides the percent sign ‘%‘, the other regular expression element that you can use is the underscore ‘_‘, which is a required match to any character.

You can also ask for an exact match from within a set of strings.

NOTE: Regular expression matching from within a set is not yet supported.

You can specify the negation of a condition. For example, if we want only those EJBInstances whose name does not start with inst we can change the above query as follows:

Equivalently, we can write any of the following.

Note that if a not is put before a comparison, then the entire comparison must be enclosed in parenthesis.

Property conditions can express programmatic relationships. For example, if you want all EJBInstances where the name property of the EBJInstance’s application property is set to app1-1, write the following expression:

When a query is made, it can be made within a scope. A scope is simply a handle to some known topology object and is represented in the query by the keyword: $scope. If you want to find all siblings of the current EBJInstance according to their ejb, write the following expression:

There is one more way to do filtering, and that is by checking whether a topology object is a particular set of objects. For example, if you want to query for all EJBInstances on the same server (the property we are interested in) that the current scoping EJB is on, use the following expression:

(EJBInstance where server in $scope.instances.server)

Finally, a topology object query can be used as the base of a programmatic walk through object properties. For example, if you want all the EJBInstances from all EJBs that are named ejb1, you can first ask for the EJBs and then look at their instances. To do this use the following expression:

As you might expect, this query can have filtering conditions applied to it, too. If you want to retrieve only those EJBInstances from above who additionally have their names starting with inst, use the following expression:

Another way to write this query is as follows:

There are two differences between topology queries and metric queries. One is that you prefix your query with a metric name and optionally suffix your query with a time period. The other is that there are fewer parentheses required because you’re using the keyword from.

Foglight agents collect metrics from monitored hosts and send them to the Foglight Management Server in batches. The length of an agent's collection period for a batch is specified in the agent properties. A metric query that includes a time component retrieves the batch of data that exists on the server at the time specified by that time component, not the batch of data collected at the time specified by the query, as it may be expected. For example, the query ruletteCount at 15:00 on 2007-09-26 retrieves the batch of data for the ruletteCount metric that exists on the server at 15:00. As seen in the example below, the start and end time of the collection period for that batch indicate that the collection period started at 14:22 (startTime) and ended at 14:59 (endTime).

Table 99. Data for the ruletteCount metric.

uniqueId	f0484b82-186e-4d97-b2d0-6d0d2fb3db98
startTime	9/26/2007 14:22
endTime	9/26/2007 14:59
samplePeriod	2250000
count	75
min	0
max	35
avg	22.86666667
sum	1715
sumSquares	56425
stdDev	15.1475704

For example, if you want to get the collect the invocationTime for all EJBInstances over a period of 1.5 hours, write the following expression:

You can also use a registry variable (here called myDuration associated with the current scoping topology object to specify a time period.

As mentioned above, you can still use the mechanisms associated with topology queries. For example:

Also, if you have a scoping EJBInstance topology object you could query for its invocationTime in the following way:

Because this is a common idiomatic case for the Rule Engine, there is a short-hand for from $scope in the above.

In this case, the language interprets that there is no sub-query for topology objects, so it assumes that the invocationTime metric is attached to the current scoping topology object. It implies a $scope clause in the query.

The time period is optional. If you just want a current invocationTime from the current scoping topology object, write the following expression:

Time periods can be used for baselining. The idea is that instead of querying for recent metrics based on the current time, you can get older metrics from either a certain date or an offset of a number of days, weeks, months or years into the past.

The first way to do this is to append an ago clause.

This statement looks at the current time, chooses the same calendar instant from week ago, and selects the 1.5 hour period immediately prior to that 1 week ago instant. For example, if it is currently Monday morning at 9:00 AM, this statement goes back to last week’s Monday morning and select the invocation time from 7:30 AM to 9:00 AM. Note that leaving off the ago clause will produce the same period of time (except on today) allowing for apples to apples comparisons with visually similar queries.

The second clause we can append is an on clause.

This works the same way as the previous example, except that instead of using a relative offset, we specify an absolute date to select the data from. Again, if it is currently 9:00 am, this query selects the data collected from 7:30 am to 9:00 am from May 25, 2009.

These clauses give wall clock equivalent comparisons, that is, they compare 9:00 am today to 9:00 am in the past. If you want to compare 9:00 am today to a different wall clock time in the past you can use a spanning clause.

The above query selects data from 1:00 pm to 2:30 pm on May 25, 2009. If you want, you can specify time ending at a certain point as well.

And finally, you can use the relative offset with a spanning clause.

Time zones can optionally be added to a spanning clause.

Examples of acceptable formats for the time zone are:

In general, any of the formats supported by java.util.TimeZone.getTimeZone() can be handled here.

Instead of asking for a metric over a period of time, you can also single metric at an instant. It works just like asking for the most recent metric, except the system pretends that the wall clock is set to the time you have specified. The way you specify wall clock time is by giving a 24 hour time value and a date. The 24 hour time value is optional and the date may either be an absolute date or an offset of a number of days, weeks, months or years into the past. The following examples show the different ways the syntax can look.

This query takes the most recent metric, pretending that it is 1:00 PM on Monday, May 25.

The use of a 24 hour clock, although preferred, is not mandatory. You can use the following expression to retrieve the same data set:

The following query retrieves the most recent metrics, pretending that it is 1:00pm, 2 days ago:

The following query instructs the query engine to take the current wall clock time, apply it to May 25, and find the most recent metric at that time.

And finally, the following query instructs the query engine to take the current wall clock time from 2 days ago, and find the most recent metric at that time.

Although the last two forms of query exist for completeness sake, they are not thought to be useful in a typical business scenario.

The scope of a rule defines the set of topology objects against which it will run. The scope of a derived metric defines the set of topology objects to which it applies. A rule or derived metric must be scoped to a topology type and can optionally be scoped to specific instances of that type (topology objects). If a rule or derived metric is not scoped to specific objects, it applies to all objects of that type.

Optionally, after selecting a topology type, it is possible to restrict the scope to specific instances of the selected type using the Scoping Query Editor, either by selecting specific object instances, using a property matching filter, or writing he scoping query manually.

NOTE: If you need to define more than three expressions in the filter, you can add them after closing the Scoping Query Editor dialog box.

You can use the syntax shown in one of the examples below to manually specify all or part of the scoping query in the box immediately below the Topology Type and Property boxes. This field is case-sensitive.

Use these examples only as guidelines with regard to the query language syntax. There are many additional ways of specifying a scoping query. For complete information about the query language syntax, see Topology query reference.

A condition is the part of a rule that is evaluated against monitoring data. When creating a simple rule or when configuring a severity level for a multiple-severity rule, you must specify a condition.

Like rules, derived metrics can be scoped to topology types or object instances and contain an expression that is calculated at runtime. Foglight uses this expression to calculate the derived value.

TIP: If you want to include an email address in a message, simply use the @ symbol twice. For example: Send email to administrator@@example.com

TIP: To reference registry variables in expressions use the syntax registry("registryVariableName").

TIP: To reference metrics in expressions use the syntax #metricName#.

CAUTION: Although you can insert a registry variable into a derived metric expression, it is not recommended that you do so. Using a registry variable in a derived metric expression could lead to unpredictable and confusing results since the resulting metric might change its definition at different points in time.

Derived metric expressions and rule conditions and expressions are matched against monitoring data. Foglight can perform functions on this data. Functions cause calculations to be performed on the data specified in conditions and expressions, allowing the data to be modified before it is matched.

Most of the default functions available with Foglight cause calculations to be performed on metrics. In addition, the functions alarmCount, changeSummary, descendents, findObservationEntries, getContainedObjects, and getObservationTrend cause values to be returned for topology objects (based on a specified scope). In most cases, you specify scope as the parameter for one of these functions; using the scope variable causes the function to be performed on the topology objects included in the rule or derived metric scope. However, there may be situations in which you want to specify an alternate scope. See Advanced scripting example for more information.

The following functions are supported by Foglight for use with rule conditions and expressions and derived metric expressions:

NOTE: Foglight supports embedding named scripts into cartridges by editing their monitoring policy. In that file, only those named scripts that are marked as functions appear in the list of functions on the Function tab of the Condition Editor (rules) or Expression Editor (derived metrics) dialog box. This excludes any custom queries that are added to the monitoring policy. Custom queries cannot be used in rule conditions.

In most cases, you use the scope variable as a parameter for the functions alarmCount, descendents, and getContainedObjects. However, there may be a situation in which you need to create a condition or expression that uses one of these functions but want the function to be performed on an object outside of the rule or derived metric scope.

For example, if you wanted to compare the alarm count for objects within the scope of a rule with the alarm count for a specific server that is not within this scope, you could specify a condition using the following syntax:

Where Server_IP is the IP address of the server. For example:

NOTE: In the example shown above, the exclamation point ‘!’ implies that the argument passed to the alarmCount function is a topology object property and not a metric.

This sectiontopic provides answers to the following FAQs:

If the rule is scoped to the topology object that has that property, you can reference the property using the scope variable. This variable contains a reference to the topology object against which the expression runs.

For example, you are interested in the property filesystemName, you can use the following in an expression to obtain the property value:

If you want to reference the topology object from within a string or embedded query, you must prefix the scope variable with the dollar sign ‘$’. For example:

or

The fglcmd tool includes a command that allows you to export metric observations to a file using a metric query. The metricexport command can be used to export metrics to a CSV or XML file.

For example, the following command exports the values of the Process metric collected in the past two hours to a CSV file.

For complete details on how to configure fglcmd, and about the util:metricexport command, see the Command-Line Reference Guide.