Managed Entities and Managed Entity Groups

Overview

A managed entity is a logical grouping of samplers on a probe, typically used to group monitoring data from a particular system or area of functionality.

Managed Entities are configured in the Managed entities top-level section of the Gateway setup. Configuration consists of a set of managed entity definitions, each of which contains the configuration for that entity. Each managed entity must be named using a name unique among all other managed entities, so that they can be referenced by this name.

Operation

The minimum configuration for a managed entity consists of the probe that the entity runs on, and a list of samplers. The probe and samplers are specified by referencing the probe or sampler definition by name. An error is raised if you specify a probe that does not exist.

Multiple samplers can be specified in the sampler list, but specifying the same sampler multiple times in a managed entity definition generates a warning. This is because using the same sampler has the same configuration and is therefore monitoring the same systems - it is unnecessary to monitor the same system repeatedly.

How to create and configure a new managed entity

These steps assume that a probe and sampler definition exist to reference in the managed entity. See Probes or Samplers Operation sections for more details on how to do this.

To create a new managed entity using the Gateway Setup Editor, follow the steps below:

  1. Select the Managed entities top-level section. If this section does not exist, double-click to create it.
  2. Select the New Managed entity button to create a new entity definition.
  3. In the Name box, give the new managed entity a unique name. This name is used to refer to the managed entity in other parts of the Gateway. Names are case sensitive.
  4. In Options, specify the type of probe that this entity is hosted on using the drop-down list. There are three options:
    • Probe
    • Floating Probe
    • Virtual Probe
    1. Specify the name of the probe using the drop-down list next to your selected probe type.
    2. To add a sampler, click Add new in the Sampler section.
    3. Select the sampler using the drop-down list.

    Once these steps have been completed, a new managed entity will have been configured on a probe, with zero or more samplers.

    This managed entity now appears in the Active Console 2, and can be examined for monitoring data provided the specified Netprobe is running.

    Types

    It is often useful to use the same list of samplers across several managed entities. This can be done by using a type (see Types). Types are referenced in a managed entity definition in a similar way to probes and samplers. A warning is generated if the same type is referenced multiple times.

    Types can be added to an entity using the Add types setting. When types are added, they can contain an additional reference to an environment (see User Variables and Environments). Samplers referenced from these types resolve variables by looking in the specified environment first.

    Types inherited from a containing managed entity group can be removed using Remove types setting. The Remove types setting is processed before the Add types setting, so it is possible to remove a type and then add it back again using a different environment.

    Attributes

    Managed entities can optionally contain a number of user configured name-value pairs called attributes. These attributes can be used for naming or grouping managed entities for use by other Gateway features. They can also be used by Active Console 2 for searching and sorting purposes. Attributes are typically used with the logical mode of the ActiveConsole 2 state tree.

    Attributes are configured as a list of values similar to the list of samplers. Attributes are inherited from a containing managed entity group, and can be overridden by specifying a new attribute value in the managed entity definition. It is a checked error to configure multiple attributes with the same name in a single managed entity definition.

    Example above shows managed entities configured with attributes. On the left is the navigation tree from Gateway Setup Editor, showing the attributes configured on the managed entity groups. On the right is an Active Console 2 state tree, configured in logical mode using the view path "Country, City".

    Configuration

    Navigation pane

    The following sections are available from the Gateway Setup Editor navigation tree, after the appropriate definition has been created.

    managedEntities

    The managed entities top-level section contains the configuration details of all the managed entities the gateway configures and monitors. This section can contain a number of entities and groups.

    managedEntities > managedEntityGroup

    A managed entity group allows grouping of managed entity definitions for ease of management.

    Groups can contain managed entities and other groups. Contained items inherit any types or attributes specified in the group, which allows an entity to be quickly configured by being placed within the appropriate group.

    managedEntities > managedEntity

    Contains the definition for a single managed entity. Each entity must have a unique name among all other managed entity definitions in this section.

    Basic tab

    These settings are found in the Basic tab.

    managedEntities > managedEntity > name

    Specifies the name for the managed entity. This name must be unique among all other configured entities, to avoid ambiguity when using the name in other parts of the gateway setup (e.g. rules). The managed entity name is case sensitive.

    Mandatory: Yes

    managedEntities > managedEntity > probe

    A named reference to the probe definition. The managed entity will then be hosted on the Netprobe specified by this definition. It is a checked error to specify an invalid probe definition name.

    Mandatory: Yes

    managedEntities > managedEntity > attribute

    A managed entity definition can contain any number of attributes. Each attribute is specified as a name-value pair containing a textual value (the attribute value). These attributes can then be used for searching and sorting in ActiveConsole 2. See Attributes.

    Mandatory: No

    managedEntities > managedEntity > addTypes

    The add types setting allows Types to be added to a managed entity. Types are referenced by name, and can be linked to an optional environment. See User Variables and Environments.

    Mandatory: No

    managedEntities > managedEntity > addTypes > type > environment

    The environment setting allows an optional environment to be linked to a type reference, within a particular managed entity definition. Samplers defined in the type will then use this environment to resolve any variables in the configuration. See Types.

    Mandatory: No

    managedEntities > managedEntity > sampler

    A managed entity definition can contain any number of sampler references, which are run on the host Netprobe for this entity.

    Each sampler is referenced by name from Samplers top level section. An error message is produced if samplers are referenced multiple times in the same entity definition.

    Mandatory: No

    managedEntities > managedEntity > sampler> disabled

    Disables the referenced sampler.

    Mandatory: No

    Advanced tab

    These settings are found in the Advanced tab.

    managedEntities > managedEntity > group

    Optionally specifies a group name. See Gateway Installation Guide for more details.

    Mandatory: No
    Default: (no group)

    managedEntities > managedEntity > description

    Optionally specifies a description. See Gateway Installation Guide for more details.

    Mandatory: No
    Default: (no description)

    managedEntities > managedEntity > displayName

    Defines a name that is displayed by the Active Console in place of the actual name of the managed entity 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 managed entity must be used for all references to the data view (e.g. in rules).

    Mandatory: No
    Default: (original name of the managed entity)

    managedEntities > managedEntity > environment

    An optional named reference to an environment. See User Variables and Environments used for resolving variables in the sampler configuration for this entity.

    Mandatory: No

    managedEntities > managedEntity > removeTypes

    The remove types setting allows the removal of inherited types from a managed entity definition. Types to be removed are listed (referenced) by name in this setting. Remove types are processed after inheritance, but before managedEntities > managedEntity > addTypes to allow "overriding" of an inherited type.

    See Types.

    Mandatory: No

    managedEntities > managedEntity > removeSamplers

    The remove samplers setting allows the removal of samplers from inherited types from a managed entity definition. Samplers to be removed are listed (referenced) by name and the type they belong to in this setting.

    Mandatory: No

    managedEntities > managedEntity > var

    Any number of variable definitions, configured with a name and value similar to Attributes. Managed entity variables override the entity environment if specified. Variables are used when resolving sampler configurations which contain variables. See User Variables and Environments.

    Mandatory: No

    managedEntities > managedEntity > var> name

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

    Mandatory: Yes

    managedEntities > managedEntity > var> ipAddress

    Sets the IP address where the variable is connected.

    Note: You cannot pass the IP address as variable into a host. It does not allow IP address to be used in names.

    Mandatory: No

    managedEntities > managedEntity > var> activeTime

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

    Mandatory: No

    managedEntities > managedEntity > var> boolean

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

    Mandatory: No

    managedEntities > managedEntity > var> double

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

    Mandatory: No

    managedEntities > managedEntity > var> externalConfigFile

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

    Mandatory: No

    managedEntities > managedEntity > var> integer

    Specifies a variable which can take a numerical integer value.

    Mandatory: No

    managedEntities > managedEntity > var> nameValueList

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

    Mandatory: No

    managedEntities > managedEntity > var> nameValueList > item

    Specifies a single name/value pair in the list.

    Mandatory: No

    managedEntities > managedEntity > var> nameValueList > item > name

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

    Mandatory: No

    managedEntities > managedEntity > var> nameValueList > item > value

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

    Mandatory: No

    managedEntities > managedEntity > var> regex

    Specifies a variable which can take a regular expression.

    Mandatory: No

    managedEntities > managedEntity > var> string

    Specifies a variable which can take a string.

    Mandatory: No

    managedEntities > managedEntity > var> stringList

    Specifies a variable which can take a list of strings.

    Mandatory: No

    managedEntities > managedEntity > var> stringList > string

    Specifies a single string in the string list.

    Mandatory: No

    managedEntities > managedEntity > var> macro

    Specifies a variable that takes the value from the gateway itself. The macros supported are listed in User Variables and Environments

    managedEntities > managedEntity > samplerInclude

    A managed entity definition can contain any number of samplerInclude references. This references a samplerInclude configuration section which will be applied to this Managed Entity.

    SamplerInclude sections define parts of sampler configuration that will be combined into a sampler.

    For example a list of processes that will be added to an instance of a processes sampler.

    Mandatory: No

    managedEntities > managedEntity > banner

    An optional name specifying the data-item to display as the representative value for this managed entity (see Banner variables).

    Names can be specified either as an absolute name, or a relative name starting from the managed entity level.

    Mandatory: No
    Default: None

    Managed Entity Groups

    Overview

    Managed entity groups allow a set of managed entities to be grouped in the Gateway setup.

    These groupings 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 managed entities.

    As stated above, a managed entity group can contain definitions for types and attributes. These are then inherited by any child groups or entity definitions. Types can be removed by using the Remove types setting in a group or entity definition, and attributes can be overridden by specifying a new value.

    Operation

    How to create a new managed entity group

    To create a managed entity group:

    1. Right-click on the Managed entities top-level section and select the New Managed entity group option. This creates a new group section.
    2. Name the managed entity group. This can be a descriptive name e.g. "PATS systems".
    3. (Optional) Add or remove types to the group.
    4. Configure attributes for the group in the Attribute section.
    5. Add managed entities for the group.
    6. New managed entities can be created in the group using the New Managed entity button.
      • Entities can also be added or removed from the group using drag-and-drop in the Navigation tree.
    7. (Optional) Add child managed entity groups.
      • Child groups can be added by right-clicking on the group in the Navigation tree and selecting the New Managed entity group option.
      • Managed entity groups can also be added and removed using drag-and drop in the Navigation tree.

    The screenshot below shows the Gateway Setup Editor navigation tree for an example configuration. The image has been annotated with the configured attributes, and the resulting attributes that are applied for each managed entity.

    Example above shows managed entity groups and attributes with inheritance. Values on the left (in red) indicate attributes defined in the gateway setup. The values on the right (in blue) show the resulting attributes for each entity.

    Configuration

    Basic tab

    These settings are found in the Basic tab.

    managedEntities > managedEntityGroup > name

    Specifies the name of the managed entity group. Groups names are not read by gateway, and so can be used for descriptive purposes.

    Mandatory: Yes
    managedEntities > managedEntityGroup > attribute

    An entity group definition can contain any number of attributes. Each attribute is specified as a name-value pair containing a textual value (the attribute value). These attributes can then be used for searching and sorting in ActiveConsole 2. See Attributes.

    Mandatory: No
    managedEntities > managedEntityGroup > addTypes

    The add types setting allows Types to be added to an entity group. Types are referenced by name, and can be linked to an optional environment. See User Variables and Environments.

    Mandatory: No
    managedEntities > managedEntityGroup > addTypes > type > environment

    The environment setting allows an optional environment to be linked to a type reference, within a particular entity group definition. Samplers defined in the type will then use this environment to resolve any variables in the configuration. See Types.

    Mandatory: No

    Advanced tab

    These settings are found in the Advanced tab.

    managedEntities > managedEntityGroup > group

    Optionally specifies a group name, which is then be inherited by contained managed entities (or groups). See Gateway Installation Guide for more details.

    Mandatory: No
    Default: (no group)
    managedEntities > managedEntityGroup > removeTypes

    The remove types setting allows the removal of inherited types from an entity group definition. Types to be removed are listed (referenced) by name in this setting. Remove types are processed after inheritance, but before managedEntities > managedEntityGroup > addTypes to allow "overriding" of an inherited type.

    See Types.

    Mandatory: No
    managedEntities > managedEntityGroup > removeSamplers

    The remove samplers setting allows the removal of samplers from inherited types from a managed entity group definition. Samplers to be removed are listed (referenced) by name and the type they belong to in this setting.

    Mandatory: No
    managedEntities > managedEntityGroup > var

    Any number of variable definitions, configured with a name and value similar to Attributes. Managed entity variables override the entity environment if specified. Variables are used when resolving sampler configurations which contain variables. See User Variables and Environments.

    Mandatory: No