Geneos - XPath Quick Guide with Examples

Introduction

An XPath is a way of describing an item on a gateway. The XPath syntax can be described as a sequence of steps, each one optionally filtered by a set of predicates.

/ <step> <predicates> / <step> <predicates> / ...

/ geneos / gateway [pred1] / directory / probe [pred1] [pred2] / ...

Currently, predicates are restricted so that you cannot evaluate another xpath within a predicate - you can only call functions and access the attributes of the current step node. For this reason, several functions have been created to enable you to access common attributes in a child node which would otherwise be inaccessible (see functions below).

For best performance, it is recommended that paths only contain the names of directory components in order. The full paths possible are then as follows. These can of course have predicates added.

/geneos/gateway/directory/probe/managedEntity/sampler/dataview/rows/row/cell

/geneos/gateway/directory/probe/managedEntity/sampler/dataview/headlines/cell

Predicate Functions

As mentioned above there are several accessor functions which can be used to extract values. These are listed below, along with the number of arguments they take and what each argument should be.

true()

Produces the Boolean value true, takes 0 arguments

/geneos/gateway[state('snoozed')=true()]

false()

Produces the Boolean value false, takes 0 arguments

/geneos/gateway[state('snoozed')=false()]

wild(searchString, matchString)

Performs a wildcard comparison on strings, takes 2 arguments

1. 1. searchString - the value to match
   2. matchString - a wildcard pattern to match against

/geneos/gateway[wild(@name,"test*")]

wild-no-case(searchString, matchString)

Performs a wildcard comparison on strings ignoring the case of letters, takes 2 arguments

1. 1. searchString - the value to match
   2. matchString - a wildcard pattern to match against

/geneos/gateway[wild-no-case(@name,"TeSt*")]

contains(haystack, needle)

Checks whether a "haystack" string contains a "needle" string, takes 2 arguments

1. 1. the "haystack" string
   2. the "needle" string

/geneos/gateway[contains(@name,"test")]

not(value)

Negates a Boolean argument, takes 1 argument

1. 1. the Boolean to negate

/geneos/gateway[not(contains(@name,"test"))]

attr(name)

Extracts the value of a managed entity attribute, takes 1 argument

1. 1. the managed entity attribute name to get the value of

/geneos/gateway/directory/probe/managedEntity[attr("attr_name")="some_value"]/sampler/...

Note: The value of the argument should be used in some kind of comparison operation. To get the attribute value on its own, use the path:

/geneos/gateway/directory/probe/managedEntity/attributes/attribute[@name="attr_name"]/@value

rparam(name)

Extracts the value of a runtime parameter for a directory component node, takes 1 argument

1. the name of the runtime parameter to get the value of

/geneos/gateway/directory/probe[rparam("ConState")="Up"]

To extract a value using an xpath (rather than filtering by predicate), use:

/geneos/gateway/directory/probe/runtimeParameters/@ConState

param(name)

Extracts the value of a parameter for a directory component node, takes 1 argument

1. the name of the parameter to get the value of

/geneos/gateway/directory/probe[param("HostName")="linux165"]

To extract a value using an xpath (rather than filtering by predicate), use:

/geneos/gateway/directory/probe/parameters/@HostName

state(name)

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

1. the name of the state attribute to get the value of

/geneos/gateway/directory/probe[state("severity")>1]

To extract a value using an xpath (rather than filtering by predicate), use:

/geneos/gateway/directory/probe/state/@severity

Operators

In addition to the above functions, the following operators are available for use inside of a predicate:

• - unary negation operator e.g. -(5+3)

• = != < <= > >= equality tests

• + - * / arithmetic operations

• mod modulus operation
• ( ) parentheses used for grouping expressions

Back to the top

State Attributes

States can be accessed either using a direct path, or by using an accessor function (see functions above). E.g.

/geneos/gateway/directory/probe/state/@severity
/geneos/gateway/directory/probe[state("snoozed")=0]/managedEntity/sampler/...

Directory components (and cells) contain the following attributes:

• state/@severity - current severity (integer), 0=none,1=ok,2=warning,3=critical,4+=user
• state/@previousSeverity
• state/@active - current active? (Boolean)
• state/@snoozed - currently snoozed? (Boolean)
• state/@logged - cells only, whether the value is configured to be logged to database (Boolean)
• state/@loggingSuccess - only for logged cells, whether value is actually being logged successfully (Boolean)
• state/@userAssigned - whether a user is currently assigned to the dataitem (Boolean)
• state/@hasKba
• state/@hasDirectKba

Back to the top

Managed Entity attributes

Managed entity attributes are configured by the user, and so will not have a fixed name. Attribute values can be accessed through an accessor function (see functions above). E.g.

/geneos/gateway/directory/managedEntity[attr("user_attribute")="some_value"]/sampler/...

Back to the top

Attribute Listing

The following shows which attributes can be extracted from each XPath element:

geneos

• contains no attributes

client

• parameters
  • HostName - the client machine's hostname
• runtime parameters
  • Username - the name of the user on the client machine
  • Domain - the domain of the user on the client machine
• features/
  • @RuleShowEx - whether the client supports the extensible show rule format

gateway

• name - the gateway name (string)
• id - the gateway id (integer)
• parameters
  • HostName -the gateway hostname or IP address (string)
  • Port - the gateway port (integer)
• runtime parameters
  • Username - the user that the client used to connect to the gateway

directory

• name - the gateway name (string)
• id - the gateway id (integer)
• parameters
  • HostName - the gateway hostname or IP address (string)
  • Port - the gateway port (integer)
  • HotStandbyRole - the configured role of the hot standby configuration, can be Unknown
• runtime parameters
  • Username - the user that the client used to connect to the gateway
  • HotStandbyState - the state of the hot standby configuration, can be Inactive
• state
  • standard directory state parameters (see below)

probe

• name - the probe name (string)
• parameters
  • Name - the probe name (string)
  • HostName - the probe hostname or IP address (string)
  • Port - the probe port (integer)
  • Group - the probe group (string)
  • Description - probe description (string) may contain newlines
  • Virtual - whether this is a vritual probe (string), "true" if virtual, "false" otherwise
• runtime parameters
  • ConState - probe connection state (string), possible values include:
    • Up - connection up
    • Down - connection down
    • Rejected - probe refused connection
    • Unreachable - unable to contact probe host
  • RejectionReason - if state rejected, the reason it was rejected as an error code (integer)
  • RejectionMessage - if state rejeceted, the reason it was rejected as text (string)
  • OS - probe host OS version (string)
  • Version - probe version (string)
  • Support - supported features of probe (string)
  • salt - password salt text (string)
  • AssignedUser - name of the assigned user
• state
  • standard directory state parameters (see below)

managedEntity

• name - managed entity name (string)
• parameters
  • Name - managed entity name (string)
  • Group - group (string), do not confuse with managed entity group
  • Description - description (string), may contain newlines
  • BannerVar - xpath to banner variable data item (string)
• runtime parameters
  • BannerVar - value of the banner variable data item
  • AssignedUser - name of the assigned user
• attributes (user-defined attribute names and values)
  • attribute
    • name - the user-defined attribute name
    • value - the user-defined attribute value
• state
  • standard directory state parameters (see below)

sampler

• name - sampler name (string)
• type - $type for this sampler (string), may be empty for no type
• parameters
  • Name - sampler name (string)
  • Type - sampler $type (string)
  • PluginName - plug-in name in upper-case (string)
  • SampleInterval - the sample interval (integer)
  • Group - sampler group as configured by user (string)
  • Description - description (string), may contain newlines
• runtime parameters
  • AssignedUser - name of the assigned user
• state
  • standard directory state parameters (see below)

dataview

• name - dataview name (string)
• parameters
  • CreateOnGateway - true for a Gateway-controlled dataview (i.e., entirely populated by Compute Engine rules and independent of its parent sampler). Not present otherwise.
  • Group - group name (string), as configured by user
  • OverviewType - type name for dynamic overview (string), defaults to plug-in name, or PLUGIN-VIEW for plug-ins with multiple views
• runtime parameters
  • AssignedUser - name of the assigned user
  • SampleInfo - replacement text for 'Sampling every X seconds' message
  • SampleNowAllowed - if false, disables 'Sample now' button in AC2
• state
  • standard directory state parameters (see below)

headlines

• no attributes

headlines / cell

• name - headline name (string)
• value - headline value (string)
• state
  • standard directory state parameters (see below)
• runtime parameters
  • AssignedUser - name of the assigned user

rows

• no attributes

row

• name - the row name (string), can also be accessed using the first column (e.g. processName for PROCESSES plug-in)

row / cell

• column - the column name (string)
• value - the cell value (string)
• rowname - the row name (string)
• state
  • standard directory state parameters
• runtime parameters
  • AssignedUser - name of the assigned user

Back to the top

XPath Setup

Each Gateway contains a directory of every item within it. The directory is a tree structure. The root of the tree is the Gateway and below that are configured probes, managed entitles, samplers, dataviews, cells and headlines.  These are added to the directory as they become live. For example, a directory can contain a gateway->probe->managed entity->sample setup. However, until the probe is connected and the sampler has started sampling, the directory will not contain the dataviews, cells and headlines until they are published.  State is propagated upward towards to the Gateway, thus when a cell becomes critical the Gateway will also become critical.

At the Gateway level the terms directory and Gateway are identical and they share the same attributes even though the XPath is of the form /geneos/gateway/directory ... This is to accommodate XPaths in the Geneos name space that refer to other things like client (Active console etc) or components that can connect to several Gateways and identify uniquely by name or attribute.

For Geneos the fastest XPaths you can write are ones that use the "name" attribute.  These can be resolved internally using something called a "FastName".  This is an optimization whereby a directory item can supply an object that knows the name of each item leading to it and direct access to those items to query attributes and parameters.  If you can identify an item by name this will be the quickest lookup.  You should always favor a [@name=value] predicate over [param("parameter") = value] predicate.  For example "/sampler[(@name="CPU")] will be quicker than /sampler[(param("PluginName")="CPU")].

The next quickest will involve attributes and parameters predicates, containing these will involve querying the object for the value.  These don't change at run-time so are fairly quick to look-up.  Similarly run-time parameters (rparam) need to be looked up, but their changeable nature may slow down the process as locking may slow down the process.

Splitting of XPaths

If you look at load monitoring stats you may see parts of your XPath being evaluated individually.  The naming code will try to use the efficient parts of the name as one XPath and evaluate the rest separately.  It will make this split where path variables are used or a non-identifying predicate (such as [@value="..."]).  A predicate such as this is the worst case scenario as the value of everything that can be matched up to that point will have to be retrieved.

Back to the top