Samplers

Overview

Samplers perform the real work of the Geneos monitoring system. Each Netprobe hosts a set of samplers which are responsible for collecting the monitoring data and forwarding it to a Gateway for processing. The monitoring configuration for each Netprobe is controlled by a Gateway, allowing for a centralised management approach. The configuration that is sent to Netprobe is made up largely of samplers defined within this section.

Samplers running on Netprobes typically gather and publish data (a sample) every 20 seconds to the rest of the system, called regular sampling. The delay between samples is called the sample interval.

Also in this document are the settings for sampler include. Sampler include allow users to configure subsets of sampler information. The information from all relevant sampler include sections is combined and passed to relevant samplers. See Sampler Include

Operation

Basic configuration

The Samplers top-level section contains a list of sampler definitions. Each definition must be uniquely named among all other sampler definitions to avoid ambiguity, because samplers are referenced in other parts of the Gateway setup (e.g. in Types and Managed Entities and Managed Entity Groups) by name.

To create a new sampler using the Gateway Setup Editor, follow these steps:

Select the Samplers top-level section. If this section does not exist, double-click to create it.
Select the New sampler button to create a new sampler definition.
Give the new sampler a unique name. This name is used to reference the sampler from other parts of the gateway setup.

Note: Names are case-sensitive.

By default samplers will collect data (sample) every 20 seconds. You can optionally change that value here using the sampleInterval setting.
The main sampler configuration is contained under the "Plugin" tab. Here you can select the plug-in to run and configure plug-in specific settings. Please see the specific plug-in documentation for a full description of these configuration settings.
For the purposes of configuring an example sampler, select the CPU plug-in from the drop-down combo-list. The CPU plug-in does not need any additional configuration in order to run - the default values are sufficient.

Once a sampler has been created, it can then be referenced with a type of managed entity. For an example usage, see the How to create and configure a new managed entity .

Sampler Groups

Samplers can be grouped in the Gateway Setup Editor for ease of management, by means of a Sampler group. These groups are ignored by Gateway and have no effect on the resulting directory structure produced by the setup.

To create a new Sampler Group, follow these steps:

Right-click on the Samplers top-level section and select the New samplerGroup menu option. This creates a new group section.
Specify the name for the sampler group. This name is not read by Gateway, and so can be used to describe the contents of the group.
Add samplers from the group by using drag-and-drop in the Navigation pane. New samplers can be created within the group by clicking the New sampler button.
Sampler groups can also contain nested sampler groups. These can be created using the right-click menu in the Navigation pane, and managed using drag-and-drop in the same manner as for sampler definitions.

Expect Rows

Expect rows are a mechanism for forcing a row to appear in a dataview. When using "expect rows" an additional column "Availability" is added to the dataview, showing whether an expected row is "present" or "absent". This allows users to set rules on data which the user expects to be present but is in fact unavailable for some reason.

To use this feature, simply configure the name of each row that is expected to be present using the expectRows setting.

Each individual expect row can be configured using static strings and string variables as shown below;

ref-guide34

It is also possible to use a single variable to define all of the expected rows. To do this you must create a stringList variable and set the expect rows setting to var and then select the stringList from the variable dropdown.

Note: Expect rows works only with Netprobe published dataviews and is not designed to work with Gateway created dataviews using compute engine (when samplers > sampler > dataviews > dataview > createOnGateway is enabled).

Dataviews

Samplers can also contain additional configuration for the dataviews they produce. This is placed in the samplers section rather than a top-level dataviews section because the dataview name alone does not make it unique in the setup. Several samplers may produce dataviews with the same names, and some plug-ins even generate dataview names based on information read from a log file.

To configure dataview settings the dataview must be referenced by name. To use this functionality, it is recommended that users configure and run a plug-in first, and then copy the name using the Active Console copy name command. Settings which can be used to configure dataview behaviour are described briefly below.

Expect rows

Expect rows for dataviews work in exactly the same way as for sampler expect rows. They can be configured on a dataview to allow users to apply expect rows to a specific view, in the case where a sampler produces multiple views. Expect rows are configured using the expectRows setting.

Metadata

Some items of metadata can be set on a dataview, namely group and overviewType. The group name can optionally be used for grouping dataviews in the Active Console metrics view, in addition to searching and sorting functions.

The overview type is used when creating combining several dataviews into a single metrics view. This functionality is known as a metrics overview. By default, views are combined using the plug-in name. This is sufficient for most plug-ins, but for views created using the TOOLKIT plug-in for example the data within the view may not be the same for all TOOLKIT samplers. Setting the overview type in these instances will allow Active Console to match dataviews according to their user‑specified type, producing a better metrics overview.

Additional data

Gateway can optionally create additional data inside a dataview. This includes extra headlines, columns and also rows. These extra cells are initially empty when created, and are typically used to provide extra metrics for a dataview which are then populated using the Compute Engine functionality. See Compute Engine.

When creating this additional data, users have the choice of whether to create a completely new dataview on the gateway, or to augment an existing dataview coming from Netprobe. This choice is controlled by samplers > sampler > dataviews > dataview > createOnGateway.

Configuration

This section describes all configuration settings available in the Samplers top-level section.

samplers

The samplers top-level section contains the configuration details of all the samplers which the gateway will use to monitor data.

samplers > samplerGroup

A sampler group allows grouping of sampler definitions for ease of management in the Gateway Setup Editor. A sampler group can contain both a list of sampler definitions, and nested sampler groups.

samplers > samplerGroup > name

Specifies the name of the sampler group. This name is not read by gateway and so can be used as a description of the group.

Mandatory: Yes

samplers > sampler

A sampler definition contains the configuration needed to monitor an aspect of a system. This configuration contains both general settings which can be applied to any sampler and plug-in specific configuration which specifies what to monitor and how to obtain the data.

Sampler settings- Basic tab

These settings are found under the Basic tab for a sampler definition.

samplers > sampler > name

Specifies the name of the sampler. This name is used to reference the sampler from Types and Managed Entities so to avoid ambiguity the sampler name must be unique among all other samplers.

The sampler name must only contain characters that satisfy the regex pattern [a-zA-Z0-9_\-\\%].

Mandatory: Yes

samplers > sampler > group

Optionally specifies a group name. See Groups for more details. Can be a variable.

Mandatory: No

Default: (no group)

samplers > sampler > description

Optionally specifies a description. See Descriptions for more details.

Mandatory: No

Default: (no description)

samplers > sampler > sampleInterval

Time in seconds between two samples taken by the sampler. This setting controls how often the sampler checks for changes in monitored data.

Value should be a non-negative integer value. A value of 0 prevent the sampler from sampling. You can still force a sample using the Sample now command accessible through Active Console, or by configuring another sample control method below.

Mandatory: No

Default: 20 (seconds)

samplers > sampler > plugin

Optionally specifies a plugin to be associated with this sampler.

Mandatory: No

Sampler settings- Advanced tab

These settings are found in the Advanced tab.

samplers > sampler > displayName

Defines a name that is displayed by the Active Console instead of the actual name of the sampler in the State Tree view. Other views such as Metrics view are not affected. This name is used for display purposes only - the original name of the sampler must be used for all references to the data view (for example in rules).

Note: This setting only affects the name of the sampler, and not any of its dataviews. To change the display name of a dataview in the state tree, see samplers > sampler > dataviews > dataview > displayName.

Mandatory: No

Default: (original name of the sampler)

samplers > sampler > sampleOnStartup

Boolean setting that controls whether the sampler should perform an initial sample on start‑up, when the gateway sends down the sampler configuration to netprobe. .

By default all samplers sample once when the sampler configuration is sent to Netprobe.

Setting this parameter to false prevents this behaviour, but it is only effective in conjunction when Samplers is set to 0.

Mandatory: No

Default: true

samplers > sampler > sampleTimesOverride

If this setting is enabled, the sampler will sample for any sampleTimes that have been specified, regardless of any active times that have been specified. See samplers > sampler > sampleTimes.

By default sample times cause a sample regardless of any active times that have been specified. When set to false, a sampler that is inactive due to active times does not sample for any sample times that fall within the inactive period.

Mandatory: No

Default: true

samplers > sampler > sampleTimes

A list of times that configures a sampler to sample at specific times during the day. This is often used in conjunction with a sampleInterval of 0 to disable regular sampling. Times are configured as a comma-delimited list of times in the format HH:MM using 24-hour clock. These times will cause a sample regardless of any active times that have been specified unless sampleTimesOverride is set false (see below).

The times specified in this list are taken as local times on the Netprobe host. This list is typically used when regular sampling is disabled by setting SampleInterval to 0 and SampleOnStartUp to false, and is processed regardless of any active times.

Mandatory: No

samplers > sampler > sampleTimes > time

Specifies the time of day at which the sampler should sample. The format should be HH:MM using 24-hour clock, given in the local time of the Netprobe host.

Mandatory: Yes

samplers > sampler > fileTrigger

A file trigger is a path to a file accessible by Netprobe, and allows external control of a sampler.

Netprobe monitors all configured files for a change in modification time. When the modification time of the file is updated (e.g. using the UNIX utility touch) it causes the sampler to sample.

This setting is typically used when regular sampling has been disabled. It causes a sample regardless of any active times that have been specified.

Mandatory: No

samplers > sampler > fileTrigger > filename

Specifies the file to monitor for a file trigger.

Mandatory: Yes (if using a file trigger)

samplers > sampler > fileTrigger > maxPerMinute

Specifies the maximum number of times that a file trigger can be triggered per minute. The value must be a positive integer (greater than 0).

Mandatory: No

Default: 5

samplers > sampler > expectRows

This setting allows the configuration of expect rows for a sampler. This setting should only be used for samplers which produce a single dataview. For a more detailed description see Expect Rows.

samplers > sampler > expectRows > data> expectRow

Specifies the name of the row to be expected.

samplers > sampler > expectRowsInitialDelay

The initial delay specifies a time in seconds from when the sampler is first started, until the expect rows are applied. This is necessary for some samplers which must connect to an external data source before producing data (e.g. RMC plug-in). The value must be a positive integer (greater than 0).

Mandatory: No

Default: (no initial delay)

samplers > sampler > var-hideColumns

Specifies a list of dataview columns to hide.

Mandatory: No

samplers > sampler > var-hideRows

Specifies a list of dataview rows to hide.

Mandatory: No

Dataviews configuration settings

For more information on this section, see Dataviews.

To configure dataview settings the dataview must be referenced by name. To use this functionality, it is recommended that you configure and run a plug-in first, and then copy the name using the Active Console copy name command.

The configuration settings for dataviews are stored within the definition of the sampler that produces the configured dataview. The available settings are listed below.

samplers > sampler > dataviews

The dataviews setting within a sampler definition contains all the configuration settings to control the behaviour of dataviews produced by that sampler.

Mandatory: No

samplers > sampler > dataviews > dataview > name

Specifies the name of the dataview the contained configuration settings should apply to. This name is best obtained by first running the sampler, and copying the name of the views produced from within Active Console.

Mandatory: Yes

samplers > sampler > dataviews > dataview > description

Specifies a description of what the dataview displays. This would typically be used with the createOnGateway setting.

Mandatory: No

samplers > sampler > dataviews > dataview > displayName

Defines a name that is displayed by the Active Console in place of the default name of the data view. Other views such as Metrics view are not affected. This name is used for display purposes only - the original name of the data view must be used for all references to the data view (e.g. in rules).

Mandatory: No

Default: (original name of the data view)

samplers > sampler > dataviews > dataview > expectRows

The expectRows setting has been deprecated. Use the expectRowsVar setting instead.

This setting allows the configuration of expect rows for a dataview. For a more detailed description see Expect Rows.

Mandatory: No

samplers > sampler > dataviews > dataview > expectRowsVar

This setting allows the configuration of expect rows for a dataview. For a more detailed description see Expect Rows.

Mandatory: No

samplers > sampler > dataviews > dataview > firstColumn

This setting is used to add a contrived first column to the data view. The cells on the first column can be populated using a combination of existing columns and literals, as specified in this section.

Typically, the feature would be used to attempt create a first column with unique values (i.e. unique row names) in cases where the existing first column does not provide one.

E.g.:

A data view has a first column A, which has duplicate values. It is known that Column A + Column B would result in unique values. This feature can be then used to add a contrived first column C, and it can be specified that the column be populated by concatenating the corresponding cell values from Column A and Column B, with a separator "-" in-between for the sake of readability.

Mandatory: No

samplers > sampler > dataviews > dataview > firstColumncreate > columnName

The name (heading) of the added first column. See samplers > sampler > dataviews > dataview > firstColumn for more details.

Mandatory: Yes

samplers > sampler > dataviews > dataview > firstColumn > create > combineColumns > column

Specifies the name of an existing column, of which the cell values will be concatenated to populate the cells on the first column. See samplers > sampler > dataviews > dataview > firstColumn for more details.

samplers > sampler > dataviews > dataview > firstColumn > create > combineColumns > literal

Specifies a literal which will be used in place to populate the cells on the first column. This would typically be used to add a separator between cell values taken from existing columns, for the sake of readability. See samplers > sampler > dataviews > dataview > firstColumn for more details.

samplers > sampler > dataviews > dataview > expectRows > initialDelay

Mandatory: No

Default: (no initial delay)

samplers > sampler > dataviews > dataview > createOnGateway

This optional Boolean setting specifies whether the dataview matching this configuration should be created on the gateway (true), or whether the settings should be applied to a dataview published by netprobe (false). This setting is used to create a dataview for use by the Compute Engine of Gateway 2.

This setting is not intended to work with Expect Rows.

Mandatory: No

Default: false

samplers > sampler > dataviews > dataview > createOnGateway > enabled

This Boolean setting specifies whether the dataview matching this configuration should be created on the gateway (true), or whether the settings should be applied to a dataview published by netprobe (false).

Mandatory: Yes

Default: true

samplers > sampler > dataviews > dataview > createOnGateway > firstColumn

This is the name of the first column created in the dataview.

Mandatory: Yes

samplers > sampler > dataviews > dataview > var-group

Optional group setting. See Groups for more details.

Mandatory: No

Default: (no group)

samplers > sampler > dataviews > dataview > overviewType

The optional overview typesetting allows users to specify the name of the overview type for a dataview, which can help to produce better displays in Active Console when using the metrics overview feature.

Mandatory: No

Default: (plug-in name is used as type)

samplers > sampler > dataviews > dataview > additions

The additions setting allow the configuration of additional space in the dataview for extra data to be added. This feature is typically used in conjunction with the Compute Engine feature of Gateway 2.

Mandatory: No

samplers > sampler > dataviews > dataview > additions > var-headlines

Specifies a list of extra headline variables to be added to the dataview. Headlines which already exist will not be added.

Mandatory: No

samplers > sampler > dataviews > dataview > additions > var-columns

Specifies a list of extra columns to be added to the dataview. Columns which already exist will not be added.

Mandatory: No

samplers > sampler > dataviews > dataview > additions > var-rows

Specifies a list of extra rows to be added to the dataview. Rows which already exist will not be added.

Mandatory: No

samplers > sampler > activeTimes

This setting specifies a list of active times, during which the sampler should perform regular sampling.

Outside of these times regular sampling is disabled, but samplers > sampler > sampleTimes will still be processed. This can be helpful when monitored data is only valid during working hours, for example. Active times are referenced by name.

Note: Active times can be Netprobe controlled or Gateway controlled (if gatewayControlledProbeActiveTimes is set). In the latter case, one cannot use timezones or seconds precision in active times. For further details, refer to activeTimes > gatewayControlledProbeActiveTimes.

Mandatory: No

samplers > sampler > legacyParameters

Allows legacy sampler parameters to be specified. This setting is used to store additional sampler parameters. These parameters may arise because they have not been converted to the Gateway 2 setup file format yet, or during testing of a new plug-in where the setup format has not been finalised.

Parameters are specified as name-value pairs, and parameter names must be unique.

Mandatory: No

Sampler settings- Visibility tab

These settings are found in the Visibility tab.

samplers > sampler > isVisible

This setting controls whether the dataview is visible in Active Console, and only applies if the dataview is actually published.

Mandatory: No

Default: true

samplers > sampler > publish

Boolean setting controlling whether the sampler is published to Gateway by Netprobe.

A sampler that is not published doesl not present in Gateway or Active Console and cannot have rules set on it .

A value of false is typically used when the view is an input to Combo Plug-in - Technical Reference - the data contained in the non-published view is be published in the COMBO plug-in instead.

Mandatory: No

Default:

 true

samplers > sampler > hideColumns

Allows you to specify a list of dataview columns that are then "hidden" by Netprobe. These columns are not transmitted to Gateway for processing, and so cannot be used in rules.

You may use regular expressions to specify the columns. However, the expression must match the whole column name. For example, if you wanted to exclude all columns containing "time" you would need to use "^.*[Tt]ime.*" as your expression.

samplers > sampler > hideRows

Similar to hideColumns above, hideRows allows users to specify a list of dataview rows which are then hidden. Once again, these rows are not transmitted to Gateway, and so cannot be used in rules.

You may use regular expressions to specify the rows. However the expression must match the whole row name. So if you wanted to exclude all rows containing "time" you would need "^.*[Tt]ime.*" as your expression.