If you are currently using version 5.x.x, we advise you to upgrade to the latest version before the EOL date. You can find the latest documentation here.
User Variables and Environments
Overview
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
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
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
Define Variables
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):
- Navigate to the section you want to make a variable for.
- Click on the Add new button for
the
var
section. - Fill in the variable name and value.
Reference Variables
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
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
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
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
environments > environmentGroup
Environment groups are used to group sets of environments, to improve ease of setup management.
environments > environmentGroup > name
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.
environments > environment
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.
environments > environment > name
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.
environments > environment > var
Each var element represents a named variable which can be accessed from its environment. There are several variable types available.
environments > environment > var > name
The name that is used to identify the variable. The name must be unique within each variable scope.
environments > environment > var > activeTime
Specifies a variable of type activeTime reference which refers to an active time in the system.
environments > environment > var > boolean
Specifies a variable of type Boolean which can take a value of true or false.
environments > environment > var > double
Specifies a variable of type double which can take a double precision floating point numerical value.
environments > environment > var > externalConfigFile
Specifies a variable which can take the name of an external configuration file.
environments > environment > var > integer
Specifies a variable which can take a numerical integer value.
environments > environment > var > nameValueList
Specifies a variable which can take a list of name value pairs.
environments > environment > var > nameValueList > item
Specifies a single name/value pair in the list.
environments > environment > var > nameValueList > item > name
Specifies the name in a single name/value pair in the list.
environments > environment > var > nameValueList > item > value
Specifies the value in a single name/value pair in the list.
environments > environment > var > regex
Specifies a variable which can take a regular expression.
environments > environment > var > string
Specifies a variable which can take a string.
environments > environment > var > stringList
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:
environments > environment > var > stringList > string
Specifies a single string in the string list.
environments > environment > var > macro
Specifies a variable that takes the value from the gateway itself. The following macros are supported:
gatewayName | The name of the gateway |
gatewayPort | [deprecated] The port number on which the gateway is listening (secure port if gateway is listening on two ports) |
secureGatewayPort | The port number on which the gateway is listening for secure connections |
insecureGatewayPort | The port number on which the gateway is listening for insecure connections |
managedEntityName | The name of the managed entity |
netprobeHost | The host name of the netprobe |
netprobeName | The name of the netprobe |
netprobePort | The port number on which the netprobe is listening |
samplerName | The name of the sampler |
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.