Geneos XPaths

What is an XPath? Copied

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")= )][(@column="status")]

Creating an XPath Copied

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 Copied

Rules only apply to the gateway on which they are configured. If Active Console 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 Copied

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 Copied

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() Copied

This function takes no parameters and always returns true.

false() Copied

This function takes no parameters and always returns false.

wild(searchString, matchString) Copied

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) Copied

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) Copied

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) Copied

Negates a Boolean argument. The function takes 1 argument

• value : boolean : value to negate

attr(name) Copied

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) Copied

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

rparam(name) Copied

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

state(name) Copied

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

me(stripDomain) Copied

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 Copied

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

Non-identifying predicates Copied

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.

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 Copied

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

Note:  Beginning Geneos 5.5.x, the Managed Entity display name is used in the user readable paths throughout the Gateway Setup Editor, except when the GSE is opened as a standalone application. This only applies if you open the GSE within the Active Console.

Evaluate path on relative paths Copied

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 Copied

Same Row Copied

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 Copied

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 Copied

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 Copied

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 Copied

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 Copied

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 Active Console 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 Copied

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. Note: Path variables can only be utilized in path aliases for rules and cannot be used to replace column or headline names. Path variables are invalid everywhere else. 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 Copied

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 Copied

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 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:

Note: Path variables can only be utilized in path aliases for rules and cannot be used to replace column or headline names. Path variables are invalid everywhere else.

Wildcarded paths and path variables Copied

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 Path Editor). 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 Copied

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 Copied

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

runtimeParameters / Rparams

state attributes

Other Examples Copied

Displaying a SampleTime Copied

• 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 Copied

• 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 Copied

• 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)