Dynamic Entities

Overview

Dynamic Entities can be created automatically based on metric datapoints provided by a Collection Agent. This allows you to monitor applications with transient lifetimes.

You must provide a Dynamic mapping to specify how Dynamic Entities and samplers are constructed from the Collection Agent datapoints.

This type of monitoring is especially useful in an orchestrated environment, such as Kubernetes, where applications and instances can be created and removed dynamically. A mapping template is provided for Kubernetes and OpenShift environments. See, Mapping templates in Monitoring strategy.

For more information on the Collection Agent, see Collection Agent in Netprobe Overview.

Dynamic Mappings

Create a Dynamic mapping

To create a new Dynamic mapping:

Right-click the Dynamic Entities top-level section and select the New Dynamic mapping option.
In the Name box, give the new Dynamic mapping a unique name. This name is used to refer to the mapping in other parts of the Gateway Setup Editor. Names are case-sensitive.
Specify a Match criteria to determine when the mapping is applied. You can specify a match by applying a regex pattern to Metric names or to the value of a specified dimension.
Where multiple Match criteria are provided, incoming datapoints will be checked against each in the order specified.
Specify the Entity mapping to determine how each Dynamic Entities is constructed. A new entity is created for each unique permutation of the options specified. The name of each Entity is given as a compound of the value of each option.
Specify the Sampler mapping to determine how the samplers of each entity are constructed. A sampler is created for each unique permutation of the options specified. The name of each sampler is given as a compound of the value of each option.
Specify the Dataview mapping to determine how the dataviews of each sampler are constructed. A dataview is created for each unique permutation of the options specified. The name of each dataview is given as a compound of the value of each option.
Specify the Row mapping to determine how the rows of each dataview are constructed. A row is created for each unique permutation of the options specified. The name of each row is given as a compound of the value of each option.
(Optional) Specify the Attribute Mappings that determine the attributes of each entity. You can add multiple Attributes and configure each by specifying the Directory mapping.
Click Validate.
Click Save.

Note: You can use variables in any static option.

Caution: The names of objects, such as entities or rows, created by a dynamic mapping are determined by the value of the options specified in the mapping. Netprobe accepts names containing any ASCII characters except for !"'()[]^{|}`/*&.

Use the label builder

The label builder creates additional dimensions and properties that can be used in mappings. Labels can be created from existing labels or metric names. You must specify the values the label will take given the value of existing parameters, you can do this manually or by specifying a regex pattern.

Choice

To configure a label manually specify the following options:

Option	Description
Name	Name of the label.
Source	The source data. Choose from `Metric name` or `Label`. If using a Label, then you must specify a label name.
Choices	List of Prefix and Value pairs. The value of the label is determined by the Value of the matched Prefix.
Dimension	Specifies if the label should be treated as a dimension. If this option is enabled, then the Source must be a dimension.
Fallback	Default value of the label if no match is found.

Regex

To configure a label using a regex pattern, specify the following options:

Option	Description
Name	Name of the label.
Source	The source data. Choose from `Metric name` or `Label`. If using a Label, then you must specify a label name.
Pattern	Regex pattern used to determine the value of the label.
Group	Regex capturing group used to determine the value of the label.
Dimension	Specifies if the label should be treated as a dimension. If this option is enabled, then the Source must be a dimension.
Fallback	Default value of the label if no match is found.

Dynamic Mapping configuration

Basic tab

Dynamic entities > Mapping > Name

A name for the Dynamic mapping. This name must be unique to avoid ambiguity when using the name in other parts of the Gateway setup. This name is case-sensitive.

Mandatory: Yes

Dynamic entities > Mapping > Match criteria

A regex match criteria to determine when the mapping is applied. The match can be performed on metric names and the value of specified dimensions. All match criteria must be matched for the mapping to be applied.

Mandatory: No

Dynamic entities > Mapping > Entity mapping

Defines the mapping used to create entities. An entity will be created for each unique combination of the options specified here.

The names of each entity are determined by the ordering of the options list.

In some situations this may result in very long names to ensure uniqueness. You may wish to use a shorter display name, to do this use the Dynamic entities > Mapping > Entity display name mapping option in the advanced tab.

Caution: By default names of the form <gateway_name> Info are reserved for Gateway self monitoring. A Gateway setup containing a Netprobe or Managed Entity with this name will fail validation. Self-Announcing Netprobes and Dynamic Entities cannot use this name. For more information, see operatingEnvironment > selfMonitoring in Operating Environment.

Mandatory: No

Dynamic entities > Mapping > Sampler mapping

Defines the mapping used to create samplers. A sampler will be created for each unique combination of the options specified here.

The names of each sampler are determined by the ordering of the options list.

Mandatory: No

Dynamic entities > Mapping > Dataview mapping

Defines the mapping used to create dataviews. A dataview will be created for each unique combination of the options specified here.

The names of each dataview are determined by the ordering of the options list.

Mandatory: No

Dynamic entities > Mapping > Row mapping

Defines the mapping used to create rows. A row will be created for each unique combination of the options specified here.

The names of each row are determined by the ordering of the options list.

Mandatory: No

Dynamic entities > Mapping > Stream mapping

Defines the mapping used to generate streams. A stream will be created for each unique combination of the options specified here, the Dynamic Entity name, and the log metric name.

Stream names are separated with periods.

If no stream mapping is provided, then all matching events will be published to a <DynamicEntityName>.<MetricName> stream, where <DynamicEntityName> is determined by the entity mapping and <MetricName> is the name of the log metric.

Mandatory: No

Dynamic entities > Mapping > Attribute mappings

Defines the attributes of the entities created using a mapping. The value of each attribute is determined by the ordering of the directory mappings list. You can also specify a default value.

Mandatory: No

Advanced tab

Dynamic entities > Mapping > Entity display name mapping

Defines the GeneosDisplayName attribute of created entities. The value of the attribute is determined by the options specified here.

The GeneosDisplayName attribute is used to identify the entity in the Active Console state tree and everywhere the display name is used. However, the name and path of each entity is still determined by the entity mapping.

Mandatory: No

Dynamic entities > Mapping > Sampler group mapping

Defines the mapping used to create sampler groups in the Active Console UI. A group will be created for each unique combination of the options specified here.

The names of each group are determined by the ordering of the options list.

Mandatory: No

Dynamic entities > Mapping > Label builders

Defines the available labels. The label builder allows you to create new dimensions and properties from those provided by the datapoint.

You can specify the values taken by a label using a regex pattern or by manual choice.

Mandatory: No

Mapping type

You can use Mapping types to create logical groupings of mappings. This allows you to easily deploy the same configuration on multiple probes. This is useful when managing large estates.

A Mapping type provides an ordered list of mappings, each datapoint received will be checked against each mapping in the order. Data will be mapped according to the first match made.

Dynamic Entities are created and removed based on Netprobe data. You must specify which mappings each Netprobe should use by applying a Mapping type.

Add a Mapping type to a Netprobe

To add a Mapping type:

Expand the Probes top-level section and select a probe.
Open the Dynamic Entities tab.
In the Dynamic entities section, select a Mapping type from the drop-down list.
Click Validate.
Click Save.

Note: You can also apply Mapping types to probe groups. Probes will inherit the Mapping types specified in their parent group, unless one is specified explicitly on an individual probe. A Mapping type specified on a probe overrides a Mapping type specified on a probe group. For more information, see probes > probeGroup in Probes.

Mapping type configuration

Dynamic entities > Mapping type > Name

A name for the Mapping type. This name must be unique to avoid ambiguity when using the name in other parts of the Gateway setup. This name is case-sensitive.

Mandatory: Yes

Dynamic entities > Mapping type > Mappings

Specifies the mappings used to create dynamic entities. The Gateway will attempt to find matches using each mapping sequentially in the specified order.

Mandatory: No

Dynamic entities > Mapping type > Samplers

Specifies which additional samplers should be created for each Dynamic Entity.

Caution: You can use only the FKM and State Tracker plugins with Dynamic Entities. Attempting to specify a sampler using a different plugin will result in an error.

Mandatory: No

Dynamic entities > Mapping type > Environment

Specifies the environment used by Dynamic Entities created by using this type.

For more information, see User Variables and Environments.

Mandatory: No

Dynamic entities > Mapping type > Entity timeout

Specifies the duration an entity must be unresponsive before it is removed from the Gateway.

Mandatory: No

Unit: seconds

Dynamic Entities commands

Show Dynamic Mappings

You can run this command in the Active Console to display the Dynamic Mapping that produced a target Cell.

The value of a Dynamic Entity dataview cell is determined by the value of a datapoint. The command shows each datapoint label and the mapping used to generate the target cell.

Datapoint information

Column Description

Label Name of the datapoint label.

Value Value of the datapoint label.

Type

Column	Description
Label	Name of the datapoint label.
Value	Value of the datapoint label.
Type	Type of the label. The options are: `Dimension` `Dimension (Built)` `Property` `Property (Built)` Labels created using the label builder are indicated with a `(Built)` tag.

Type of the label.

The options are:

Dimension
Dimension (Built)
Property
Property (Built)

Labels created using the label builder are indicated with a (Built) tag.

The mapping matched to the datapoint and applied is indicated.

Column	Description
Mapping Name	Name of the Dynamic Mapping.
Match Result	Match status. A matched mapping is applied to the incoming datapoint.

Geneos Structure

Column	Description
Geneos structure	Object in the Geneos hierarchy.
Value	Shows the full string of the object name and the mapping that produced each element of the name.

The possible targets of this command are:

Cells in a Dynamic Entity dataview.
Cells in the InvalidMetrics dataview created by the Dynamic Entities Health plugin.

Forget Dynamic Entity

You can run this command to remove a Dynamic Entity from Geneos and all associated dataviews from the Active Console.

Dynamic Entities are automatically removed after a timeout period if no new data has been received. This timeout period is determined by the earliest of the Entity timeout and the stale-metrics-threshold in the Collection Agent StatsD plugin configuration file.

This command allows you to remove an entity you have stopped monitoring but still appears in the Active Console since the timeout has not expired. This is common during testing or when reconfiguring production environments.

Note: If you run this command on an entity that is still being monitored, Geneos will recreate the dynamic entity when the next datapoint is received. As a result the command may appear to have no effect.

The possible targets of this command are:

Dynamic Entities in the State Tree.
Cells in the Entities dataview created by the Dynamic Entities Health plugin.

Appendix: Using regex

Mappings and labels can be created using regular expression (regex) patterns. The following are common patterns that may be useful when creating mappings:

Pattern	Description
`^$`	No matches.
`.+`	Matches any value. Requires that a value is present.
`^A1$`	Matches only `A1` exactly.
`A1`	Matches any value that contains `A1`.