Samplers

Overview Copied

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 Copied

Basic configuration Copied

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:

  1. Select the Samplers top-level section. If this section does not exist, double-click to create it.
  2. Select the New sampler button to create a new sampler definition.
  3. 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.
  4. By default samplers will collect data (sample) every 20 seconds. You can optionally change that value here using the sampleInterval setting.
  5. 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.
  6. 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 Copied

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:

  1. Right-click on the Samplers top-level section and select the New samplerGroup menu option. This creates a new group section.
  2. 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.
  3. 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.
  4. 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 Copied

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;

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. For more information, see environments > environment > var > stringList in User Variables and Environments.

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 Copied

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 Copied

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 Copied

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 Copied

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 Copied

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

samplers Copied

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

samplers > samplerGroup Copied

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 Copied

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 Copied

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 Copied

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

samplers > sampler > name Copied

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 Copied

Optionally specifies a group name.

Mandatory: No

Default: (no group)

samplers > sampler > description Copied

Optionally specifies a description.

Mandatory: No

Default: (no description)

samplers > sampler > sampleInterval Copied

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 Copied

Optionally specifies a plugin to be associated with this sampler.

Mandatory: No

Sampler settings- Advanced tab Copied

These settings are found in the Advanced tab.

samplers > sampler > displayName Copied

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 Copied

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 when sampleInterval is set to 0.

Mandatory: No

Default: true

samplers > sampler > sampleTimesOverride Copied

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 Copied

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 Copied

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 Copied

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 Copied

Specifies the file to monitor for a file trigger.

Mandatory: Yes (if using a file trigger)

samplers > sampler > fileTrigger > maxPerMinute Copied

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 Copied

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 Copied

Specifies the name of the row to be expected.

samplers > sampler > expectRowsInitialDelay Copied

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 Copied

Specifies a list of dataview columns to hide.

Mandatory: No

samplers > sampler > var-hideRows Copied

Specifies a list of dataview rows to hide.

Mandatory: No

Dataviews configuration settings Copied

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 Copied

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 Copied

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 Copied

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

Mandatory: No

samplers > sampler > dataviews > dataview > displayName Copied

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 Copied

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 Copied

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 Copied

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. The values of this column are passed as the new row names.

Typically, this 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.

For example, if 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 then be 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.

Commands that use the row name often depend on the original row names. Using the firstColumn option may prevent these commands from behaving correctly. The commands provided by the following plugins may break when using this feature:

Mandatory: No

samplers > sampler > dataviews > dataview > firstColumncreate > columnName Copied

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 Copied

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 Copied

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 Copied

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 > dataviews > dataview > createOnGateway Copied

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 Copied

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 Copied

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

Mandatory: Yes

samplers > sampler > dataviews > dataview > var-group Copied

Optional group setting.

Mandatory: No

Default: (no group)

samplers > sampler > dataviews > dataview > overviewType Copied

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 Copied

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 Copied

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 Copied

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 Copied

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 Copied

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 Copied

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

These settings are found in the Debug tab.

samplers > sampler > debug > debug > setting Copied

Specify any debug settings.

Sampler settings - Publishing tab Copied

These settings are found in the Publishing tab.

samplers > sampler > publishing > schemas > dataviews > dataview Copied

Specifies the name of the dataview that the data schema applies to. If omitted, the schema applies to the dataview that has the same name as the sampler (the default dataview).

samplers > sampler > publishing > schemas > dataviews > schema Copied

Specify a data schema. For more information about data schema, see Data Schema User Guide.

This field has two options:

Standardised formatting configuration Copied

samplers > sampler > publishing > standardisedFormatting Copied

See Standardised formatting in Publish to Kafka.

samplers > sampler > publishing > standardisedFormatting > dataviews > dataview Copied

Provides a list of standardised formatting variables to apply to one or more dataviews in the sampler. When the name of the dataview is set the variable definitions are restricted to the named dataview. If the name is left unset the variable definitions applies to all dataviews belonging to the sampler.

Mandatory: No

Default: Not set

samplers > sampler > publishing > standardisedFormatting > dataviews > dataview > Name Copied

Name of the variable.

samplers > sampler > publishing > standardisedFormatting > dataviews > dataview > variables > variable Copied

Variable definition specifying type and applicability of variable.

samplers > sampler > publishing > standardisedFormatting > dataviews > dataview > variables > variable > type Copied

Specifies the type of the variable. Currently on dateTime is supported.

samplers > sampler > publishing > standardisedFormatting > dataviews > dataview > variables > variable > type > dateTime Copied

Specifies that the variable is a date-time (includes dates and times which are assumed to be for the current day).

samplers > sampler > publishing > standardisedFormatting > dataviews > dataview > variables > variable > type > dateTime > formats > format Copied

Specifies the expected format of the data. See the following section for a description of the time parsing codes. There can be several of these to accommodate that different servers may generate dates in differing formats.

Mandatory: Yes

samplers > sampler > publishing > standardisedFormatting > dataviews > dataview > variables > variable > type > dateTime > exceptions > exception Copied

Specifies exceptions to Standardised Formatting. If the text specified here matches the value of a published cell, no formatting is applied and no error is logged. This is for instances where dataviews have invalid values such as a blank string ("") or “N/A” as a date.

For data published via Publishing using Kafka, the data is published unchanged.

For data published to Gateway Hub, any exceptions are published as “N/A”. This allows the Gateway Hub to recognise and process the data.

Mandatory: No

samplers > sampler > publishing > standardisedFormatting > dataviews > dataview > variables > variable > type > dateTime > ignoreErrorsIfFormatsFail Copied

If set to true and the none of the formats can translate the data then the errors generated are suppressed. This can be used to specify a NULL format that overrides a system provided one with no formatting. This can be useful for example if you don’t care about formatting these and the output is in an unexpected format due to locale.

Mandatory: No

Default: false

samplers > sampler > publishing > standardisedFormatting > dataviews > dataview > variables > variable > type > dateTime > overrideTimezone Copied

The default timezone date is that of the dataview. i.e. if the Probe has a timezone set the date would be interpreted from that timezone. If not the timezone will match the Gateway’s timezone. This setting allows you to explicitly set the timezone from which the data is being received.

Mandatory: No

samplers > sampler > publishing > standardisedFormatting > dataviews > dataview > variables > variable > applicability Copied

Allows matching of formats to dataview variables.

samplers > sampler > publishing > standardisedFormatting > dataviews > dataview > variables > variable > applicability > headlines Copied

Allows you to match variables to headline variables.

samplers > sampler > publishing > standardisedFormatting > dataviews > dataview > variables > variable > applicability > headlines > regex Copied

A regular expression to match against the headline names.

All values within the matching headlines will have the formatter applied for publishing.

Mandatory: No

Expression Effect
date Matches all headlines containing date.
date$ Matches all headlines ending in date$.
^date$ Matches the healdine date.

samplers > sampler > publishing > standardisedFormatting > dataviews > dataview > variables > variable > applicability > columns > regex Copied

A regular expression to match against the column names.

All values within the matching columns will have the formatter applied for publishing.

Mandatory: No

Expression Effect
date matches all columns containing date
date$ matches all columns ending in date$
^date$ matches the column date

samplers > sampler > publishing > standardisedFormatting > dataviews > dataview > variables > variable > applicability > cells Copied

Maps to a specific row and column. These mappings are good for dataviews made from name, value pairs and take priority on lookup over column regular expressions. As these are specific the row and columns are not regular expressions.

Mandatory: No

Sampler settings - Visibility tab Copied

These settings are found in the Visibility tab.

samplers > sampler > isVisible Copied

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

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 Copied

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.

["Geneos"] ["Geneos > Gateway"] ["Technical Reference"]

Was this topic helpful?