User Variables and Environments

Overview Copied

In many places in the setup file you can specify the value of a setting by referencing a variable instead of entering data directly.

Variables Copied

Variables are typically configured for settings in a sampler configuration. This allows the same sampler definition to be used in several places, and the behaviour of the sampler depends on the values of the variables when it is used.

Alternatively, the same variable can be referenced by many different samplers (e.g. the sample interval), allowing the user to control their behaviour by altering a single value.

Variables have scoping rules which define where they are valid and hold values. This means that although the GSE may suggest the name of a variable to use, the variable referenced may not be resolvable in a particular instance.

Gateway produces setup validation warnings for this occurrence, so you should check this output when making setup changes.

Environments Copied

If the same group of variables are used repeatedly in multiple places, then you may want to use an environment. An environment is a collection of variables, and is configured using the environments top-level section.

Each managed entity or type can reference a single environment. This makes the variables contained within the environment accessible by any samplers defined on that entity or type. When a type is added to a managed entity using an addTypes setting, an environment can also be specified for use by the samplers defined within the type.

It is also possible to nest environments to allow specialisations. Child environments inherit variables from their parent environment.

Operation Copied

Define Variables Copied

Variables can be defined in managed entities, managed entity groups, types, environments and operating environment.

A variable definition consists of the variable name and its value. The value can be one of several different types, including strings, integers, a list of items, an active time reference, amongst others.

Where possible, the variable type should fit the intended usage. For example, the sample interval setting takes integer values, so the variable here should be an integer type. Gateway attempts to substitute (for instance) a text value where an integer value is expected, but this does not work for all situations.

To define a new variable using the Gateway Setup Editor (GSE):

1. Navigate to the section you want to make a variable for.
2. Click on the Add new button for the var section.
3. Fill in the variable name and value.

Reference Variables Copied

To use the value of a variable, configure a setting using a variable name instead of a data value.

In the GSE, a setting that supports variables appears with a blue hyperlink stating either data or var.

Click on this text to switch between data and variable modes, and supply the data value or variable name respectively.

Some settings (typically text-valued settings) also support inline usage of variables, which allow the value of a variable to be inserted in the middle of user-supplied text (i.e. a mix of data and var values). To insert a variable reference, click on the var drop-down to the right of the setting and select a variable to use. See Inline variable storage.

Inline variable storage Copied

Inline variable usage allows a mix of user-supplied (text) data and variables.

Settings which support this will display a var dropdown menu to the right of the setting, which insert a reference to the selected variable.

In the example screenshot below, the process_user variable has been inserted into the path for a log file.

Variable Scoping and Resolution Copied

Variables have scoping rules which define where they are valid and hold values. This means that although the GSE may suggest the name of a variable to use, the variable referenced may not be resolvable in a particular instance.

For example, a sampler which references the variable myVar can be added to managed entities me1 and me2. If me1 defines a value for myVar but me2 does not, then the sampler on me2 will not be able to resolve this reference to a value, and uses an empty value instead.

When a variable reference is used in a sampler or sampler include, it is resolved by looking through the following locations in order until the variable can be found. If it is not found then an empty value is substituted (a gateway validation warning is also produced for this occurrence).

If the sampler or sampler include is referenced by a type:

• The environment specified when the type was added to that managed entity or managed entity group.
• Variables defined directly in the type.
• The environment referenced by the type.

If the sampler or sampler include is referenced in the managed entity or managed entity group, or was not found in the above:

• Variables defined in (or inherited by) the managed entity.
• The environment referenced by the managed entity.
• The operating environment.

For a sampler include, if the variable still cannot be resolved:

• This process is repeated, using the locations that would be searched when resolving variables for the host sampler configuration.

Inherited Variables Copied

Managed entities and environments inherit any variables defined in its ancestor sections in the Gateway setup.

For example, in the screenshot below, managed entity linux1 inherits the three variables shown, as they are defined in the managed entity group linux hosts which contains the linux1 definition.

Inherited variables can also be overridden (a new value given to the variable, replacing the inherited value) by re-defining the variable again with the new value. Additional variables can also be defined as normal.

The screenshot above shows the variables defined in the linux1 managed entity. As this entity is part of the linux hosts group, it inherits the three variables dbhost, dbport, and logdir.

The additional var entries define a new variable dbuser, and override the inherited logdir variable with a new value. This brings the total number of variables for this managed entity to 4 (3 inherited variables with 1 overridden, and 1 new variable).

Configuration Copied

environments > environmentGroup Copied

Environment groups are used to group sets of environments, to improve ease of setup management.

Mandatory: No

environments > environmentGroup > name Copied

Specifies the name of the environment group.

Although the name is not used internally by gateway, it is recommended to give the group a descriptive name so that users editing the setup file can easily determine the purpose of the group.

Mandatory: Yes

environments > environment Copied

Each configuration in this section is a named environment that can be accessed from other parts of the configuration.

An environment defines a set of variables that can be referred to by users of the environment.

Mandatory: Yes

environments > environment > name Copied

Specifies the name of the environment.

Although the name is not used internally by gateway, it is recommended to give the environment a descriptive name so that users editing the setup file can easily determine the class of variables in this environment.

Mandatory: Yes

environments > environment > var Copied

Each var element represents a named variable which can be accessed from its environment. There are several variable types available.

Mandatory: Yes

environments > environment > var > name Copied

The name that is used to identify the variable. The name must be unique within each variable scope.

Mandatory: Yes

environments > environment > var > activeTime Copied

Specifies a variable of type activeTime reference which refers to an active time in the system.

Mandatory: No

environments > environment > var > boolean Copied

Specifies a variable of type Boolean which can take a value of true or false.

Mandatory: No

environments > environment > var > double Copied

Specifies a variable of type double which can take a double precision floating point numerical value.

Mandatory: No

environments > environment > var > externalConfigFile Copied

Specifies a variable which can take the name of an external configuration file.

Mandatory: No

environments > environment > var > integer Copied

Specifies a variable which can take a numerical integer value.

Mandatory: No

environments > environment > var > nameValueList Copied

Specifies a variable which can take a list of name value pairs.

Mandatory: No

environments > environment > var > nameValueList > item Copied

Specifies a single name/value pair in the list.

Mandatory: No

environments > environment > var > nameValueList > item > name Copied

Specifies the name in a single name/value pair in the list.

Mandatory: No

environments > environment > var > nameValueList > item > value Copied

Specifies the value in a single name/value pair in the list.

Mandatory: No

environments > environment > var > regex Copied

Specifies a variable which can take a regular expression.

Mandatory: No

environments > environment > var > string Copied

Specifies a variable which can take a string.

Mandatory: No

environments > environment > var > stringList Copied

Specifies a variable which can take a list of strings. This can be used in various plugins to define lists of values. It can also be used it the inList() function in rules. (There is no where else in rules that stringLists should be used).

You can use a stringList variable in the following cases:

• realTimeCheckpoints > checkpoint > parents in Message Tracker configuration
• processParameters in Processes
• inList in Rules, Actions, and Alerts
• Adding to existing dataviews in Rules, Actions, and Alerts
• samplers > sampler > hideRows in Samplers
• samplers > sampler > hideColumns in Samplers
• Expect Rows in Samplers

Mandatory: No

environments > environment > var > stringList > string Copied

Specifies a single string in the string list.

Mandatory: No

environments > environment > var > macro Copied

Specifies a variable that takes the value from the gateway itself. The following macros are supported:

The values of macros that cannot be resolved because they are not applicable (e.g. the value of samplerName on a Managed entity) will return the name of the macro.

Mandatory: No