Geneos XPaths - User Guide

What is an XPath?

XPaths are simply a way of describing an item on a gateway

Gateway/Netprobe/Managed Entity/Sampler/Data View/Row/Cell

Each element of an XPath is defined as

element_name[@property1=value][@property2=value]…

so for example a snoozed, inactive cell in the status column on the same row as the target cell is

parent::node()/cell[(state("active")="0")][(state("snoozed")="1")][(@column="status")]

Creating an XPath

Do not open up the Path Editor and try to create the path from scratch.

If a specific element is needed, the easiest and simplest approach is to left click on the element to select it, and then left click again and drag it directly into the Target. If it is one of a set of cells, select one and drag it.

Then select Edit and open the Path Editor and adjust the properties on each element to make it as general or specific as required.

  • Removing all the properties means that an element will match all elements of that type.
  • Any property can contain an * which is a wildcard.
  • If any properties are missing from the item being tested then a blank string will be passed to the match. So a blank attribute and a non-existent attribute are the same thing on the gateway.
  • It is best to always use Any for gateways as that allows the gateway to be renamed in future.

Using Evaluate path

Rules only apply to the gateway on which they are configured. If ActiveConsole is connected to multiple gateways and the Gateway is defined as Any gateway, then Evaluate Path will list cells on other gateways which match the path, even though the rule will not actually apply to them.

XPath predicates

An XPath is composed of nodes and predicates. The predicates are the expressions in the square brackets that follow a node. The predicate performs a filter on the node. So /geneos/gateway/directory/probe will match all of the probes on a gateway. /geneos/gateway/directory/probe[(@name="pr123")] will match the single probe with name "pr123". /geneos/gateway/directory/probe[(rparam("Version")="GA3.0.20-140610")] will match any probe which has a version number of "GA3.0.20-140610".

Predicate Functions

Geneos provides a set of functions that can be applied to the nodes to be filtered. They return values that can then be tested in the predicate. The following functions are provided:

true()

This function takes no parameters and always returns true.

false()

This function takes no parameters and always returns false.

wild(searchString, matchString)

This function performs a wildcard comparison on strings.

The function takes 2 arguments

  • searchString : string : the value to match
  • matchString : string : a wildcard pattern to match against

The match string is compared against the whole of the search string, character by character, except that

  • '*' in the matchString matches zero or more characters.
  • '?' in the matchString matches exactly one character.

wild-no-case(searchString, matchString)

This function performs a wildcard comparison on strings ignoring the case of letters. The function takes 2 arguments

  • searchString : string : the value to match
  • matchString : string : a wildcard pattern to match against

contains(haystack, needle)

Checks whether a "haystack" string contains a "needle" string. The function takes 2 arguments

  • haystack : string : the string to search
  • needle : string : the string to search for

not(value)

Negates a Boolean argument. The function takes 1 argument

  • value : boolean : value to negate

attr(name)

Extracts the value of a managed entity attribute. The function takes 1 argument

  • name : string : name of the managed entity attribute to get the value of

param(name)

Extracts the value of a parameter for a directory component node. The function takes 1 argument.

  • name : string : name of the parameter to get the value of

For a list of parameter names see section Extracting information > Parameters / Params

rparam(name)

Extracts the value of a runtime parameter for a directory component node. The function takes 1 argument

  • name : string : name of the runtime parameter to get the value of

For a list of parameter names see section Extracting information > runtimeParameters / Rparams

state(name)

Extracts the value of a state attribute for a directory component node, or a dataview cell node. The function takes 1 argument

  • name : string : name of the state attribute to get the value of

For a list of attributes see section Extracting information > state attributes

me(stripDomain)

Extracts the name of the user logged on to the gateway.

The function takes 1 argument

  • stripDomain : boolean : if stripDomain is true then the username returned will have the Windows domain stripped, otherwise the full username will be returned

This function can only be used on a client that is logged in to the gateway, so it is not available for use with Rules or Database logging. It is available for command targets and argument targets in commands which are evaluated on the client when the command is executed. A command which uses this function in an argument target should not be used a scheduled command, because the value returned will be "NO USER ASSIGNED", since a scheduled command is not associated with a logged in user.

Identifying predicates

Identifying predicates are expressions that can be evaluated using the gateway setup. Examples of the most common of these predicates are listed below.

Predicate Example
name @name="pr123"
row @row="r1"
column @column="c1"
type @type=""
param param("HostName")="a.bcd.com"
attr attr("DEPT")="DEV"

Non-identifying predicates

Non-identifying predicates are expressions that cannot be evaluated using the gateway setup. They need runtime information in order to be evaluated. Examples of the most common of these predicates are listed below.

Predicate Example
value @value="OK"
state state("snoozed")="1"
rparam rparam("HostName")="pr123"
contains contains(@value,".")
wild wild(rparam("AssignedUser"),"user*")
me me(true())="user7"

There are certain places where the gateway will only accept identifying predicates e.g. Rule target, Rule context, Rule Group context, Database Logging Item Target etc. If a non-identifying predicate is used then the Gateway Setup Editor will return an error showing the non-identifying predicate(s) that breach the XPath requirements of the field in error.

Relative Paths

Only use a relative path where one is actually needed - it is advisable to avoid the temptation to overcomplicate things.

Relative paths are useful for

  • cells from the same dataview
  • comparing two values on the same row

Evaluate path on relative paths

It is possible to use the Path Editor in the GSE to test relative paths by using the evaluate path button. When used with a relative path, user needs to provide an XPath that the relative path will be tested against. For example, if constructing a relative XPath to use in a command, the XPath to one of the cells the command will be run from should be used. This XPath is dragged/typed into the "Evaluate path relative to:" text box in the path editor.

The user can then construct a relative path in the work area by using the Relative Path and Data-items Elements from the toolbar area. The evaluation of the relative path in relation to the target path can be executed by pressing the Evaluate path button or the right-click menu options 'Evaluate Full Path' and 'Evaluate to this element'.

The 'edit' dialog for every element in the relative path will have dropdown lists for the Name (and Column for table cells) which are relevant to the position of the element in the path. Other properties which cannot be evaluated in a relative path will be empty, but can be filled in by the user.

Useful relative paths

Same Row

Three ways to a cell on the same row as the single target cell

../cell[(@column="status")]
parent::node()/cell[(@column="status")]
ancestor::row/cell[(@column="status")]

Same Column

A cell in the same column as the single target cell but a different row

parent::node()/parent::node()/row[(@name="activeMounts")]/cell[(@column="Value")]

A column on the same dataview as the single target cell

ancestor::rows/row/cell[(@column="filename")]

Sampling Status

Sampling Status is a headline, so two alternative relative paths from a single target cell on the dataview are

parent::node()/parent::node()/parent::node()/headlines/cell[(@name="samplingStatus")]
ancestor::dataview/headlines/cell[(@name="samplingStatus")]

Elements Above

Any element in the path above this element

ancestors

e.g. to find the gateway, probe or managedEntity, on which this element is a child, create a relative path which is the appropriate one of

ancestor::gateway
ancestor::probe
ancestor::managedEntity

There should be no need to add a property as there can only be one ancestor or each type in the path.

Note: It generally is more efficient to use a series of parent::node() statements in place of ancestor. This is because the system has to look at all ancestors and filter them, rather than directly selecting the appropriate element. A notable exception to this is going from a cell to a dataview.

Elements Below

Any element in the path below, use Descendants and Self (this is Ancestors in reverse) or

//

To find all the SamplingStatus cells below this point

//headlines/cell[(@name="samplingStatus")]

All managed entities

//managedEntity

or to select a specific one, set the value of the property

//managedEntity[(@name="cjt_gwy2_ops")]

Target names and relative paths

It is possible to reference parts of the unique path of the "target data-item" of a rule, and use this in relative paths in order to access similar data from another monitored system.

The target data-item is the item (typically a dataview cell) that the rule is run upon; this is where the severity is applied, the value is set (for compute engine rules) and/or what an action is run for.

The unique name of this item is the name that appears when selecting the "copy from name -> path" menu option in ActiveConsole when you right-click on the item.

The ability to access the target name is most commonly used to get the row name of a dataview cell. This row name can then be used to extract and compare associated values published in a different dataview, or perhaps on a different managedEntity. Instructions on how to do these tasks can be found below.

Comparing similar data from another dataview

In this example the corresponding values in the sendDataRate column of two dataviews are compared.

First a rule is created. The aim is for the cells in toolkitA to have severity (colours) applied to them, so these are made the target of the rule by dragging a cell from this column (see highlighted cell 1 above) to the rule target.

This will apply the rule to the specific cell which was dragged into the field. To apply the rule to all cells in the column, open the path editor dialog by clicking the "edit" button and clear the row properties by selecting the option in the right-click context menu.

To reference data from another dataview, it is necessary to configure a path alias. This is done in the advanced rule configuration, accessed by clicking the advanced tab at the top of the rule configuration pane.

Create a new path alias and give it a helpful name. In the example image, the name is associatedRow, as it will be used to reference an associated row in a different dataview.

The path alias is populated by dragging a cell from the associated dataview (the view containing the data we want to compare against) into the field. In this example, cell 2 from toolkitB has been dragged (please see the earlier screenshots to see the precise cell that this refers to).

Once again, because the cell was dragged in, the path alias will currently only refer to that exact cell. In order for the rule to work correctly, it is necessary to reference the cell in toolkitB that has the same row name as the target cell in toolkitA. This is done by using a path variable. Path variables are substituted when a rule is executed. In this case, a path variable is used to substitute the row name.

To do this, open the path editor by clicking the edit button, then hover over the row component of the path and click edit. In the dialog that opens, the name will be populated with the name of the cell that was dragged in. Replace this name with any variable name, as identified with a $ symbol. In the example image, the name used is row.

The path alias now references a variable named row, so this variable needs to be defined. Create a new path variable (just above the path alias definitions) and call it "row". When the variable is created, a mini rule editor pane is displayed.

The pane allows for complex expressions to be created, which are explained in the Path variable expressions section. This allows you to translate from the target data-item (cell the rule is applied on) to the secondary data-item (cell where extra data is extracted).

In the current example, however, all that is required is to copy the row name from the target data-item into the path alias, which is done using the target syntax. You can either type target "rowName" as per the example, or insert this text via the right-click menu option.

Now the path alias has been configured, it can be used to write the rule. This example compares the difference between the cell values in the two dataviews. If the values are too far apart, the severity is set to warning, and then critical if further apart.

The variable val is used in this rule to store the result of the path alias lookup. This is an optimisation to the rule, so that the value from the other cell only gets looked up once, even though the value is used twice.

Copying values using Compute Engine

Using path variables, rules can be created to copy values into a dataview, from another dataview. Following on from the previous example, it is possible to copy cell values from toolkitB to toolkitA as follows.

First start by creating an additional column in toolkitA to hold the copied values. This is done in the advanced section of the sampler configuration, in the dataviews setting near the bottom.

Save the setup and find the new column created in the dataview.

Create a new rule with one of the new cells as the target, and then erase the row name so that the rule applies to the whole column.

Then configure a path alias and path variable as for Target names and relative paths above.

The rule body is then the single line below:

value path "associatedRow" value

Path variable expressions

When a path variable is configured, the value of the variable is given by an expression. Up until now, the examples have been using basic target <name> expressions which just extract the selected name (the row name).

More complex expressions can be constructed by the use of rule functions (such as concat or stringBefore) which allow the row name (or other expression) to be processed. The resulting value is then cast to a string value before being used in the path alias.

Some examples:

Row name (from target item) Expression Resulting value (to match aliased item)
CQSE1-A target "rowName" CQSE1-A
CQSE1-A stringBefore(target "rowName", "-A") CQSE1
CQSE1-A concat(stringBefore(target "rowName", "-A"), "-B") CQSE1-B
prefix-VALUE-suffix stringAfter(target "rowName", "prefix-") VALUE_suffix
prefix-VALUE-suffix stringBefore(stringAfter(target "rowName", "prefix-"), "-suffix") VALUE

Wildcarded paths and path variables

Currently creating a pathAlias which contains a wildcard pattern is not supported by the drag-and-drop Path Editor dialog. Therefore this must be done manually by editing the path in the expert mode (See The 'expert mode' Path Editor in the Active Console 2 User Guide). Start by inserting a variable into the path (see Target names and relative paths for more details on doing this).

Then click in the path field (or switch to XML mode) to see a path similar to the following. The highlighted text shows the variable part of the path.

/geneos/gateway[(@name="TR_8600_test")]/directory/
probe[(@name="testhost_18248")]/
managedEntity[(@name="testhost")]/
sampler[(@name="p2ps User Mounts")][(@type="")]/
dataview[(@name="p2ps User Mounts")]/rows/
row[(@name=var("userName"))]/
cell[(@column="compBytesSentRate")]

To modify this to be a wildcard, it is necessary to change

[(@name=var("userName"))]

to

[wild(@name,var("userName"))]

So the path now becomes

/geneos/gateway[(@name="TR_8600_test")]/directory/
probe[(@name="testhost_18248")]/
managedEntity[(@name="testhost")]/
sampler[(@name="p2ps User Mounts")][(@type="")]/
dataview[(@name="p2ps User Mounts")]/rows/
row[wild(@name,var("userName"))]/
cell[(@column="compBytesSentRate")]

Note: To use a path variable as a wildcard pattern, it will probably be necessary to add wildcard characters (? and *) to the path variable expression in order to match using wildcards.

For example, to match rows which start with the target item rowname, the pathVariable expression should be concat(target "rowName", "*").

Commands - Useful Targets

Any and everything - e.g. give access to the command anywhere

// *

Provide the command on all managed entities, use either of

/geneos/gateway/directory/probe/managedEntity//managedEntity

Extracting information

Some commands take XPaths as arguments. For example, if the command is to run on the managedEntity or below and you need to pass in the Hostname related to this element (e.g. with a logon command), use

ancestor::probe/parameters/@HostName

i.e. find the probe above this element and then return the HostName parameter.

XPaths to return values to pass as parameters to commands

ancestor::gateway/parameters/@Port
ancestor::probe/runtimeParameters/@ConState

XPaths to return the value of a named Managed Entity attribute

ancestor::managedEntity/attributes/attribute[@name="<attribute name>"]/@value
ancestor::managedEntity/attributes/attribute[@name="OS"]/@value

Obtaining parameter values in a rule

value path "myprobe" rparam "ConState"   where myprobe is the alias ancestor::probe
value path "mygway" param "Name"   where mygway is ancestor::gateway

The contents of a cell

../cell[(@name="colname")]

but the first column is special and a row name

@rowname

The tables below show which properties can be extracted from each element

Parameters / Params

Element gateway directory probe managedEntity sampler dataview
Name X X X X
HostName X X
Port X X
Secure X X
HotStandbyRole X X
Group X X X X
Description X X
BannerVar X
Type X
PluginName X
Virtual X
Imported X
ExportingGateway X
Floating X
SelfAnnounced X
SampleInterval X
UsingSampleInterval X
UsingSampleTime X
UsingSampleInterval X
UsingFileTrigger X

runtimeParameters / Rparams

Element gateway directory probe managedEntity sampler dataview cells
UserName X X
ConState X
ImportedConState X
RejectionReason X
RejectionMessage X
OS X
Version X X X
AssignedUser X X X X X X
SampleIntervalActive X
SampleTime X
SampleInfo X

state attributes

Element name Data type Description
Severity integer Current severity -
0 = none, 1 = OK, 2 = warning, 3 = critical, 4+ = user.
Active boolean Whether the component is currently active.
Snoozed boolean Whether the component is currently snoozed.
Snoozed Parents (excluding cells)
integer Number of snoozed parents.
Snoozed Children (excluding cells) integer Number of snoozed children.
Logged (cells only) boolean Whether Value is configured to be logged to a database.
Logging success (logged cells only) boolean Whether Value is being logged successfully to the database.
User Assigned boolean Whether a user is currently assigned to the DataItem.

Other Examples

Displaying a SampleTime

  • On the Advanced tab of the sampler under Dataviews, create a headline cell on the dataview and call it SampleTime
  • Create a new rule setting
    • Target to be the headline cell SampleTime
    • pathalias SrcSampleTime to ancestor::dataview
    • rule to value path "SrcSampleTime" rparam "SampleTime"

Totalling a column to a headline cell

  • On the Advanced tab of the sampler under Dataviews, create a headline cell on the dataview and call it TotalX
  • Create a new rule setting
    • Target to be the headline cell TotalX
    • pathalias ColX to
    parent::node()/parent::node()/rows/row/cell[(@column="X")]
    • rule to value total(wpath "ColX" value)

Totalling cells only when another column contains a certain value

  • On the Advanced tab of the sampler under Dataviews, create a headline cell on the dataview and call it SelectedXTotal
  • Create a new rule setting
    • Target to be the headline cell SelectedXTotal
    • pathalias SelectX (to select only from columnX where column Y contains an "a") to
    parent::node()/parent::node()/rows/row/cell[(@value="a")][(@column="Y")]/parent::node()/cell[(@column="X")]
    • rule to value total(wpath "SelectX" value)