Gateway Plug-Ins - Technical Reference

Introduction

Gateway plug-ins run on the gateway, instead of an external Netprobe processes. They typically provide a mechanism for exposing Gateway specific parameters to the monitoring capabilities of Geneos. The different Gateway Plug-ins that are available are described below:

Gateway RunTime Parameters

The Severity Count, Severity Data, Snooze Data and User Assignment Data plugins have the following Gateway runtime parameters available at the Sampler level:

  • GatewayName — The name of the Gateway.
  • GatewayHost — The hostname of Standalone or Primary Gateway (in case of HotStandby pair).
  • GatewayPort — The port of Standalone or Primary Gateway (in case of HotStandby pair).
  • SecurePort — Whether gateway is listening or secure port (true/false).
  • SecondaryHost — The hostname of Secondary Gateway (in case of HotStandby pair).
  • SecondaryPort — The port of Secondary Gateway (in case of HotStandby pair).

Gateway Data Plug-In

samplers > sampler > plugin > Gateway-gatewayData

The plug-in monitors the current configuration and state of this gateway. The plug-in provides the following variables:

List Variables:

Variable Name Description
gatewayName Configured unique name for the gateway.
gatewayId Unique identifier for the gateway.
release Release version of the gateway.
releaseAge The time in days since the gateway version was created.
hostname Hostname of the machine the gateway is running on.
ipAddress IpAddress of the machine the gateway is running on.
secureGatewayPort EMF2 port for the gateway that is used to listen for TSL connections.
insecureGatewayPort EMF2 port for the gateway that is used to listen for insecure TCP connections.
sslCertificateDaysRemaining

Number of days before the gateway's SSL certificate expires.

  • If negative, indicates number of days since it expired.
  • If zero, indicates that no certificate exists or that it is not yet valid.
hotStandbyRole Current hot standby role of the gateway (Unknown, Stand Alone, Primary, Secondary).
hotStandbyEnabled Is hotstandby configuration enabled (true, false)
hotStandbyFailbackStrategy

How does the Primary Gateway in a Hot-standby pair behave on restart with an Active Secondary?

  • Automatic - Gateway regains control
  • Manual - command needs to be run on the Secondary to release control.
  • Stand Alone - Not a Hot-standby Gateway.
secondaryGatewayHostname Hostname of the secondary gateway if hot standby is enabled and connected to a primary gateway.
secondaryGatewayPort Port of the secondary gateway if hot standby is enabled and connected to a primary gateway.
secondaryGatewayConnectionStatus Connection status to the secondary gateway if hot standby is enabled and connected to a primary gateway.
primaryGatewayHostname Hostname of the primary gateway if hot standby is enabled and connected to a secondary gateway.
primaryGatewayPort Port of the primary gateway if hot standby is enabled and connected to a secondary gateway.
gatewaySetupFile Name of the primary setup file for this gateway.
setupIncludeFiles Names of all included setup files for this gateway
insecurePasswordLevel The level at which insecure passwords are being reported in the setup (None, Warning, Error, Critical).
gatewayLogFile Name of the log file for this gateway.
gatewayProcessSize Size of the gateway process in Mb.
licenseFile Name of the temporary licence file.
licenseExpiryDate Expiry date of the licence file for this gateway
licenseDaysRemaining Number of days before the license expires.
severity The runtime severity of this gateway.
databaseLoggingEnabled Is database logging enabled (true, false)
databaseConnectionStatus Status of database connection if enabled (Pending, Connected, Not Connected).
databaseHost The configured host for the gateway's database connection. (This will be blank for Oracle and Sybase connections).
databasePort The configured port for database connection. (This will be blank for Oracle and Sybase connections).
databaseType Type of database (MySQL, SQLServer, Sybase, Oracle).
databaseSchemaVersion Version number of the database schema. This is read from the database at connection time.
gatewayDatabaseSchemaVersion Maximum version of the database schema that the gateway supports.
schemaVersion Version of the schema currently applied to this gateway.

Points to Note:

  • When the Gateway connects to a database, the 'databaseConnectionStatus' will be 'Connected'. If the user then pauses the database connection (using Database Logging -> Connection -> pause command), the connection will be dropped from the Gateway and the 'databaseConnectionStatus' will update to 'Not Connected'. If the user then resumes the connection, the 'databaseConnectionStatus' will not update until there is something to log to the database at which point the Gateway will re-establish connection to the database and the 'databaseConnectionStatus' would reflect this as 'Connected'.
  • If the Gateway is started in paused connection mode, then the 'databaseConnectionStatus' would sit at 'Pending' state until the user resumes the database connection.

Probe Data plugin

samplers > sampler > plugin > Gateway-probeData

The plug-in monitors the probes whose data is being monitored via this gateway. This may include normal probes (configured in the setup), virtual probes (configured in the setup), floating probes (configured in the setup), self-announcing probes (self-announced itself to the gateway) and imported probes (imported from an exporting gateway dataset).

This view also contains select data quality statistics applicable to probes. These statistics are generated internally to gateway and update approximately every 5 seconds. Therefore, depending upon the sampling rate configured you may not see a different value every sample.

The data quality statistics will "freeze" for a probe which has been suspended by the data quality algorithm, so that the last known values for the probe are available for viewing. These values are ignored for statistical calculations, so figures in - for example - the gatewayLoad column are expected to sum to greater than 100% in this circumstance.

The plug-in provides the following variables:

Headline Variables:

Variable Name Description
probeCount Number of probes configured on this gateway.
probesUp Number of probes that have a connectionState UP.
probesDown Number of probes that have a connectionState other than up.
maxDataAge The age of the oldest (pending) data update in milliseconds.
dataAgeLimit The configured maximum age. If maxDataAge reaches or exceeds this limit, the data quality algorithm may take steps to reduce gateway load to improve data quality.
totalDataSize The estimated size of the unprocessed (pending) data in the data-queues. In megabytes.
readThrottlingStatus

Status of the TCP read throttling algorithm that protects the data-queues from unbounded growth when the gateway is overloaded. Can be one of four values:

  • Not Throttling: Gateway is operating normally.
  • Throttling Importing Connections: Gateway is throttling reads on netprobes but will remain responsive to downstream components such as Active Console.
  • Throttling All Connections: Gateway is throttling all connections, and may become unresponsive.
  • Disabled: Read throttling algorithm is unable to operate (probably because older netprobes are connected) and no data-queue memory protection exists.

Row variables (Single row per probe):

Variable Name Description
name The unique name configured for this probe.
type

Type of probe. This can be one of four values:

  • Normal: A probe configured in the gateway setup file or imported from an exporting gateway dataset.
  • Virtual: A virtual netprobe configured in the gateway setup file.
  • Floating: A floating netprobe configured in the gateway setup file.
  • Self Announced: A probe that has announced itself to the gateway and is not configured in the gateway setup file.
security Whether the probe has connected to its gateway using a secure or insecure connection.
virtual Whether the probe is virtual of not (true/false)
imported Whether the probe is imported from another gateway.
importedFrom The name of the exporting gateway from which this probe is imported (i.e. if it is imported, blank otherwise)
hostname The hostname configured for this probe.
ipaddress The ipaddress resolved from the hostname for this probe.
port The port configured for this probe.
release The release version of this probe.
releaseAge The time in days since the probe version was created.
schemaVersion The version number of the schema published by this probe.
severity The runtime severity of this probe.
connectionState

The connectionState of this probe (Unknown, Up, Down, Unreachable, Rejected, Removed, Suspended).

Note: When the connection state of the probe is shown as 'Unreachable', this means that the probe is unreachable, not necessarily the server hosting it. For example, the probe might be unresponsive or its port might be in use.

OS The operating system type of the connected netprobe.
managedEntityCount The number of ManagedEntities configured on this probe.
support Features supported by this probe version.
gatewayLoad The load on the gateway caused by processing data from the probe, as a percentage against all other probes. This figure can help to identify "busy" Netprobes.
busiestView The view which is contributing most to the gatewayLoad figure for that probe.
busiestViewLoad The load of the busiestView, as a percentage against all other views on that probe.

Optional row variables:

Variable Name Description
user

This column will be available if the setting processAttributes has been set to "byName". This is the default value for the setting.

The cell will contain the user name of the account that is running the Netprobe.

The Netprobe must be at least version GA3.0.20-140610 to support this feature. If the Netprobe does not support this feature then the cell will be blank.

group

This column will be available if the plugin setting processAttributes is set to "byName". This is the default for the setting.

The cell will contain the name of all groups that the account that is running the Netprobe belongs to.

The Netprobe must be at least version GA3.0.20-140610 to support this feature. If the Netprobe does not support this feature then the cell will be blank

uid

This column will be available if the plugin setting processAttributes is set to "byID".

The cell will contain the user id of the account that is running the Netprobe.

The Netprobe must be at least version GA3.0.20-140610 to support this feature. If the Netprobe does not support this feature then the cell will be blank

Windows probes do not support IDs for users so this cell will be blank for windows probes.

gids

This column will be available if the plugin setting processAttributes is set to "byID".

The cell will contain the ids of all groups that the account that is running the Netprobe belongs to.

The Netprobe must be at least version GA3.0.20-140610 to support this feature. If the Netprobe does not support this feature then the cell will be blank

Windows probes do not support IDs for groups so this cell will be blank for windows probes.

TRUSTED_API_HOSTS

This column will be available if "TRUSTED_API_HOSTS" is selected under the plugin attributes setting. The cell will contain the value of the TRUSTED_API_HOSTS environment variable provided to the Netprobe at start-up.

The Netprobe must be at least version GA3.0.20-140610 to support this feature.

TRUSTED_DEBUG_HOSTS

This column will be available if "TRUSTED_DEBUG_HOSTS" is selected under the plugin attributes setting".

The cell will contain the value of the TRUSTED_DEBUG_HOSTS environment variable provided to the Netprobe at start-up.

The Netprobe must be at least version GA3.0.20-140610 to support this feature.

TRUSTED_HTTP_HOSTS

This column will be available if "TRUSTED_HTTP_HOSTS" is selected under the plugin attributes setting".

The cell will contain the value of the TRUSTED_HTTP_HOSTS environment variable provided to the Netprobe at start-up.

The Netprobe must be at least version GA3.0.20-140610 to support this feature.

TRUSTED_GATEWAY_HOSTS

This column will be available if "TRUSTED_GATEWAY_HOSTS" is selected under the plugin attributes setting".

The cell will contain the value of the TRUSTED_GATEWAY_HOSTS environment variable provided to the Netprobe at start-up.

The Netprobe must be at least version GA3.0.20-140610 to support this feature.

TRUSTED_GATEWAY_NAMES

This column will be available if "TRUSTED_GATEWAY_NAMES" is selected under the plugin attributes setting".

The cell will contain the value of the TRUSTED_GATEWAY_NAMES environment variable provided to the Netprobe at start-up.

The Netprobe must be at least version GA3.0.20-140610 to support this feature.

Note: The security value for an imported probe cannot be trusted to guarantee a secure connection to the importing Gateway. The importing connection should also be checked. The `severity` value reported in this dataview reflects the severity of each probe, thus if a probe is imported, the value will be affected by severity and snooze data imported from probes' source gateway as well as any severity and snooze data generated by this gateway on the probe.

samplers > sampler > plugin > Gateway-probeData > processAttributes

This setting defines how the process context of the Netprobe should be shown. The process context is the account run the Netprobe process. The plugin displays the user and group information for this account. If the value of this setting is "byName" then the user and group names of the account will be shown in columns user and groups. If the value of this setting is "byID" then the user id and group ids will be shown in columns uid and gids.

Note: Windows probes do not support ids for groups and users, so the uid and gids cells will be blank for windows probes.

These settings require a probe whose version is newer than GA3.0.20-140610. If the Netprobe is older the cells will be blank.

Mandatory: No
Default : byName

samplers > sampler > plugin > Gateway-probeData > attributes

This setting allows the administrator to add a set of environment variables used by the Netprobe to the sampler. Currently the following environment variables are supported:

  • TRUSTED_API_HOSTS
  • TRUSTED_DEBUG_HOSTS
  • TRUSTED_HTTP_HOSTS
  • TRUSTED_GATEWAY_HOSTS
  • TRUSTED_GATEWAY_NAMES

New columns will be added to the sampler with the names of the environment variables selected. These settings require a probe whose version is newer than GA3.0.20-140610. If the Netprobe is older the cells will be blank. If an environment variable is selected from the above list then the default value for the selected environment variable will be a "+" sign.

Mandatory: No
Default : No environment variables selected

Managed Entities Data plugin

samplers > sampler > plugin > Gateway-managedEntitiesData

The plug-in monitors the probes that are currently configured on this gateway. The plug-in provides the following variables:

Headline Variables:

Variable Name Description
managedEntityCount Number of ManagedEntities configured on this gateway.
undefinedCount Number of configured ManagedEntities that have a runtime severity of undefined.
okCount Number of configured ManagedEntities that have a runtime severity of ok.
warningCount Number of configured ManagedEntities that have a runtime severity of warning.
criticalCount Number of configured ManagedEntities that have a runtime severity of critical.

Row variables (Single row per managed entity):

Variable Name Description
name The unique name configured for this managed entity.
severity The runtime severity of this managed entity.
probeName The name of the probe this managed entity references.
probeStatus The connectionState of the probe this managed entity references.
samplerCount The number of samplers configured on this managed entity.
samplerNames

The name of the samplers configured on this entity.

Note: The `severity` value reported in this dataview reflects the severity of each manageEntity, thus if a manageEntity is imported, the value will be affected by severity and snooze data imported from manageEntity's source gateway as well as any severity and snooze data generated by this gateway on the manageEntity.

attributes The attribute name value pairs for this entity.
dataviewCount The number of dataviews in this managed entity.
maxCellCount The number of cells in the dataview in this managed entity that has the most cells.

Snooze Data plugin

samplers > sampler > plugin > Gateway-snoozeData

The plug-in monitors all data-items that are currently snoozed:

Headline Variables:

Variable Name Description
snoozedItemCount Number of snoozed data-items on this gateway.
snoozedButAbsentItems Number of data-items that are snoozed but not present on this gateway at this time.
filterIn Displays the inclusive attribute filters. See filter setting.
filterOut Displays the exclusive attribute filters. See filter setting.

Row variables (Single row per snoozed item):

Variable Name Description
cellId Unique identifier for this cell.
componentType The directory component type of this DataItem. One of gateway, probe, managedEntity, sampler, DataView, cell.
probe The probe for this DataItem.
managedEntity The managed entity for this DataItem.
sampler The sampler for this DataItem.
dataView The dataview for this DataItem.
cell The cell for this DataItem.
type The configured type for this DataItem.
plugin The configured plugin type for this DataItem.
snoozeType The type of snooze applied to the cell (Manual, SeverityTo, SeverityFrom, Time, DateTime, ValueChanges)
user Name of the user that issued the snooze.
userFullName Full name of the user that issued the snooze.
timestamp Time the snooze was issued.
duration

Number of minutes that the snooze has been active.

This view reports snooze information that was created by the current Gateway and does not reflect snooze data from imported Gateways. Thus if a user snoozes a cell using command delegation. The snooze information will appear in the Gateway-snoozeData view on the exporting gateway, but not on the importing gateway. However if snooze is not imported but the data items are, then the item snoozed will only be snoozed on the importing gateway and the snooze information will appear in the Gateway-snoozeData view on the importing gateway.

timeTillAutoUnsnooze Number of seconds before the snooze is auto cancelled (if appropriate).
comment User comment associated with this DataItem (if present).

samplers > sampler > plugin > Gateway-snoozeData > filter

This setting is used to filter the cells listed in the plugin. The cells are filtered by ManagedEntity. If the setting is not present then all snoozed cells on the gateway will be listed.

Mandatory: No
Default : No filtering

samplers > sampler > plugin > Gateway-snoozeData > filter > useAncestorManagedEntity

If this setting is present then the sampler will only display snoozed items that are descendants of the managed entity to which the sampler belongs.

samplers > sampler > plugin > Gateway-snoozeData > filter > filterByAttribute

A set of one or more filters which can be used to limit the number of managed entities that contribute data to the sampler's dataview. Each filter is applied in order and a managed entity needs to be accepted by all the filters in order to contribute data.

samplers > sampler > plugin > Gateway-snoozeData > filter > filterByAttribute > include

This setting defines a filter on an individual attribute. Any managed entities that have the specified attribute defined in the filter with a value that matches one of the values provided in the filter is accepted by this filter. Any other managed entity is rejected by this filter.

samplers > sampler > plugin > Gateway-snoozeData > filter > filterByAttribute > include > name

Name of the managed entity attribute tested by this filter.

samplers > sampler > plugin > Gateway-snoozeData > filter > filterByAttribute > include > values

Values of the managed entity attribute that is used by the filter to accept/reject managed entities from contributing data to the sampler's dataview. Managed entities whose specified attribute matches one of the listed values will be accepted by the filter. If the attribute is not specified on the managed entity or the specified attribute does not match one of the values provided it will be rejected by the filter.

samplers > sampler > plugin > Gateway-snoozeData > filter > filterByAttribute > exclude

This setting defines a filter on an individual attribute. Any managed entities that have the specified attribute defined in the filter with a value that matches one of the values provided in the filter is rejected by this filter. Any other managed entity is accepted by this filter.

samplers > sampler > plugin > Gateway-snoozeData > filter > filterByAttribute > exclude > name

Name of the managed entity attribute tested by this filter.

samplers > sampler > plugin > Gateway-snoozeData > filter > filterByAttribute > exclude > values

Values of the managed entity attribute that is used by the filter to accept/reject managed entities from contributing data to the sampler's dataview. Managed entities whose specified attribute matches one of the listed values will be rejected by the filter. If the attribute is not specified on the managed entity or the specified attribute does not match one of the values provided it will be accepted by the filter.

samplers > sampler > plugin > Gateway-snoozeData > filter > filterAttributes

A set of one or more filters which exclude managed entities if they contain attributes whose name and value match any of the filters defined here. If a managed entity is excluded all snoozed items that are descendants of the managed entity will also be excluded.

Deprecated: See filterByAttribute setting.

samplers > sampler > plugin > Gateway-snoozeData > excludeSelfGenerated

Whether to exclude rows that represent data generated by the plugin dataview itself.

For example, if excludeSelfGenerated is set and headline 'managedEntity' is snoozed, no rows will be generated.

Mandatory: No
Default : True
 

samplers > sampler > plugin > Gateway-snoozeData > attributeColumns

A list of attributes that will be added to the dataview as additional columns. If a row represents a managed entity, the additional columns will be populated with the attribute values for the attributes defined. If a row represents the descendant of a managed entity, the additional columns will be populated with the attribute values of the ancestor managed entity for the attributes defined. If a row represents a gateway or a probe then the cells will be blank.

Mandatory: No

User Assignment Data plugin

samplers > sampler > plugin > Gateway-userAssignmentData

The plug-in monitors all data-items that are currently user assigned:

Headline Variables:

Variable Name Description
assignedItemCount Number of data-items which have been assigned to users on this gateway.
assignedButAbsentItemsCount Number of data-items which have been assigned to users but are not present on this gateway at this time.
filterIn Displays the inclusive attribute filters. See filter setting.
filterOut

Displays the exclusive attribute filters. See filter setting.

Note: The `warningItems` and `criticalItems` values reported in this dataview reflects the severity of the Gateway, thus it is affected by severity and snooze data imported from other gateways as well as severity and snooze data generated on this gateway.

Row variables (Single row per user assigned cell):

Variable Name Description
cellId Unique identifier for this cell.
componentType The directory component type of this DataItem. One of gateway, probe, managedEntity, sampler, DataView, cell.
probe The probe for this DataItem.
managedEntity The managed entity for this DataItem.
sampler The sampler for this DataItem.
dataView The dataview for this DataItem.
cell The cell for this DataItem.
type The configured type for this DataItem.
plugin The configured plugin type for this DataItem.
assigner The user that issued the assignment.
assignerFullName Full name of the user that issued the assignment.
assignee The user to which the DataItem is assigned.
assigneeFullName Full name of the user to which the DataItem is assigned.
timestamp Time the assignment was issued.
duration

Number of minutes that the assignment has been active.

Note: This view reports user assignment that was created by **the current Gateway** and does not reflect user assignment data from imported Gateways. Thus if a user assigns a cell using command delegation. The user assignment information will appear in the Gateway-userAssignmentData view on the exporting gateway, but not on the importing gateway. However if user assignment information is not imported but the data items are, then the item assigned will only be assigned on the importing gateway and the assignment information will appear in the Gateway-userAssignmentData view on the importing gateway.

comment User comment associated with this DataItem (if present).

samplers > sampler > plugin > Gateway-userAssignmentData > filter

This setting is used to filter the cells listed in the plugin. The cells are filtered by ManagedEntity. If the setting is not present then all assigned cells on the gateway will be listed.

Mandatory: No
Default : No filtering

samplers > sampler > plugin > Gateway-userAssignmentData > filter > useAncestorManagedEntity

If this setting is present then the sampler will only display assigned items that are descendants of the managed entity to which the sampler belongs.

samplers > sampler > plugin > Gateway-userAssignmentData > filter > filterByAttribute

A set of one or more filters which can be used to limit the number of managed entities that contribute data to the sampler's dataview. Each filter is applied in order and a managed entity needs to be accepted by all the filters in order to contribute data.

samplers > sampler > plugin > Gateway-userAssignmentData > filter > filterByAttribute > include

This setting defines a filter on an individual attribute. Any managed entities that have the specified attribute defined in the filter with a value that matches one of the values provided in the filter is accepted by this filter. Any other managed entity is rejected by this filter.

samplers > sampler > plugin > Gateway-userAssignmentData > filter > filterByAttribute > include > name

Name of the managed entity attribute tested by this filter.

samplers > sampler > plugin > Gateway-userAssignmentData > filter > filterByAttribute > include > values

Values of the managed entity attribute that is used by the filter to accept/reject managed entities from contributing data to the sampler's dataview. Managed entities whose specified attribute matches one of the listed values will be accepted by the filter. If the attribute is not specified on the managed entity or the specified attribute does not match one of the values provided it will be rejected by the filter.

samplers > sampler > plugin > Gateway-userAssignmentData > filter > filterByAttribute > exclude

This setting defines a filter on an individual attribute. Any managed entities that have the specified attribute defined in the filter with a value that matches one of the values provided in the filter is rejected by this filter. Any other managed entity is accepted by this filter.

samplers > sampler > plugin > Gateway-userAssignmentData > filter > filterByAttribute > exclude > name

Name of the managed entity attribute tested by this filter.

samplers > sampler > plugin > Gateway-userAssignmentData > filter > filterByAttribute > exclude > values

Values of the managed entity attribute that is used by the filter to accept/reject managed entities from contributing data to the sampler's dataview. Managed entities whose specified attribute matches one of the listed values will be rejected by the filter. If the attribute is not specified on the managed entity or the specified attribute does not match one of the values provided it will be accepted by the filter.

samplers > sampler > plugin > Gateway-userAssignmentData > filter > filterAttributes

A set of one or more filters which exclude managed entities if they contain attributes whose name and value match any of the filters defined here. If a managed entity is excluded all assigned items that are descendants of the managed entity will also be excluded.

Deprecated: See filterByAttribute setting.

samplers > sampler > plugin > Gateway-userAssignmentData > excludeSelfGenerated

Whether to exclude rows that represent data generated by the plugin dataview itself.

For examples of this flag, see the entries in the Gateway-snoozeData or Gateway-severityData plugins.

Mandatory: No
Default : True

samplers > sampler > plugin > Gateway-userAssignmentData > attributeColumns

A list of attributes that will be added to the dataview as additional columns. If a row represents a managed entity, the additional columns will be populated with the attribute values for the attributes defined. If a row represents the descendant of a managed entity, the additional columns will be populated with the attribute values of the ancestor managed entity for the attributes defined. It a row represents a gateway or a probe then the cells will be blank.

Mandatory: No

Menu Items

Unassigned Absent Items

This command is available on the assignedButAbsentItemsCount headline if the Gateway-userAssignmentData plugin in enabled and on the gateway regardless.

This command requires confirmation from the user as on a busy gateway or gateway with many missing items it may be processor intensive. This may lead to the gateway becoming temporarily unresponsive.

There is also the risk of removing items that may return when connecting to probe or reconfiguring a sampler.

Client Connection Data plugin

samplers > sampler > plugin > Gateway-clientConnectionData

The plug-in monitors currently connected client applications. This includes;

  • Active Console
  • Open Access Server
  • Webslinger
  • Gateway that import data from this gateway

Headline Variables:

Variable Name Description
clientConnectionCount Number of clients connected.

Row variables (Single row per client connection):

Variable Name Description
connectionId Connection identifier for this client.
component Component name of this client.
release The release version of this client.
releaseAge The time in days since the client version was created.
hostname The hostname that the client is connecting from.
ipaddress The ipaddress that the client is connecting from.
security Whether the client has connected to this gateway using a secure or insecure connection.
duration The number of minutes since the client connected.
expiresIn The time in minutes until the client SSO credentials will expire. This will be blank if this is not an SSO connection. In normal running the client will refresh the credentials before they expire.
userName The user associated with this connection.
userFullName The full name of the user associated with this connection.
userDomain The domain of the user associated with this connection.
ssoUser Whether this is an SSO user (true, false).
genericUser Whether this is a generic user (true, false).
userGroups List of groups that this user belongs to.
connectionType

This is one of

  • Full Sync
  • BDO Sync
  • Gateway Sharing
numFullySyncedDataviews The number of dataviews for which every cell is sent to the client every time it changes value.

The connectionType indicates how the system is transferring data to the client. Webslinger and very old active consoles use "Full Sync" where every data view is kept in sync between the client and the gateway.

Open Access Server and newer Active consoles use "BDO Sync" where the only dataviews being viewed/used are kept in sync between the client and the gateway. Other dataviews are kept in partial sync until such time as they are viewed/used by the client. At that time they are brought into full sync. Once a dataview is no longer used, then the dataview is only kept in partial sync again.

Importing gateways use Gateway Sharing where they only import the dataviews they have expressed interest in. All imported dataviews are kept fully in sync.

Exported Data

samplers > sampler > plugin > Gateway-exportedData

Row variables (Single row per connection to an importing gateway):

Variable Name Description
connectionId Connection identifier for importing gateway.
gatewayName The name of importing gateway.
requestedDataSets The list of data sets that the importing gateway has requested.
providedDataSets The list of data sets that have actually been provided to the importing gateway.
connectedUser The user name if available that was used to authenticate the connection.

The connectionId column is the same as the connectionId column in the client connection plugin. This allows rules to be used that take data from both these plugins and merged dataviews to be created using the gateway-sql plugin.

Note: Under normal circumstances, the requestedDataSets and the providedDataSets should be the same. These will only differ if the importing gateway is requesting a data set that does not exist on the exporting gateway.

Imported Data

samplers > sampler > plugin > Gateway-importedData

Row variables (Single row per configured imported data connection):

Variable Name Description
name The name of this connection.
connectionStatus

The status of the connection. This can be one of;

  • Up
  • Down
  • Suspended
  • Rejected
providedDataSets The list of data sets that have actually been provided to the importing gateway.
requestedDataSets The list of data sets that the importing gateway has requested.
gatewayName The name of the exporting gateway
primaryHost The host of the gateway that data is being imported from. (This is the primary host if the gateways are in a hot standby pair).
primaryPort The port of the gateway that data is being imported from is listening on. (This is the primary host if the gateways are in a hot standby pair).
secondaryHost The host of the secondary gateway that data is being imported from.
secondaryPort The port of the secondary gateway that data is being imported from is listening on. (This is the primary host if the gateways are in a hot standby pair).
security Whether the gateway has connected to the exporting gateway using a secure or insecure connection.
conflictingProbes

A comma separated list of probes that have been dropped from the imported data sets because they conflict with existing probes in the importing gateway.

See Conflict Resolution

Severity Count plugin

samplers > sampler > plugin > Gateway-severityCount

The plug-in monitors the number of cells with OK, WARNING or CRITICAL severities.

Headline Variables:

Variable Name Description
viewpath Displays what viewpath elements need to be matched for a managed entity to be considered when generating the dataview
filterIn Displays the inclusive attribute filters. See filter setting.
filterOut Displays the exclusive attribute filters. See filter setting.

Note

This is an optional headline which only gets displayed if one or more filter attributes have been defined."

Row variables:

Variable Name Description
name Row identifier
okItems Number of ok items.
warningItems Number of warning items
criticalItems

Number of critical items.

Note: The `okItems`, `warningItems` and `criticalItems` variables can be affected by any snooze or severity data that has been imported, as well as any snooze or severity data locally generated.

samplers > sampler > plugin > Gateway-severityCount > viewPaths

A list of view paths.

Mandatory: No
Default : no path defined

samplers > sampler > plugin > Gateway-severityCount > viewPaths > viewPath

The view path configures the view in which the entities will be ordered in terms of attribute names.

Mandatory: No
Default : no path defined

samplers > sampler > plugin > Gateway-severityCount > includeUserAssigned

Whether to include user assigned cells in the count. Any item that has an assigned user counts for this filter, no matter whether it was assigned on this gateway or the assignment was imported from another gateway.

Mandatory: No
Default : true

samplers > sampler > plugin > Gateway-severityCount > includeSnoozed

Whether to include snoozed cells in the count. Any item that has been snoozed counts for this filter, no matter whether it was assigned on this gateway or the assignment was imported from another gateway.

Mandatory: No
Default : false

samplers > sampler > plugin > Gateway-severityCount > includeInactive

Whether to include inactive cells in the count.

Mandatory: No
Default : false

samplers > sampler > plugin > Gateway-severityCount > appendManagedEntity

Whether to drill down to managed entity level.

Mandatory: No
Default : false

samplers > sampler > plugin > Gateway-severityCount > filterByAttribute

A set of one or more filters which can be used to limit the number of managed entities that contribute data to the sampler's dataview. Each filter is applied in order and a managed entity needs to be accepted by all the filters in order to contribute data.

Mandatory: No
Default : no filters

samplers > sampler > plugin > Gateway-severityCount > filterByAttribute > include

This setting defines a filter on an individual attribute. Any managed entities that have the specified attribute defined in the filter with a value that matches one of the values provided in the filter is accepted by this filter. Any other managed entity is rejected by this filter.

samplers > sampler > plugin > Gateway-severityCount > filterByAttribute > include > name

Name of the managed entity attribute tested by this filter.

samplers > sampler > plugin > Gateway-severityCount > filterByAttribute > include > values

Values of the managed entity attribute that is used by the filter to accept/reject managed entities from contributing data to the sampler's dataview. Managed entities whose specified attribute matches one of the listed values will be accepted by the filter. If the attribute is not specified on the managed entity or the specified attribute does not match one of the values provided it will be rejected by the filter.

samplers > sampler > plugin > Gateway-severityCount > filterByAttribute > exclude

This setting defines a filter on an individual attribute. Any managed entities that have the specified attribute defined in the filter with a value that matches one of the values provided in the filter is rejected by this filter. Any other managed entity is accepted by this filter.

samplers > sampler > plugin > Gateway-severityCount > filterByAttribute > exclude > name

Name of the managed entity attribute tested by this filter.

samplers > sampler > plugin > Gateway-severityCount > filterByAttribute > exclude > values

Values of the managed entity attribute that is used by the filter to accept/reject managed entities from contributing data to the sampler's dataview. Managed entities whose specified attribute matches one of the listed values will be rejected by the filter. If the attribute is not specified on the managed entity or the specified attribute does not match one of the values provided it will be accepted by the filter.

samplers > sampler > plugin > Gateway-severityCount > filterAttributes

A set of one or more filters which exclude managed entities from being considered if they contain attributes whose name and value match any of the filters defined here.

Mandatory: No
Default : no filters
Deprecated: See filterByAttribute setting.

Includes Data plugin

samplers > sampler > plugin > Gateway-includesData

The plug-in monitors the include files that are currently configured on this gateway. The plug-in provides the following variables:

Row variables (Single row per file):

Variable Name Description
priority The configured priority of the include file.
file The location of the include file (or main setup file) as specified on the gateway.
applied The time when this file was read from disk and applied by the gateway. If the file could not be applied this is noted here along with applicable error message.
changed The time when this file last changed on disk. If the file cannot be reached to check the changed time, a "path inaccessible" message is displayed.
activeMd5Sum This is the MD5 sum of the include file that is currently active. This will be different from the MD5 sum of the include file on disk in the following cases:

  • The file on disk has been changed outside of geneos and gateway has not reloaded the setup.
  • The file on disk has been changed outside of geneos and gateway refused to load the setup.
  • The file on disk was changed (externally/or via GSE) and is currently marked as inactive (See includes > reloading > activeTime).

activeVersion This is version number of the active include file as returned by the post-validate hook. (See Post Setup Apply).
lastEditedBy The name of the user who last edited the file.
LastEditedGateway The name of the Gateway the user was authenticated with when the file was last edited. Not recorded if using an unauthenticated Gateway.
LastEditedOnWorkstation The name of the machine the user was logged into when the file was last edited.

Load Monitoring plugin

samplers > sampler > plugin > Gateway-gatewayLoad

The Gateway Load Monitoring feature provides various statistics about the runtime state of a Gateway. These statistics include processing times spent in various features, and can be viewed using configured instances of the load monitoring plug-in.

The load monitoring plugin has several different display modes, which allow users to obtain either a broad high-level overview of the current gateway state, or to drill down to examine statistics for a particular item.

The expected use for this plugin is primarily for troubleshooting, or to pinpoint specific components that are causing or contributing to a problem. For a more detailed description on this, please see the "Gateway 2 Performance Tuning Guide" document.

Categories

Load monitoring statistics are broken down into several categories of statistic. Each of these categories is displayed by the load monitoring plug-in as a separate view mode, controlled by the category setting.

Component Statistics

The component statistics is the default display mode for the load monitoring plug-in. These statistics summarise how much time is being spent processing each gateway feature.

Headline Variables:

Variable Name Description
category The load monitoring statistics category being displayed.
grouping The currently configured grouping mode, if any.
statistics The statistics being displayed. This will be "time" by for the componentStats category.
filter The currently configured filter, if any.
lastUpdatedTime Time the underlying data being displayed was last updated.

Row Variables:

Variable Name Description
components Row identifier
time Total amount of CPU time spent on each component. Time units vary per platform, and should be used for relative comparisons only.

The features reported on are as follows:

  • Actions
  • Active Times
  • Alerting
  • Auditing
  • Commands
  • Database Logging
  • Directory
  • Includes constructing and modifying the state tree among other tasks.
  • Effects
  • Express Reports
  • Knowledge Base
  • Licencing
  • Probe Management
  • Includes establishing and maintaining communication with Netprobes.
  • Roles
  • Includes the time spent on Hot-Standby functionality.
  • Rules
  • Schema
  • Self-Announcing Netprobes
  • Setup Management
  • Snooze
  • Ticker Events
  • Time Series
  • User Assignment
  • User Management
  • Other user functionality not related to assignment.

Note: A high amount of time spent in some components relative to others is expected in a normal gateway configuration, as not all gateway features are used to the same degree.

Directory Statistics

Several gateway features operate on Data-items selected by a user-configured XPath. The directory statistics category provides information about the items a feature is operating on, with corresponding location information from the directory, such as the Netprobe or Managed Entity that an item is associated with. It is therefore possible to identify a particular probe or plug-in whose data is causing excessive load on the gateway.

Headline Variables:

Variable Name Description
category The load monitoring statistics category being displayed.
grouping The currently configured grouping mode, if any.
statistics The statistics being displayed. One of "time", "rules" or "dbLogging" depending on selected option.
filter The currently configured filter, if any.
lastUpdatedTime Time the underlying data being displayed was last updated.

Row Variables:

Variable Name Description
group Name of the group, the precise type being specified by the grouping mode.
dbLogging Total amount of CPU time spent for that grouped item (and all contained items in the group) on database logging.
rules Total amount of CPU time spent for that grouped item (and all contained items in the group) on rules.
matchingItems Displayed for some statistics modes. This column shows the count of matchingItems (i.e. number of contained items in the group) for the selected feature, for that group.
time Displayed for some statistics modes. Shows the CPU time spent for the selected feature, for that group.
updates Displayed for dbLogging statistics. The number of times a database logging target value changed, causing a check to see if the new value should be logged.
evaluations Displayed for rule statistics. The number of times a property change on a matched data-item caused a rule evaluation.

At present two features are instrumented at this level: Rules and Database Logging. Statistics for these can be shown as a total time side-by-side, or in a view containing specific details for either of the features.

The directory statistics mode also allows users to group and filter items to help drill down to problem areas. Grouping allows statistics to be displayed (for example) at a Sampler or Managed Entity level. Values are aggregated at the grouping level, so an entity grouping would sum all values within a given entity.

Filtering items allows the views to be restricted to a particular entity or rule for example, and removes other counts from the aggregate statistics of the grouping.

Connection Statistics

The connection statistics category displays low-level details about the network traffic to and from the gateway. Connection data will include Netprobes, connected clients such as Active Console 2 or Web Dashboards, as well as other components such as a hot-standby Gateway, Licence Daemon or web-based http connections.

Headline Variables:

Variable Name Description
category The load monitoring statistics category being displayed.
grouping The currently configured grouping mode, if any.
statistics The statistics being displayed.
filter The currently configured filter, if any.
lastUpdatedTime Time the underlying data being displayed was last updated.

Row Variables:

Variable Name Description
connection The host and port of the remote side of the connection.
WriteStreamLength Data in KB to be sent from the gateway.
ReadStreamLength Data in KB that have not yet been processed.
MessagesQueued For a Netprobe or ActiveConsole 2 connection, the number of messages waiting to be processed.
SendRate Rate of data sent in the last 10 seconds (KB/s)
ReceiveRate Rate of data received in the last 10 seconds (KB/s)
MemoryInUse Total amount of memory used for send and receive buffers.
XPath Statistics

This category displays information about XPath evaluations within the gateway. These paths are used both for user-configured items such as rule targets, as well as internally for tasks such as executing commands. Due to the complexity of paths, it is recommended to use this category for debugging under the instruction of ITRS support staff.

Headline Variables:

Variable Name Description
category The load monitoring statistics category being displayed.
grouping The currently configured grouping mode, if any.
statistics The statistics being displayed.
filter The currently configured filter, if any.
lastUpdatedTime Time the underlying data being displayed was last updated.

Row Variables:

Variable Name Description
path The full XPath text.
invocations Number of times this path was evaluated.
time Total time spent evaluating the path.
ORB Statistics

The ORB (Object Request Broker) is a central part of each geneos binary, and is used to transfer information from the Netprobe to the Gateway and then on to the Active Console and other components in an efficient way. Almost all work passes through the ORB (an example of an exception to this is the small heartbeats used to ensure other components are up) so this statistics category is a good indicator the total work that the gateway is performing. The Component Statistics can then be used to see a higher level view of the parts of the Gateway that are processing this data.

In addition, this view displays statistics relating to conflation which can be used to determine its effectiveness and impact on the gateway.

Headline Variables:

Variable Name Description
category The load monitoring statistics category being displayed.
grouping The currently configured grouping mode, if any.
statistics The statistics being displayed.
filter The currently configured filter, if any.
lastUpdatedTime Time the underlying data being displayed was last updated.

Row Variables:

Variable Name Description
conflatedMessagesCreated The number of outgoing messages created by conflation. A message can contain multiple updates.
messagesConflated The number of incoming messages condensed into conflated messages. A message can contain multiple updates.
methodsConflated The number of individual updates discarded by conflation.
conflationTime The total time spent waiting for conflation to run. This value is included in the time statistic.
time Total time spent processing data.
Gateway-sql Statistics

The Gateway-sql plugin is a plugin that runs on the gateway and allows users to produce new dataviews by combining data from existing dataviews on the gateway. The statistics in this category show how much work various instances of the plugin are doing.

Headline Variables:

Variable Name Description
category The load monitoring statistics category being displayed.
grouping The currently configured grouping mode, if any.
statistics The statistics being displayed.
filter The currently configured filter, if any.
lastUpdatedTime Time the underlying data being displayed was last updated.

Row Variables:

Variable Name Description
totalTime

The total time spent in the plugin, this includes the time taken to:

  • Create the database and initialise it,
  • populate the source tables,
  • extract the data from the database into the sampler's dataviews, and
  • publish the data.
searchTime The time taken to seach the gateway for the items prior to insertion in the database.
insertTime The time taken to insert data into the source tables.
queryTime The time taken to run SQL queries against the source tables
extractionTime The time taken to populate the sampler's dataviews from the query result sets
publishTime The time taken to publish the extracted data into the gateway

Commands

The underlying statistics for the gateway load monitoring plug-in can be controlled by a set of gateway commands. Using these commands, users can dynamically:

  • Start statistics collection
  • Stop statistics collection
  • Reset all cumulative statistics
  • Write statistics to file

These commands appear in Active Console 2 when right-clicking on a gateway:

Selecting the "for time period" command produces the following dialog, allowing users to gather statistics over a specified period of time.

Starting and stopping statistics collection will start and stop the collection in memory, but will also start and stop the periodic logging of statistics to a file, if this has been configured. In addition, starting statistics collection is only possible if a timed collection is not in progress. To cancel a timed collection, simply issue the "stop collection" command first.

The "Reset Stats" command will clear any cumulative statistics from memory, i.e. zero any times and number of executions etc. Stats such as the number of matching items will not be reset to zero as they will be valid regardless of the time period monitoring occurs for (assuming no new samplers are (un)configured, or probes started/stopped).

The "Write Stats to File" command will write the statistics values from memory to disk. This performs the same operation as the regular stats file writing that can be configured, as well as the the "Write Stats to file after collection" option when gathering statistics over a period of time.

Configuration

samplers > sampler > plugin > Gateway-gatewayLoad > view > category

Specifies the category of statistics to display:

Mandatory: Yes
samplers > sampler > plugin > Gateway-gatewayLoad > view > source > file

The file data source specifies that the plug-in should display load data as read from a file. This file should have previously been logged by a gateway using the "Write stats to file" operating environment settings.

Mandatory: No
Default: If not specified, the plug-in reads data from gatewayInternals source.
samplers > sampler > plugin > Gateway-gatewayLoad > view > source > gatewayInternals

This data source specifies the plug-in should display data currently being gathered by the gateway, and read from gateway memory.

Mandatory: No.
Default: If not specified, the plug-in reads data from gatewayInternals source.
samplers > sampler > plugin > Gateway-gatewayLoad > view > category > componentStats > grouping

The grouping level at which to view the statistics. Each row in the resulting view will be a group at the grouping level. For example, grouping by ThreadID means that each row in the output view relates to a particular thread.

Mandatory: No
Default: Grouping by component
samplers > sampler > plugin > Gateway-gatewayLoad > view > category > componentStats > statistics > expandType

Displaying statistics by expanded type will show only the stats values for that type. For example, selecting "Rules" will show all rule statistical values with a separate column for each value. Values for other types will not be displayed.

Mandatory: No
Default: No expansion, time statistics will be shown.
samplers > sampler > plugin > Gateway-gatewayLoad > view > category > directoryStats > filtering > filter

This setting applies an inclusive filter to the statistics before display. Only items matching the filter will be shown in the resulting view.

Filtering can be performed on:

  • Managed Entity
  • Plug-in
  • Probe
  • Rule
  • Sampler
  • Type
  • Database Item
Mandatory: No
Default: No filtering
samplers > sampler > plugin > Gateway-gatewayLoad > view > category > directoryStats > grouping

The grouping level at which to view the statistics. Each row in the resulting view will be a group at the grouping level. For example, grouping by Managed Entity will means that each row in the output view relates to an entity.

Up to two levels of grouping can be applied, to display a top-level grouping with sub-groups of the second configured level.

Mandatory: No
Default: Managed Entity
samplers > sampler > plugin > Gateway-gatewayLoad > view > category > directoryStats > statistics > perType

This setting controls which statistics to display. Statistics from a feature matching the selected type will be shown, with the column as the name of the type.

For example, displaying perType with "matchingItems" will show columns where the values are counts of matching items. The names of these columns will be the feature names, i.e. rules and dbLogging.

Mandatory: No
Default: Time
samplers > sampler > plugin > Gateway-gatewayLoad > view > category > directoryStats > statistics > expandType

Displaying statistics by expanded type will show only the stats values for that type. For example, selecting "Rules" will show all rule statistical values with a separate column for each value. Values for other types will not be displayed.

Mandatory: No
Default: If not specified, the plug-in will display a "perType Time" statistic.
samplers > sampler > plugin > Gateway-gatewayLoad > view > category > xpathStats > filter > method

Filters the XPath statistics output to view, by the internal gateway method-call used to evaluate the path.

Value Meaning
getItems Called by the gateway to resolve a path to a set of items.
getRelativeItems Called to resolve a relative path against a specific item, to a set of items.
nameAppliesToDataItem Called to reverse-resolve an item against a path (e.g. during rule lookups on initial item creation).
Mandatory: No
Default: All methods are summarised into a single figure

Licence Usage plugin

samplers > sampler > plugin > Gateway-licenceUsage

The Licence Usage plugin monitors the licence daemon currently connected to the gateway. It shows how the licence is in use and how much of the licence is still available as well as the connection status and licence expiry time.

By default, a view will be shown for all licensing groups configured on the gateway

See the Licence Daemon Technical Reference Guide for more information about how to use the plugin to monitor licence usage.

samplers > sampler > plugin > Gateway-licenceUsage > groups

Specifies which licensing groups configured on the daemon the plug-in should display views for. By default, a view will be shown for all licensing groups configured on the gateway.

Mandatory: No

samplers > sampler > plugin > Gateway-licenceUsage > groups > group

The name of a licensing group configured on the daemon that the plug-in should display a view for.

Mandatory: No

samplers > sampler > plugin > Gateway-licenceUsage > showOverall

Display a view showing the overall ITRS issued licence and how it is being used.

Mandatory: No
Default: false

samplers > sampler > plugin > Gateway-licenceUsage > showOther

Display a view showing how any tokens not allocated to a licensing group are being used.

Mandatory: No
Default: false

Scheduled Command Data plugin

samplers > sampler > plugin > Gateway-scheduledCommandData

The plug-in monitors currently configured Scheduled Commands and present information about their configuration, current, past and future scheduled runs. The plugin has no configuration settings.

Dataview

Below is a snapshot of how the plugin dataview might look:

Headline Variables:

Variable Name Description
configuredCommandsCount Number of Scheduled Commands that are currently configured.
runningCommandsCount Number of Scheduled Commands that are currently running.
scheduledCommandsCount Number of Scheduled Commands which are scheduled for future run.

Row variables (Single row per scheduled command):

Variable Name Description
command The name of Scheduled Command.
recurrenceInterval How often the Scheduled Command is run? This data will make sense in conjunction with 'recurrencePeriod'
recurrencePeriod The recurrence period for the Scheduled Command. It will have values - minutes, hours, days, weeks, weekdays, months.
activeTime The Active Time (if any) associated with the Scheduled Command.
running Whether the Scheduled Command is currently running. Possible values: 'YES', 'NO'
runningTimestamp Start time of currently running instance (if any), <blank> otherwise.
runningTargetCount The number of targets against which the Scheduled Command is running (if it is currently running), <blank> otherwise
scheduled Whether the Scheduled Command is scheduled to run in future. Possible values: 'YES', 'NO'
scheduledState Whether the next scheduled run will be inside or outside the Active Time. Possible values: 'Active', 'Not Active'
scheduledTimestamp Start time of next run (if scheduled), <blank> otherwise.
scheduledTargetCount The number of targets against which the Scheduled Command is scheduled to run next. This count will be if the command was run at the time the data view is sampled.
lastRunTimestamp Start time of last run instance of Scheduled Command (if any).
lastRunTargetCount The number of targets against which the Scheduled Command ran last time.
lastRunFailedTargetCount The number of targets against which the Scheduled Command failed to run last time.

Points to Note:

  • Column scheduledState'Not Active' value denotes that the scheduled run will not occur as it will be outside the active time (as the Active Time state at that scheduled time will be Not Active or Override). Similarly, 'Active' value denotes that the scheduled run will occur as it will be inside active time. Scheduled Commands with no configured 'Active Time' but a scheduled run will always display 'Active' for this column.
  • 'weekDays' recurrencePeriod will denote that user has configured everyWeekday days recurrence pattern in the setup.
  • If the Scheduled Command is not scheduled, it will mean the Scheduled Command had 'endByDate' or 'endAfterXOccurances' configured and either the time is past 'endByDate' or the command has already run X times in the past.
  • If the Scheduled Command is not running, it will simply mean the Scheduled Command is not running at that point of time. One cannot infer if it is scheduled to run in future. For that, one will refer to 'scheduled' column.
  • The timestamps will be displayed in Gateway time zone irrespective of the time zones configured in the individual Scheduled Commands. All the timestamps would be displayed in the format YYYY-MM-DD HH:MM:SS for easy sorting of columns.

Scheduled Commands History Data plugin

samplers > sampler > plugin > Gateway-scheduledCommandsHistoryData

The plug-in monitors the past runs of currently configured Scheduled Commands.

Below is a snapshot of how the plugin dataview might look:

Configuration

samplers > sampler > plugin > Gateway-scheduledCommandsHistoryData > scheduledCommand

The Scheduled Command for which past runs need to be monitored. By default, all configured Scheduled Commands past runs are displayed.

Mandatory: No
samplers > sampler > plugin > Gateway-scheduledCommandsHistoryData > run > last

The number of most recent past runs which need to be displayed. This number if always limited by the history count configured in the Scheduled Command Advanced tab. Refer to this section.

Mandatory: No

Dataview

Headline Variables:

Variable Name Description
lastRunsPerScheduledCommandsCount Number of most recent past runs displayed per Scheduled Command.

Row variables (Single row per scheduled command past run):

Variable Name Description
lastRunInstance The last run instance of the Scheduled Command. Format: YYYY-MM-DD HH:MM:SS_<commandName>
command The Scheduled Command name (for easy sorting)
status The status of the past run instance. Possible values: 'SUCCESS', 'FAIL'.
totalTargets The number of targets against which the Scheduled Command instance ran.
failedTargets The number of targets against which the Scheduled Command instance failed to run.

Points to Note:

  • 'FAIL' status of the last run instance means the command failed to run on 1 or more expected targets. 'SUCCESS' status implies the command ran fine on all targets.
  • The timestamps would be displayed in Gateway time zone irrespective of the time zones configured on the individual Scheduled Command. All the timestamps would be displayed in the format YYYY-MM-DD HH:MM:SS for easy sorting of columns.

Gateway SQL plugin

samplers > sampler > plugin > Gateway-sql

Introduction

This plug-in is part of the Compute Engine functionality of the gateway; unlike the other Gateway plug-ins, it provides a way to summarise and reformat dataviews rather than to monitor the gateway. It uses an in-memory SQLite database to take data from multiple dataviews and combine them to provide a set of new dataviews. Note that the database is used within the plug-in to manipulate the dataviews, not to store any historical data. The version of SQLite used in this plug-in is sqlite-3.9.2 (See http://www.sqlite.org/releaselog/3_9_2.html).

A user can configure the plugin to take data from a pair of specified dataviews and combine them using a key column in each dataview.

So if the first dataview was;

And the second dataview was;

We can combine the two dataview using the following SQL statement (where T1 is the first dataview table and T2 is the second dataview table) to get a human readable state value. Below is how it would be configured in the Gateway Setup Editor.

The resulting dataview is

More complex SQL is available including OUTER JOINS, LEFT JOINS, GROUP BY. For a more in-depth list of queries that can be used, please look at http://www.sqlite.org/lang.html.

The sampler has a sample time. Every time that it samples, all the tables associated with the sources are wiped clean and the data is rescanned into the databases. The SQL is then run to extract the specified views and the Geneos data model is updated.

Note: The severity, snooze state and user assignment data reported in this dataview reflects the severity snooze state and user assignment of the data items, thus it is affected by severity, snooze state and snooze data imported from other gateways as well as severity snooze state and snooze data generated on this gateway.

Table Sources

There are 3 different gateway sources that can be used to populate tables in the sampler database;

  • A Dataview table (data from a single dataview)
  • A Dataview's headlines (data from a single dataview)
  • A set of XPaths (data from multiple dataviews)

Dataview sources

A single dataview can be used a source for a database table. If the columns are not specified in the setup, then the dataview columns will be the same as the columns in the source dataview. (This will include the rowname column). If the columns are specified in the setup, then just those columns present in the dataview that are specified in the setup will be copied into the sampler's database. It is recomented that columns are specified where possible as this allows the table to be created before the dataview is populated. If the columns are not created and the source dataview is missing, the plugin will be unable to create a table and subsequent SQL queries will fail.

If the XPath provided matches multiple dataviews, then only the first dataview found will be used. The other dataviews will be ignored.

Below is the setup to obtain the dataview row data from a CPU dataview:

Setting Table Columns

This section of the setup allows users to define the schema of the SQLite table created for each dataview. If this section is omitted, the table will have a column for each column in the dataview. If this section is present, any column whose name does not match a column in the dataview will be populated with NULL values and any columns present in the dataview but not specified will be omitted from the SQLite database table.

This section also allows the datatype of each column to be specified as TEXT, INTEGER or REAL. The default value if unspecified is TEXT. See http://www.sqlite.org/datatype3.html for more details about how types affect tables in SQLite.

Choosing whether or not to specify the columns for a dataview source involves a trade-off between efficiency and adaptability.

Explicitly specifying the columns has the advantages that:

  1. Columns that are not used in the queries need not be copied, saving memory and CPU resources in the Gateway.
  2. Queries will not fail if dataviews are missing as the tables will still exist in the database (though they will be empty).

On the other hand, with a fixed set of columns:

  1. The resultant query cannot adapt to new columns being added to the source dataview.
  2. The resultant dataview will not show an error if the source dataview is absent.

Below is the setup to obtain the dataview row data from a subset of the columns in a CPU dataview:

Below is an example of extracting the data using the previous settings:

Headline sources

The headlines from a single dataview can used a source for a database table. The table has a predefined structure: two columns of type TEXT, called "name" and "value". There is a single row for each headline in the dataview. ('samplingStatus' is one of the dataview headlines and so will be one of the row names returned.)

If the XPath provided matches multiple dataviews, then only the first dataview found will be used. The other dataviews will be ignored.

Below is the setup to obtain the headlines from a CPU dataview:

Below is an example of extracting using the previous settings:

XPath sources

A set of XPaths can be used to define the source for a database table. These XPaths are separated into two groups: row XPaths and column XPaths.

The row XPaths define target items for the rows in the table. On each sample, the Gateway directory is searched for items that match the row XPaths and each item found is used to create a row in the database table. If an item matches more than one row XPath, it will only generate one row in the database table.

Each column in the database table is defined by a column XPath. This XPath selects a value for the column. Normally this is a relative XPath evaluated relative to the target item used to create the row.

This section also allows the datatype of each column to be specified as TEXT, INTEGER or REAL. The default value if unspecified is TEXT. See http://www.sqlite.org/datatype3.html for more details about how types affect tables in SQLite.

Below are two examples of XPath sources.

Example 1

The Setup above selects all the rows from CPU dataviews in Managed Entities with an Attribute OWNER=ITRS. We are extracting the following information:

  • Entity Name
  • CPU Name
  • Utilisation
  • WaitTime

This is set up by targeting one cell from each row of the relevant dataviews. The XPath filters the dataviews using attribute name. The cell use here is the percentUtilisation column. (Note that you cannot use the cpu column as it is the rowname column and cannot be selected as a cell by the XPath). The XPath for each column is specified relative to the target cell.

  • Entity Name: The Entity name is obtained from the entity that owns the target cell [ ancestor-or-self::managedEntity ]
  • CPU Name: The CPU name is obtained from rowname of the target cell [ @rowname ]
  • Utilisation: The utilisation is obtained from the value of the target cell [ @value ]
  • WaitTime: The wait time is obtained from the percentWaitTime cell in the same row as the target cell [ ../cell[(@column="percentWaitTime")]/@value ]

The setup dialog above also shows how the data type can be set for each column if required (the default is TEXT).

The XPath source table defined above can be used to populate a dataview as follows:

Example 2

The Setup above selects a basic summary for each Managed Entity with an Attribute OWNER=ITRS. We are extracting the following information:

  • Entity Name: The Entity name is obtained from the entity [ . ]
  • cpus: The numOnlineCpus headline in the CPU sampler [ ./sampler[(@name="CPU")]/dataview[(@name="CPU")]/headlines/cell[(@name="numOnlineCpus")] ]
  • mem: The memoryUse from the Hardware sampler [ ./sampler[(@name="HW")]/dataview[(@name="HW")]/rows/row[(@name="memoryUse")]/cell[(@column="Value")]]

These column XPaths utilise a short cut provided by gateway-sql. If a column XPath refers to a cell, then its value will be used as the column value. If the XPath refers to a data item that is not a cell (such as a directory, probe, managed entity or sampler), then the name of the data item will be used as the column value.

The XPath source table defined above can be used to populate a dataview as follows:

Sampler queries

The examples above have shown the use of simple queries to populate the dataviews generated by the plug-in.

Multiple views can be defined, each with its own query. Each view can combine tables from any combination of the data sources described in the previous section.

Queries are written in the dialect of SQL supported by SQLite, which is described at http://www.sqlite.org/lang.html.

The sampler performs SQL queries at three different times.

  • Setup SQL: This query is performed every time the sampler is created. (e.g. at gateway startup and when the setup changes).
  • Sampler SQL: This query is performed once per sample. It is performed after the tables have been populated
  • View SQL: These queries (one for each view) are performed after the 'Sampler SQL' again once per sample.

Sampler processing

The steps that the sampler goes through to generate its views are:

Sampler Setup

This occurs when the sampler is first created. It also occurs when any sampler parameters are changed, as the sampler is destroyed and recreated at this time.

  1. Create a private in-memory database accessible only by this sampler
  2. Create the dataviews that will be populated by the sampler
  3. Run the setup SQL statements if defined

If there is an error on running the setup SQL then an error will be displayed in the sampling status on all the views and further changes will not occur to the views until the error is corrected.

Sampler Sample

This occurs at a regular interval specified in the sampler setting.

  1. For each source table defined on the sampler
    • Find the source dataview (does not apply to XPath sources)
    • Drop the table from the database
    • Recreate the table
    • Populate the table from the source dataview (or row XPaths)
  2. Run the sampleSQL statements if defined
  3. For each output view defined on the sampler
    • Empty the dataview
    • Use the view's SQL statement to extract data from the database
    • Push the changes into the gateway

If an error occurs in stage 1 or stage 2 an error will be displayed in the sampling status on all the views. The processing will then stop for that sample. The next sample will start again and continue if the error no longer occurs.

If an error occurs in stage 3 then an error will be displayed in the sampling status of the view the error occurred upon. No further processing will occur on that view but the other views will still be processed.

When looking for a dataview in stage 1a, if the dataview is not found, or if the dataview is unpopulated (no row or column names defined) then an error will result. If multiple dataviews are found then the first one found will be used.

Debugging

The plugin provides debug settings to help to configure the sampler. These are set in the debug settings of the sampler. The following settings are available;

  • statusDetails: This debug setting provides additional information to the log file if an error occurs during sampling.
  • showQueries: This debug setting outputs all the SQL queries passed to the sampler's database. This includes those defined in the configuration and those used by the sampler to create and populate source tables.
  • debugSQLCommands: This debug setting enables a debug gateway command that allows the user to perform SQL commands on the in-memory database maintained by the sampler. Please note that this database is transitory and can be reset by setup changes/re-sampling.
  • showSampleTimes: This debug setting will log time spent during each sample, which can be useful when profiling the setup. The times given mirror the times that are reported by the Gateway-load plugin when monitoring Gateway-sql.

In order to understand how much time is being spent processing these plugins, a new section has been added to the Gateway-gatewayLoad configuration to monitor the time spent in Gateway-sql plugins. This can be grouped and filtered by entity or sampler name, allowing a detailed breakdown by individual sampler.

Configuration

samplers > sampler > plugin > gateway-sql > tables

This section is used to specify the source data for a table in the sampler's in-memory database.

samplers > sampler > plugin > gateway-sql > tables > dataview

This allows the specification of a dataview table as the source of the data for the table. See Dataview sources

samplers > sampler > plugin > gateway-sql > tables > dataview > tableName

The name of the table to create in the sampler's in-memory database. This table is destroyed and recreated each sample.

samplers > sampler > plugin > gateway-sql > tables > dataview > xpath

The path to a dataview used to populate a table in the sampler's in-memory database. If this path points to more than one dataview then only the first matching dataview will be used. This path can be an absolute path or a relative path. If a relative path is used then the path will be relative to the instance of the sampler. So to get a specific dataview in the same managed entity you would use a path similar to the one below;

../sampler[@name="cpu"]/dataview[@name="cpu"]
samplers > sampler > plugin > gateway-sql > tables > dataview > columns

The optional column names of the table.

If not specified then the table is destroyed and recreated each sample with columns that match the columns in the dataview.

If specified then the table is created at sampler start/setup change. The columns created are those specified in this section. If the optional affinities are set then those are used when creating the table. In the case when the columns are specified the table will be truncated rather than re-created each sample.

samplers > sampler > plugin > gateway-sql > tables > headlines

This allows the specification of a dataview's headline variables as the source of the data for an sql table. See Headline sources

samplers > sampler > plugin > gateway-sql > tables > headlines > tableName

The name of the table to create in the sampler's in-memory database. This table is destroyed and recreated each sample.

samplers > sampler > plugin > gateway-sql > tables > headlines > xpath

The path to a dataview used to populate a table in the sampler's in-memory database. If this path points to more than one dataview then only the first matching dataview will be used. This path can be an absolute path or a relative path. If a relative path is used then the path will be relative to the instance of the sampler. So to get a specific dataview in the same managed entity you would use a path similar to the one below;

../sampler[@name="cpu"]/dataview[@name="cpu"]
samplers > sampler > plugin > gateway-sql > tables > xpath

This allows the specification of a subset of the geneos data as the source of the data for an sql table. See XPath sources for more details.

samplers > sampler > plugin > gateway-sql > tables > xpath > tableName

The name of the table to create in the sampler's in-memory database. This table is destroyed and recreated each sample.

samplers > sampler > plugin > gateway-sql > tables > xpath > xpaths

A list of XPaths used to obtain a set of dataitems. Each dataitem will be used to generate a row in the table. The column XPaths (samplers > sampler > plugin > gateway-sql > tables > xpath > columns) will be used relative to these items to define the values to put in column of the row. See XPath sources for more details.

samplers > sampler > plugin > gateway-sql > tables > xpath > columns

This specifies the columns of the table. The column definition is composed of:

  • Name: This is the name of the column created in the database table
  • XPath: This is path is used in conjunction with the table XPath to populate the table cells in the column. See XPath sources for more details.
  • Type: This is the type of the database column. If not specified then it defaults to TEXT.
samplers > sampler > plugin > gateway-sql > views

This section defines the views that will be created by the sampler. The sampler can create multiple views pulling data from the same set of dataviews.

samplers > sampler > plugin > gateway-sql > views > view > name

This is the name of the dataview that is to be created.

samplers > sampler > plugin > gateway-sql > views > view > sql

This is the sql query that will be run to produce the data for the dataview. The dataview is cleared each sample and then populated with the results from this query.

samplers > sampler > plugin > gateway-sql > views > view > showRowID

This flag controls the way that view's SQL query result is mapped into a Geneos dataview. If this flag is set then the row name will be column called RowID, that will contain an incrementing row number starting at 1. If the flag is missing or false then the row name will be the first column extracted from the database, as defined by the view's SQL.

Mandatory: No
Default: false
samplers > sampler > plugin > gateway-sql > views > view > disabled

This is the flag can be used to disable individual views in the sampler. If the flag is set the the views will not be generated, and the dataviews will not be added to the sampler.

Mandatory: No
Default: false
samplers > sampler > plugin > gateway-sql > setupSql

This defines a piece of SQL that is run when the in-memory database is created. This is run only once. (At gateway start up or when the sampler parameters are changed). This SQL can contain more than one statement (separated by semi-colons).

samplers > sampler > plugin > gateway-sql > sampleSql

This defines a piece of SQL that is run after all the source tables have been populated, but before the view extraction queries are run. This SQL can contain more than one statement (separated by semi-colons) and is run on every sample of the sampler.

Database Logging plugin

samplers > sampler > plugin > Gateway- databaseLogging

The plug-in monitors the database logging configuration and status of everything that is logged from Gateway to a database.

The plugin has 3 views: Summary View, Cache view and Items view.

Summary view

Summary view shows the overall database settings and connection status. Below is a snapshot of how the Summary view might look:

List Variables:

Variable Name Description
host The configured host for the gateway's database connection. (This will be blank for Oracle and Sybase connections).
port The configured port for the gateway's database connection. (This will be blank for Oracle and Sybase connections).
database Database name
type Type of database (MySQL, SQLServer, Sybase, Oracle)
version Version of the database (if connected).
enabled Is database logging enabled (true, false)
connectionStatus Status of database connection if enabled (Pending, Connected, Not Connected)
connectionPaused Is database connection paused (using Database Logging -> Connection -> pause command)
discardingItemValues Is discarding item values (using Database Logging -> Item values -> discard command)
timeSinceLastSuccess Time in seconds since last successful log to the database. This is updated every sample interval.

Points to Note:

  • When the Gateway connects to a database, the 'connectionStatus' will be 'Connected'. If the user then pauses the database connection (using Database Logging -> Connection -> pause command), the connection will be dropped from the Gateway and the 'connectionStatus' will update to 'Not Connected'. If the user then resumes the connection, the 'connectionStatus' will not update until there is something to log to the database at which point the Gateway will re-establish connection to the database and the 'connectionStatus' would reflect this as 'Connected'.
  • The `severity` value reported in this dataview reflects the severity of the Gateway, thus it is affected by severity and snooze data imported from other gateways as well as severity and snooze data generated on this gateway.
  • If the Gateway is started in paused connection mode, then the 'connectionStatus' would sit at 'Pending' state until the user resumes the database connection.

Cache view

Cache view gives details about the internal queue and cache (dump) files statistics. Below is a snapshot of how the Cache view might look:

List Variables:

Variable Name Description
autoReload Is auto reloading of dump files enabled (true/ false)
cacheFiles No of dump files on disk
cacheLocation The directory where dump files are created/stored
cachePeriod The maximum duration for which dump files will be stored before the oldest file is discarded
cacheSize Total size of the dump files on disk
maxCacheSize The upper limit for the total size of the dump files as configured in the setup
queueSize Current internal queue size (Internal queue holds the log requests which are yet to make into database)
maxQueueSize The upper limit for the internal queue size as configured in the setup. When this limit is hit, the log requests are dumped to disk (if dump files creation is enabled)
oldestCacheData The oldest dump file on disk (in days)
writingNewFiles Is creation of new dump files enabled (true/false)

Items view

Items view gives details about the DB items configured in the setup such as which table are they configured to log to, the number of live data cells matching their target paths, and how many of those have been logged or failed to log.

Below is a snapshot of how the Items view might look:

Headline Variables:

Variable Name Description
successfullyLogging Total number of data items from all DB items target XPaths that were successfully logged to the database on their last value update.
failingLogging Total number of data items from all DB items target XPaths that failed to log to the database on their last value update.
loggingNotAttempted Total number of data items from all DB items target XPaths that were not attempted to log to the database on their last value update.

Row variables (Single row per configured DB item):

Variable Name Description
name Name of the DB item configured in the setup
table The database table it is configured to log to
active Whether active when active time is configured. (active/inactive). If active time not configured, it is always active.
matchingDataItems The number of live data cells that match all the target XPaths configured per this DB item.
successfullyLogging The number of data items that were successfully logged on their last value update.
failingLogging The number of data items that failed to log on their last value update.
loggingNotAttempted The number of data items that were not attempted to log on their last value update.

Points to Note:

  • The 'matchingDataItems' reflects count of all data items that match the target XPaths in the DB item. A dataitem may match more than one target XPaths in the DB item, hence, this value is not a count of unique data items. Same is true for 'successfullyLogging', 'failingLogging', 'loggingNotAttempted' counts.
  • A dataitem may match multiple target XPaths across different DB items. Hence, the headline variables 'successfullyLogging', 'failingLogging' and 'loggingNotAttempted' is not a count of unique data items in the system.
  • The 'successfullyLogging', 'failingLogging', 'loggingNotAttempted' count are not updated when a configured active time enters inactive period.
  • The 'failingLogging' count will go up when the database connection is paused and there are data item value updates.

Severity Data plugin

samplers > sampler > plugin > Gateway-severityData

The plug-in monitors and displays details of all cells with WARNING or higher severity. The plugin can be configured to monitor a subset of the cells by filtering the output by Managed Entity.

Headline Variables:

Variable Name Description
warningItems

Number of warning items displayed in dataview.

criticalItems

Number of critical items displayed in dataview.

filterIn Displays the inclusive attribute filters. See filter setting.
filterOut Displays the exclusive attribute filters. See filter setting.

Row variables:

Variable Name Description
id Unique identifier for this cell.
componentType The directory component type of this DataItem. Example: Cell.
probe The probe for this DataItem.
managedEntity The managed entity for this DataItem.
sampler The sampler for this DataItem.
dataView The dataview for this DataItem.
cell The cell for this DataItem.
type The configured sampler type for this DataItem.
plugin The configured plugin type for this DataItem.
severity The severity for this DataItem (Warning/Critical).
snoozed Whether this DataItem is snoozed (true/false).
userassigned Whether this DataItem is assigned to a user (true/false).
active

Whether this DataItem is active (true/false).

Note: The `severity`, `snoozed`, `userassigned` and `active` values reported in this dataview reflects the values currently on the cell, thus it is affected by data imported from other gateways as well as data generated on this gateway.

timestamp The time the most recent severity change (Warning/Critical) for this DataItem occurred.

Note: For the timestamp variable, time is updated when severity is first logged by the gateway and when severity changes between Warning/Critical states. Active and snooze state changes do not affect the timestamp. Timestamp values for imported severities are created at the time they are imported, not when they occurred on the originating gateway.

 
 

samplers > sampler > plugin > Gateway-severityData > filter

This setting is used to filter the cells listed in the plugin. The cells are filtered by ManagedEntity. If the setting is not present then all assigned cells on the gateway will be listed, unless they are filtered by one of other filter setting [includeUserAssigned, includeSnoozed or includeInactive]

Mandatory: No

samplers > sampler > plugin > Gateway-severityData > filter > useAncestorManagedEntity

If this setting is present then the sampler will only display critical and warning labelled cells that are descendants of the managed entity to which the sampler belongs.

samplers > sampler > plugin > Gateway-severityData > filter > filterByAttribute

A set of one or more filters which can be used to limit the number of managed entities that contribute data to the sampler's dataview. Each filter is applied in order and a managed entity needs to be accepted by all the filters in order to contribute data.

samplers > sampler > plugin > Gateway-severityData > filter > filterByAttribute > include

This setting defines a filter on an individual attribute. Any managed entities that have the specified attribute defined in the filter with a value that matches one of the values provided in the filter is accepted by this filter. Any other managed entity is rejected by this filter.

samplers > sampler > plugin > Gateway-severityData > filter > filterByAttribute > include > name

Name of the managed entity attribute tested by this filter.

samplers > sampler > plugin > Gateway-severityData > filter > filterByAttribute > include > values

Values of the managed entity attribute that is used by the filter to accept/reject managed entities from contributing data to the sampler's dataview. Managed entities whose specified attribute matches one of the listed values will be accepted by the filter. If the attribute is not specified on the managed entity or the specified attribute does not match one of the values provided it will be rejected by the filter.

samplers > sampler > plugin > Gateway-severityData > filter > filterByAttribute > exclude

This setting defines a filter on an individual attribute. Any managed entities that have the specified attribute defined in the filter with a value that matches one of the values provided in the filter is rejected by this filter. Any other managed entity is accepted by this filter.

samplers > sampler > plugin > Gateway-severityData > filter > filterByAttribute > exclude > name

Name of the managed entity attribute tested by this filter.

samplers > sampler > plugin > Gateway-severityData > filter > filterByAttribute > exclude > values

Values of the managed entity attribute that is used by the filter to accept/reject managed entities from contributing data to the sampler's dataview. Managed entities whose specified attribute matches one of the listed values will be rejected by the filter. If the attribute is not specified on the managed entity or the specified attribute does not match one of the values provided it will be accepted by the filter.

samplers > sampler > plugin > Gateway-severityData > filter > filterAttributes

A set of one or more filters which excludes managed entities if they contain attributes whose name and value match any of the filters defined here. If a managed entity is excluded all critical and warning labelled cell that are descendants of the managed entity will be excluded.

Deprecated: See filterByAttribute setting.

samplers > sampler > plugin > Gateway-severityData > includeUserAssigned

Includes user assigned cells in the dataview.

Mandatory: No
Default : true

samplers > sampler > plugin > Gateway-severityData > includeSnoozed

Includes snoozed cells in the dataview.

Mandatory: No
Default : false

samplers > sampler > plugin > Gateway-severityData > includeInactive

Includes inactive cells in the dataview.

Mandatory: No
Default : false

samplers > sampler > plugin > Gateway-severityData > excludeSelfGenerated

Whether to exclude rows that represent data generated by the plugin dataview itself.

As an example, a rule is placed on the timestamp column that causes cells to change to critical severity if the cell the row is monitoring has been at critical severity for more than 24 hours. If excludeSelfGenerated is set, then a new row will not be created if a cell in the timestamp column changes to critical severity after 1 day, because this is data generated by the plugin dataview itself.

Mandatory: No
Default : True

samplers > sampler > plugin > Gateway-severityData > maximumNumberOfRows

Maximum number of rows that the dataview will display. If the number of Warning and Critical cells that should be displayed in the dataview is greater than the maximum number of rows, but the number of Critical cells is less than the maximum number of rows then only the critical cells will be displayed in the dataview. If the number of Critical cells that should be displayed in the dataview is greater than the maximum number of rows then no rows will be displayed in the dataview. Whenever cells are not displayed because displaying them would cause the maximum number of rows in the dataview to be breached, an error will be displayed in the sampling status.

The headline variables "warningItems" and "criticalItems" will always display the number of cells that match the filters provided by the sampler. They are not affected by this setting.

Mandatory: No
Default : 100

samplers > sampler > plugin > Gateway-severityData > attributeColumns

A list of attributes that will be added to the dataview as additional columns. If a row represents a managed entity, the additional columns will be populated with the attribute values for the attributes defined. If a row represents the descendant of a managed entity, the additional columns will be populated with the attribute values of the ancestor managed entity for the attributes defined. If a row represents a gateway or a probe then the cells will be blank.

Gateway Breach Predictor plug-in

Introduction

A breach is defined as reaching or crossing a maximum tolerable threshold value for any entity or configurable variable in the Gateway.

Intra-day breach prediction is a feature that allows you to do breach prediction calculations for any particular variable or set of variables. This prediction is done based on the model data supplied by you as a Data Sets (Time series) and logged to the database. Intra-day breach prediction performs the prediction based on only one day's worth of data.

You can use the predicted information in a rule to be alerted well in advance if a breach will occur, so that you can take appropriate steps.

Configuration View

On creation, the Breach Predictor Plug-in has an empty predictor.

A predictor is a logical grouping of dataview cells on which breach prediction is to be performed. You must configure at least one predictor. There is no upper limit.

Clicking on Add new link presents the configuration options for a predictor. This presents options for the following:

The remainder of the settings are identical to any other Gateway Plugin.

adaptive-rules1

Predictor Settings

The settings below define the predictor.

predictors > predictor

A predictor is a logical grouping of the dataview cells that you want to use for the breach prediction calculation. You must create at least on predictor. This is no upper limit.

Mandatory: Yes (at least one predictor must be configured per plugin)

predictors > predictor > name

Name you want to identify each predictor with. Each predictor name should be unique across an instance of the plugin.

The name must not be empty because this throws a validation error in the GSE.

Mandatory: Yes

predictors > predictor > target

Xpath name or the data items that this predictor applies to. See Xpaths User Guide for more information on xpaths.

Mandatory: Yes

predictors > predictor > threshold

Specifies a threshold value that is to be used for the breach prediction calculation.

The threshold value must be a valid double value otherwise the predictor is ignored. The threshold is used as an upper limit value for breach prediction calculation. There is no way to provide a lower limit threshold value for breach prediction calculation within a particular range. The threshold can be a positive or negative value.

Mandatory: No
Default: 0.0

predictors > predictor > predictionFunction

The prediction function specifies which prediction function is to be used for prediction calculation. The drop down provides 2 values.

Value Effect
linear Linear function is used for breach prediction calculation.
percentage Percentage based function is used for breach prediction calculation.

Mandatory: No
Default: Linear

predictors > predictor > predictionFunction > linear

Linear based prediction is where the predicted values of the cell follow a graph which simulates the gradient of the cell values provided by the time series.

For example, the table below shows the values provided by the time series in second row. The current time is 9:00 and the current value of a cell is 5.00.

The predicted values of the cell follow the gradient of the values provided by the time series. Therefore, if the threshold value specified as 25.00, the breach is predicted to occur at 11:00.

Time 9:00 (current time) 10:00 11:00 12:00 13:00 14:00 15:00 16:00 17:00
Values from Time Series -10.00 0.00 10.00 20.00 30.00 40.00 30.00 20.00 10.00
Predicted Values 5.00 (current value) 15.00 25.00 35.00 45.00 55.00 45.00 35.00 25.00

predictors > predictor > predictionFunction > percentage

Percentage based prediction is where prediction is based on the percentage difference between the values provided by the time series and current value of the cell. The prediction cannot be done if the current value of cell is zero.

Example 1: The table below shows the values provided by the time series in second row. The current time is 9:00 and the current value of a cell is 20.00.

If the threshold value specified as 100.00, the breach is predicted to occur at 13:00.

Time 9:00 (current time) 10:00 11:00 12:00 13:00 14:00 15:00 16:00 17:00
Values from Time Series 10.00 20.00 30.00 40.00 50.00 60.00 70.00 80.00 90.00
Predicted Values 20.00 (current value) 40.00 60.00 80.00 100.00 120.00 140.00 160.00 180.00

Example 2: The table below shows the values provided by the time series in second row. The current time is 9:00 and the current value of a cell is -15.00.

If the threshold value specified as 20.00 the breach is predicted to occur at 16:00.

Time 9:00 (current time) 10:00 11:00 12:00 13:00 14:00 15:00 16:00 17:00
Values from Time Series -30.00 -20.00 -10.00 0.00 10.00 20.00 30.00 40.00 70.00
Predicted Values -15.00 (current value) -10.00 -5.00 0.00 5.00 10.00 15.00 20.00 35.00

predictors > predictor > timeSeries

Specifies a time series that is created in the data sets. The drop down shows a list of all the time series that have been created in the data sets.

If the user does not select any time series, then the corresponding rows in the breach predictor dataview state that the time series is non-existent and no prediction is done. The prediction is done only if the time series is valid and has data points updated from the database.

Mandatory: Yes

Data View

Upon configuring a valid breach predictor gateway plugin, a data view appears for the plugin. The data view displays as many rows as the total number of data view cells that have been configured through xpaths in all the predictors for that breach predictor gateway plugin.

Row variables (Single row per data item):

Variable Name Description
Id Unique identifier for this cell. Prepends Predictor name for identifying which predictor it belongs to.
componentType

The directory component type of this dataitem. One of :

  • gateway
  • probe
  • managedEntity
  • sampler
  • dataView
  • cell
probe The probe for this dataitem.
managedEntity The managed entity for this dataitem.
sampler The sampler for this dataitem.
dataview The dataview for this dataitem.
cell The cell for this dataitem.
type The configured type for this dataitem.
currentValue The value for this dataitem (in double).
thresholdValue Threshold value provided in the predictor.
timeSeries Name of the time series used as a model value for breach prediction calculation.
timeToBreach The predicted time to Breach. Blank in case the cell value is not expected to breach or if the prediction cannot be done.
timeOfBreach The predicted time of Breach. Blank in case the cell value is not expected to breach or if the prediction cannot be done.
description

Information about the breach. One of

  • Breached
  • Will Breach
  • No Data
  • No Prediction
  • Error: Non-existent Time Series

No Data appears if there are no values in the model time series or the current time is beyond the range of time for which the model values are present.
No Prediction appears if the prediction function is percentage-based, and the current value of cell is zero. In which case breach prediction cannot be done.