Dynamic Entities

Overview Copied

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

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.

Differences compared to Managed Entities Copied

Gateways organise data into entities. An entity represents an object being monitored, such as an application or a Kubernetes pod. Gateways format data into the following hierarchy:

• Entity
• Sampler
• Dataview
• Row

However, Collection Agent datapoints do not follow this hierarchy. A datapoint is composed of, and uniquely defined by, a set of dimensions and a metric name. Where a dimension is a key-value pair.

You can configure mappings to construct a Geneos hierarchy from datapoints. The resulting Dynamic Entities are then created in the Gateway. Geneos includes many built-in mappings but you can also create custom mappings to fit your data and workflow.

For each Dynamic Entity that is created, the set of all dimensions belonging to the Dynamic Entity and any attributes it has must be unique. This set of dimensions is referred to as the Dynamic Entity’s identifying dimensions.

For more information on the Collection Agent, see Introduction to Collection Agent.

Create Dynamic Entities Copied

To create new Dynamic Entities:

1. Install and configure a Collection Agent in the environment you want to monitor. For more information, see Collection Agent configuration reference.
2. Create one or more mappings and a mapping type that uses these mappings. For more information, see Dynamic Mapping configuration and Mapping type.
3. Install and configure a Netprobe to collect data from your Collection Agent and use the mapping type you created. For more information, see Collection Agent setup.

Custom mappings Copied

Custom mappings allow you to create bespoke mappings to fit your data and workflow. The parts of a custom mapping are Filters, Geneos items, and Default sampler name. For a detailed configuration for each mapping options, see Mapping options.

Mapping errors Copied

Dynamic mappings are read by the Netprobe, if a mapping is not compatible this results in an error.

Note the following:

• 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 !"'()[]^{|}`/*&.
• All cells in a dataview row must have the same dimensions. If a new datapoint is mapped to a row and it does not have the same dimensions as the other datapoints already mapped to that row, then that datapoint will be rejected by the Netprobe.
• If a mapping would map a new datapoint to an existing Dynamic Entity, but the identifying dimensions generated by the datapoint do not match the existing Dynamic Entity, then the datapoint is discarded and an Entity Dimension clash is recorded.

Single row pivoting Copied

Any mapping that does not map a label to a row would normally generate a dataview with only a single row, instead this data is pivoted. As a result, when you view this dataview in Active Console there are two columns, name and value, and each named datapoint is mapped to a row. If the data is forwarded to Gateway Hub or Kafka, then it is pivoted back to the original format.

Mapping and mapping group Copied

Dynamic mapping configuration Copied

Dynamic mapping group configuration Copied

Dynamic mapping groups allow a set of mappings to be grouped in a Gateway setup.

These groups can be used to provide a more structured view in the Gateway Setup Editor, but they can also be used to simplify the configuration of Dynamic Entities.

A mapping group allows you to set the Filters, Geneos items, Default sampler name, and Local Attributes that are inherited by child mappings. However, children that use built-in mappings only inherit Local Attributes.

To create a new dynamic mapping group:

1. Right-click on the Dynamic Entities > Mapping section in the Navigation tree and select the New Mapping group option. This creates a new mapping group section.
2. Name the mapping group.

Note

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

3. Configure the Filters, Geneos items, Default sample name, and Local Attributes of the mapping groups you have created. For detailed configuration information, see Mapping options.

New mappings can be created in the group using the New Mapping button. Existing mappings can also be added or removed from the group using drag-and-drop in the Navigation tree.

Child groups can be added by right-clicking on a mapping group in the Navigation tree and selecting the New Mapping group option.

Mapping groups can also be added and removed using drag-and drop in the Navigation tree.

Mapping options Copied

Filter Copied

This section allows you to filter which datapoints this mapping applies to based by specifying criteria their labels must meet.

You can apply one or more filters that apply simultaneously.

Note

If a mapping group and a mapping or a nested mapping group contain a filter for the same label, both will be applied.

Geneos items Copied

This section allows you to define how items in the Geneos tree structure are generated from the labels of a datapoint.

When mapping Geneos items, note the following:

• Mapping items, excluding attributes, stack so that each label is appended to the item name in the order listed here. If a mapping exists but the label is missing or empty, then it will not be added to the item name.

  For example, if both Kubernetes namespace and Kubernetes pod name are mapped to Managed Entity and the namespace label is listed first, then the Managed Entity name will be <namespace>-<pod_name>. If the Kubernetes namespace label does not exist, the Managed Entity name will be <pod_name>.

• The dataview name is divided into two parts. The first part is defined by the mappings you provide, and the second part is generated from the dimensions of the datapoint. This ensures that each dataview row has a unique set of dimensions.

Note

Mapping items defined at the mapping group level will stack before items defined in nested mapping groups or in mappings and any duplicate items are not removed.

Default sampler name Copied

When a sampler’s dimensions match its containing managed entity, this value determines the sampler’s name.

If not set, then the sampler will be given the same name as the managed entity if it has the same dimensions as the managed entity.

If the dataview rows have extra dimensions, then the names of those dimensions will be appended using the by X and Y format.

Note

The default sampler name defined in nested groups or in mappings will override a default sampler name defined in their parent mapping groups.

Local attributes Copied

Define zero or more attributes that are applied to every Dynamic Entity created by the mapping.

Available for both Built In and Custom mappings. The attribute values are strings that can include embedded variables. The variables are fetched from the environment specified in the dynamic mapping type.

Mandatory: No

Note

Local attributes defined in nested groups or in mappings will override local attributes defined in their parent mapping groups.

Mapping type Copied

Netprobes process Collection Agent data using a specified Mapping type and create or remove Dynamic Entities accordingly. Mapping types allow 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, and every datapoint received is checked against each mapping in the order. Data is then mapped according to the first match made.

Add a Mapping type to a Netprobe Copied

To add a Mapping type:

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

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 Copied

Collection Agent parameters Copied

Beginning Geneos 6.0.0, the Collection Agent parameters are now configured under the Dynamic Entities section in the GSE. You may now also configure the parameters from the Collection Agent configuration file in the Gateway Setup Editor if you will use a managed YAML for your Collection Agent.

Collection Agent parameters configuration Copied

Managed Collection Agent Copied

Collectors Copied

Beginning Geneos 6.0.0, you may add or edit a collector for your managed Collection Agent without the need to manually stop and restart your Collection Agent instance.

Note

Collectors can only be added if the Collection Agent is managed and the YAML setting is managedYAML.

When adding or editing a collector, the Netprobe will automatically restart the Collection Agent instance.

Basic configuration Copied

Advanced configuration Copied

Dynamic Entities commands Copied

Show Dynamic Mappings Copied

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.

The possible targets of this command are:

• Cells in a dynamically generated dataview that is not from an FKM or a State Tracker sampler.
• Cells in the InvalidStreams dataview created by the Dynamic Entities Health plugin.

Datapoint information Copied

The mapping matched to the datapoint and applied is indicated.

Geneos Structure Copied

Forget Dynamic Entity Copied

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.

The possible targets of this command are:

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

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.

View Log Copied

The View Log command is also available when you right-click the following in the State Tree:

• Netprobes with configured Dynamic Entities
• Dynamic Managed Entities
• Dynamic Entity Health samplers

This command shows the logs of the corresponding Collection Agent of the selected cell. When you right-click on any cell except for the probeName, and select theCollection Agent > View Log… option, a dialog box will open to specify options on how you want to view the logs. The following parameters can be set:

• Initial Download size(kb) — sets the initial download size of the log file. This defaults to 2 kb.
• Delivery Type — allows you to choose between Snapshot and Continuous delivery type. The snapshot delivery type displays the contents of the log file at the time it was generated, while continuous delivery type displays logs continuously in real-time.
• Filter String — allows you to specify strings that will filter the Collection Agent log file.

Sample Output (Snapshot delivery type) Copied

View Configuration Copied

The View Configuration command is also available when you right-click the following in the State Tree:

• Netprobes with configured Dynamic Entities
• Dynamic Managed Entities
• Dynamic Entity Health samplers

When you right-click on any cell except for the probeName, and select theCollection Agent > View Configuration option, a new window displaying the configuration of the corresponding Collection Agent will open.

Sample Output Copied

View Error Copied

When you right-click on a cell in the status column and select the Collection Agent > View Error option, a new window displays more information.

Sample Output Copied

Appendix: Using regex Copied

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