Gateway Plug-Ins

Overview Copied

Gateway plugins 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 plugins that are available are described in this topic.

Gateway RunTime Parameters Copied

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

• GatewayName — Name of the Gateway.
• GatewayHost — Hostname of Standalone or Primary Gateway (in case of Hot Standby pair).
• GatewayPort — Port of Standalone or Primary Gateway (in case of Hot Standby pair).
• SecurePort — If Gateway is listening or secure port (true/false).
• SecondaryHost — The hostname of Secondary Gateway (in case of Hot Standby pair).
• SecondaryPort — The port of Secondary Gateway (in case of Hot Standby pair).

Breach predictor Copied

Introduction Copied

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

On creation, the Breach Predictor Plugin 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:

• Name
• Target
• Threshold value
• Prediction Function
• Time Series

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

Predictor Settings Copied

The settings below define the predictor.

predictors > predictor Copied

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 one predictor. There is no upper limit.

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

predictors > predictor > name Copied

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 Gateway Setup Editor.

Mandatory: Yes

predictors > predictor > target Copied

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 Copied

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 Copied

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

Mandatory: No

Default: Linear

predictors > predictor > predictionFunction > linear Copied

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.

predictors > predictor > predictionFunction > percentage Copied

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.

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.

predictors > predictor > timeSeries Copied

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

Dataview Copied

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

Table legend Copied

Client connection data Copied

samplers > sampler > plugin > Gateway-clientConnectionData Copied

The plugin monitors currently connected client applications. This includes:

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

Headline legend Copied

The headline cells above the table display the following data:

Table legend Copied

The table cells display the following data:

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.

Database logging Copied

samplers > sampler > plugin > Gateway- databaseLogging Copied

The plugin 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 Copied

Summary view shows the overall database settings and connection status. For example:

Legend Copied

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 Copied

Cache view gives details about the internal queue and cache (dump) files statistics. For example:

Legend Copied

Items view Copied

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

The headline cells above the table display the following data:

Table legend Copied

The table cells display the following data:

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 headlines ‘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.

Exported data Copied

samplers > sampler > plugin > Gateway-exportedData Copied

Table legend Copied

The table cells display the following data:

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.

Forecaster Copied

samplers > sampler > plugin > Gateway-forecaster Copied

Caution

The Gateway-forecaster is a pilot feature. This feature is subject to change.

The plugin allows the consumption of Obcerv forecasted time-to-breach data and presents it visually on the Active Dashboard. This data enables you to establish rules, such as forecasting when a breach of a particular metric will occur. To use this plugin, you need to send data from the Gateway to Obcerv. This can be done by setting up the Obcerv Connection. For more information, see Connect Geneos to Obcerv.

The plugin employs REST APIs to retrieve data from Obcerv Forecaster. As this involves establishing a connection to Obcerv, you must initially set up an Obcerv endpoint. This can be configured with two parameters:

• Group
• Names (optional list of names)

Note

Results only display forecasts for metrics from the current Gateway.

If Group is the only parameter configured, then all available names will be displayed in the Active Dashboard. Otherwise, if one or more Names are specified, then the dataview will be populated only with the information that Obcerv Forecaster provides for those names.

Note

If multiple groups are required, then you have to create multiple plugins.

You can also choose whether to include items in the dataview for which the forecaster is unable to predict breaches. By default, items that the forecaster cannot predict will also be included. Refer to the screenshot below for the setting:

Once the data becomes available, the dataview will appear as follows:

Headline legend Copied

The headline cells above the table display the following data:

Table legend Copied

The table cells display the following data:

Gateway data Copied

samplers > sampler > plugin > Gateway-gatewayData Copied

The plugin monitors the current configuration and state of this gateway.

Legend Copied

The plugin provides the following properties:

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.

Gateway Hub data Copied

Introduction Copied

The Gateway Hub Data plugin monitors the current configuration and state of publishing to Gateway Hub from this Gateway. The plugin has two dataviews:

• Summary
• Nodes

Summary dataview Copied

The summary dataview provides general information regarding publishing from the Gateway to Gateway Hub.

Table legend Copied

The table cells display the following data:

Nodes dataview Copied

The nodes dataview provides information about the publishing and REST nodes.

Headline legend Copied

The headline cells above the table display the following data:

Table legend Copied

The table cells display the following data:

Show Dataviews Command Copied

The Show Dataviews command is available by right-clicking on the cells in the following columns and navigating to Gateway Hub > Show Dataviews:

• Num of dataviews published.
• Num of dataviews unpublished.
• Num of dataviews with errors.

The command opens a new window showing a table identifying the dataviews contributing to the count in that cell.

The table has the following columns:

• Managed Entity.
• Sampler.
• Type.
• Dataview.

Gateway load Copied

samplers > sampler > plugin > Gateway-gatewayLoad Copied

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 plugin.

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, see Gateway Performance Tuning.

Categories Copied

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

Component Statistics Copied

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

Headline legend Copied

The headline cells above the table display the following data:

Table legend Copied

The table cells display the following data:

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

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 plugin whose data is causing excessive load on the gateway.

Headline legend Copied

The headline cells above the table display the following data:

Table legend Copied

The table cells display the following data:

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 Copied

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 or Web Dashboards, as well as other components such as a hot-standby Gateway, Licence Daemon or web-based http connections.

Headline legend Copied

The headline cells above the table display the following data:

Table legend Copied

The table cells display the following data:

XPath Statistics Copied

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

The headline cells above the table display the following data:

Table legend Copied

The table cells display the following data:

ORB Statistics Copied

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

The headline cells above the table display the following data:

Table legend Copied

The table cells display the following data:

Gateway-sql Statistics Copied

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

The headline cells above the table display the following data:

Table legend Copied

The table cells display the following data:

Commands Copied

The underlying statistics for the gateway load monitoring plugin 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 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 Copied

samplers > sampler > plugin > Gateway-gatewayLoad > maximumNumberOfRows Copied

Maximum number of rows displayed on the dataview. The rows with the highest values for the main statistics are displayed. For most categories, and when the statistics > expandType option is used, this is the “Time” or “TotalTime” column. For connection statistics, it is the sum of “ReceiveRate” and “SendRate”. When a single statistic is shown for multiple features, that statistic is summed across the features.

Note

The performance of the Gateway may be affected if this setting is increased significantly above the default value.

Mandatory: No

Default: 200

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

Specifies the category of statistics to display:

• Component statistics
• Directory statistics
• Connection statistics
• XPath statistics
• ORB statistics
• Gateway-sql statistics

Mandatory: Yes

samplers > sampler > plugin > Gateway-gatewayLoad > view > source > file Copied

The file data source specifies that the plugin 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.

The file will be read if it has been updated since the last sample. Reading a very large statistics file may take several seconds. The results are cached across all Gateway Load samplers reading the file, so the amount of Gateway processing allocated to reading the file is affected by the shortest sample interval of those samplers. If a file that takes 12 seconds to read is updated and sampled every 10 seconds, the Gateway will become unresponsive.

Mandatory: No

Default: If not specified, the plugin reads data from gatewayInternals source.

samplers > sampler > plugin > Gateway-gatewayLoad > view > source > gatewayInternals Copied

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

Mandatory: No.

Default: If not specified, the plugin reads data from gatewayInternals source.

samplers > sampler > plugin > Gateway-gatewayLoad > view > category > componentStats > grouping Copied

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 Copied

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 Copied

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
• Plugin
• Probe
• Rule
• Sampler
• Type
• Database Item

Mandatory: No

Default: No filtering

samplers > sampler > plugin > Gateway-gatewayLoad > view > category > directoryStats > grouping Copied

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 Copied

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 Copied

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 plugin will display a perType Time statistic.

samplers > sampler > plugin > Gateway-gatewayLoad > view > category > xpathStats > filter > method Copied

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

Mandatory: No

Default: All methods are summarised into a single figure

Includes data Copied

samplers > sampler > plugin > Gateway-includesData Copied

The plugin monitors the include files that are currently configured on this gateway.

Table legend Copied

The table cells display the following data:

Imported data Copied

samplers > sampler > plugin > Gateway-importedData Copied

Table legend Copied

The table cells display the following data:

Licence usage Copied

samplers > sampler > plugin > Gateway-licenceUsage Copied

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 Copied

Specifies which licensing groups configured on the daemon the plugin 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 Copied

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

Mandatory: No

samplers > sampler > plugin > Gateway-licenceUsage > showOverall Copied

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 Copied

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

Mandatory: No

Default: false

Managed entities data Copied

samplers > sampler > plugin > Gateway-managedEntitiesData Copied

The plugin monitors the Managed Entities whose data is being monitored via this Gateway. This plugin has two dataviews:

• Summary dataview
• Entities dataview

Entities Summary dataview Copied

This dataview provides the following properties:

Entities Details dataview Copied

The dataview provides details on each entity being monitored by the Gateway.

samplers > sampler > plugin > Gateway-managedEntitiesData > mode Copied

Mode can either be Summary Only or Summary And Details. If Summary Only is selected then only the Summary dataview is generated by the plugin, otherwise both dataviews are generated.

Mandatory: No

Default: Summary Only

Obcerv Connection Copied

The Obcerv Connection plugin monitors the current configuration and state of the Gateway connection to Obcerv. The plugin has two dataviews:

• Summary
• Detail

Summary dataview Copied

The summary dataview provides general information regarding publishing from the Gateway to Obcerv and, Active Console access to Obcerv.

Table legend Copied

Detail dataview Copied

The detail dataview shows separate message statistics for the different types of messages that may be published.

Table legend Copied

Show Dataviews Command Copied

The Show Dataviews command is available by right-clicking on the cell values in the following rows and navigating to > Show Dataviews:

• dataviewsPublished.
• dataviewsUnPublished
• dataviewsWithErrors

The command opens a new window that shows a table identifying the dataviews contributing to the count in that cell.

The table has the following columns:

• Managed Entity
• Sampler
• Type
• Dataview

Probe data Copied

samplers > sampler > plugin > Gateway-probeData Copied

The plugin monitors the probes whose data is being monitored via this Gateway. This plugin has two dataviews:

• Netprobe dataview
• Collection Agent dataview

Netprobe dataview Copied

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

Headline legend Copied

The headline cells above the table display the following data:

Table legend Copied

The table cells display the following data:

Optional columns:

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.

Collection Agent dataview Copied

Note

Rows in the Collection Agents dataview will not disappear even if the Netprobe goes down.

Table legend Copied

Commands Copied

The following commands are available in the Collection Agent dataview:

• View Log
• View Configuration
• View Error

The View Log and View Configuration commands are also available when you right-click the following in the State Tree:

• Netprobes with configured Dynamic Entities
• Dynamic Managed Entities
• Dynamic Entity Health samplers

View Log Copied

This command shows the logs of the corresponding Collection Agent of the selected cell. When you right-click on any cell except for the probeName, and select theCollection Agent > View Log… option, a dialog box will open to specify options on how you want to view the logs.

The following parameters can be set:

• Initial Download size(kb) — sets the initial download size of the log file. This defaults to 2 kb.
• Delivery Type — allows you to choose between Snapshot and Continuous delivery type. The snapshot delivery type displays the contents of the log file at the time it was generated, while continuous delivery type displays logs continuously in real-time.
• Filter String — allows you to specify strings that will filter the Collection Agent log file.

Sample Output (Snapshot delivery type) Copied

View Configuration Copied

When you right-click on any cell except for the probeName, and select theCollection Agent > View Configuration option, a new window displaying the configuration of the corresponding Collection Agent will open.

Sample Output Copied

View Error Copied

When you right-click on a cell in the status column, and select theCollection Agent > View Error option, a new window displaying more inforopen.

Sample Output Copied

samplers > sampler > plugin > Gateway-probeData > processAttributes Copied

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 Copied

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

Scheduled command data Copied

samplers > sampler > plugin > Gateway-scheduledCommandData Copied

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

Dataview Copied

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

Headline legend Copied

The headline cells above the table display the following data:

Table legend Copied

The table cells display the following data:

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 Copied

samplers > sampler > plugin > Gateway-scheduledCommandsHistoryData Copied

The plugin monitors the past runs of currently configured Scheduled Commands.

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

Configuration Copied

samplers > sampler > plugin > Gateway-scheduledCommandsHistoryData > scheduledCommand Copied

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 Copied

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

Mandatory: No

Dataview Copied

Headline legend Copied

The headline cells above the table display the following data:

Table legend Copied

The table cells display the following data:

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.

Severity count Copied

samplers > sampler > plugin > Gateway-severityCount Copied

The plugin monitors the number of cells with OK, WARNING or CRITICAL severities.

Headline legend Copied

The headline cells above the table display the following data:

Table legend Copied

The table cells display the following data:

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

A list of view paths.

Mandatory: No

Default: no path defined

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

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 Copied

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 Copied

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 Copied

Whether to include inactive cells in the count.

Mandatory: No

Default: false

samplers > sampler > plugin > Gateway-severityCount > appendManagedEntity Copied

Whether to drill down to managed entity level.

Mandatory: No

Default: false

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

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 Copied

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 Copied

Name of the managed entity attribute tested by this filter.

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

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 Copied

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 Copied

Name of the managed entity attribute tested by this filter.

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

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 Copied

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.

Severity data Copied

samplers > sampler > plugin > Gateway-severityData Copied

The plugin 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 legend Copied

The headline cells above the table display the following data:

Table legend Copied

The table cells display the following data:

Note

For the timestamp metric, 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 Copied

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 Copied

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 Copied

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 Copied

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 Copied

Name of the managed entity attribute tested by this filter.

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

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 Copied

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 Copied

Name of the managed entity attribute tested by this filter.

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

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 Copied

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

Provides a drop-down list to select for only warning severities, critical severities, or both to appear in the dataview:

• Select Critical to have only critical severities appear in the dataview. Warning severities are excluded.
• Select Warning to have only warning severities included in the dataview. Critical severities are excluded.
• Select Warning and critical to have both severity levels included in the dataview.

Mandatory: No

Default : Warning and critical is selected.

samplers > sampler > plugin > Gateway-severityData > includeUserAssigned Copied

Includes user assigned cells in the dataview.

Mandatory: No

Default: true

samplers > sampler > plugin > Gateway-severityData > includeSnoozed Copied

Includes snoozed cells in the dataview.

Mandatory: No

Default: false

samplers > sampler > plugin > Gateway-severityData > includeInactive Copied

Includes inactive cells in the dataview.

Mandatory: No

Default: false

samplers > sampler > plugin > Gateway-severityData > excludeSelfGenerated Copied

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 Copied

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 Copied

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.

Snooze data Copied

samplers > sampler > plugin > Gateway-snoozeData Copied

The plugin monitors all data-items that are currently snoozed:

Headline legend Copied

The headline cells above the table display the following data:

Table legend Copied

The table cells display the following data:

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

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 Copied

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 Copied

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 Copied

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 Copied

Name of the managed entity attribute tested by this filter.

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

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 Copied

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 Copied

Name of the managed entity attribute tested by this filter.

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

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 Copied

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 Copied

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 Copied

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

Menu Items Copied

Unsnooze Absent Items Copied

This command is available on the snoozedButAbsentItems headline if the Gateway-snoozeData 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.

Gateway-SQL Copied

samplers > sampler > plugin > Gateway-sql Copied

Introduction Copied

This plugin is part of the Compute Engine functionality of the gateway; unlike the other Gateway plugins, 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 plugin to manipulate the dataviews, not to store any historical data. The version of SQLite used in this plugin 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.

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 Copied

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 Copied

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 Copied

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:

Headline sources Copied

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:

XPath sources Copied

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 Copied

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

Example 2 Copied

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.

Sampler queries Copied

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

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 Copied

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

Sampler Setup Copied

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 Copied

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 Copied

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 Copied

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

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 Copied

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 Copied

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 Copied

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 Copied

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 Copied

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

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

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 Copied

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 Copied

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 Copied

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 Copied

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 Copied

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 Copied

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 Copied

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

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

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 Copied

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 Copied

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 Copied

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 Copied

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.

User assignment data Copied

samplers > sampler > plugin > Gateway-userAssignmentData Copied

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

Headline legend Copied

The headline cells above the table display the following data:

Table legend Copied

The table cells display the following data:

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

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 Copied

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 Copied

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 Copied

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 Copied

Name of the managed entity attribute tested by this filter.

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

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 Copied

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 Copied

Name of the managed entity attribute tested by this filter.

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

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 Copied

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 Copied

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 Copied

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 Copied

Unassigned Absent Items Copied

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.