Management-zone rules

Management zones comprise one or more rules that define and limit the entities or dimensional data (such as logs and metrics) that can be accessed within the management zone.

When you select a management zone in Settings > Preferences > Management zones, all configured rules are displayed. You can Disable/Enable individual rules.

Rule types

Management zones offer UI-based rule definition for:

• Monitored entities
• Dimensional data (logs and metrics)

You can select the type of rule, and then create rule conditions based on entity/data properties, operators, and values where relevant.

When creating rules for some entities, you can propagate access to related topological entities without creating an extra rule. See How management-zone rules are applied below.

For UI-based rules for dimensional log and metric data, you can define conditions based on the log file name, metric keys and dimension keys and values. Built-in, calculated, and ingested metrics are supported.

Note that users automatically get access to logs and metrics associated with entities that are included within their assigned management zones.

Text-based rules leverage the powerful entity selector for v2 Environment APIs to define entities. Text-based rules enable you to define entity access based on all the entity types, properties, values, and relationships exposed by the Monitored entities API v2.

There are several advantages of text-based rules.

• You can provide granular and focused entity definitions without having to review the subset of choices available in the UI.
• While UI-based rules allow for some relationship-based propagation of entity access, with text-based rules, you can explicitly use relationships to filter your entity selection. You have the flexibility to decide exactly which relationships you want to use to filter entities.
• You can define text-based rules for including your own custom entity types, attributes, and relationships in management zones.

Add a UI-based rule for entities

See Examples for different rule types and implementations.

1. Select/create a management zone and then select Add a new rule.

2. Select Monitored entity as the Rule type. (See also information on rules for dimensional data and text-based rule definition via the Entity selector.)

3. Select the entity type to which the rule should apply (Rule applies to), for example, Web applications.

   

4. Each entity can be defined and limited by several different conditions. Select Add condition.

5. Choose the condition Property, Operator, and Value (where relevant). For example, you can specify that the Web application name begins with a specified string. You can enter up to 80 characters; wildcard characters are not allowed; regular expressions are allowed in the contains regex and does not contain regex condition operators.

6. If you enter a text string, specify whether it is Case sensitive.

   

7. For some entities, you can propagate access to related topological entities without creating an extra rule. For example, turn on the appropriate toggles to include underlying hosts and process groups when defining a management-zone rule for Services.

   

8. Select Add condition to add another condition (or Remove condition to remove a condition) as required.

   Notes

   • You need to define at least one condition per rule.
   • Conditions are applied using the AND logic—all conditions need to be met for the rule to apply to an entity.
   • There's no limit on the number of conditions per rule. However, there's a limit of 100,000 conditions for all rules taken together per environment.

9. Select Preview to see entities matching the rule that were active and online in the last 72 hours. Of course, when you actually apply the management zone, all entities matching the rules for the given timeframe will be displayed. Note that Preview is only available for entity-based rules.

   

10. Save changes.

Add a UI-based rule for dimensional data

See Examples for different rule types and implementations.

1. Select/create a management zone and then select Add a new rule.

2. Select Dimensional data for Rule type. (See also information on rules for entities and text-based rule definition via the Entity selector.)

3. Select the data Type to which the rule should apply.

   • For a UI-based rule for a built-in, calculated, or ingested metric, select METRIC.

   • For a UI-based rule for logs, select LOG.

4. Each rule can be defined and limited by several different conditions. Select Add condition.

5. Choose the condition Type, Key (where appropriate), Operator, and Value. You can enter up to 80 characters in any text field; wildcard characters are not allowed.

   Condition types are:

   • For a log attribute or metric dimension, DIMENSION.

     

   • For a log filename, LOG_FILE_NAME. The log filename should match the attribute log.source.

     

   • For a metric key, METRIC_KEY.

     

   • For a combined log or metric condition, ANY.

   Allowed operators are begins with and equals.

6. Select Add condition to add another condition (or Remove condition to remove a condition) as required.

   Notes

   • You need to define at least one condition per rule.
   • Conditions are applied using the AND logic—all conditions need to be met for the rule to apply to an entity.
   • There's no limit on the number of conditions per rule. However, there's a limit of 100,000 conditions for all rules taken together per environment.
   • Preview is not available for dimensional-data rules.

7. Save changes.

Add a text-based entity selector rule

1. Select/create a management zone and then select Add a new rule.

2. In Rule type, select Entity selector.

3. To fill out the Entity Selector text string, you might need to run Monitored entities API v2 calls to fetch entity types, properties, values, and relationships. Consult entity selector documentation for details on how to construct an entity definition. See Examples for different rule types and implementations.

   Important parts of the entity selector string

   • type(<entityType>) defines the type of entity that is subject to the rule. For example, the entity type for hosts is host and for process groups is process_group. The entity type is not case sensitive. You can only provide a single entry in <entityType>.

     Run the GET all entity types API call for a list of all entity types in your environment (including custom entities) and their properties.

     Alternatively, you can specify multiple individual entity IDs with the entityId criterion. You can run the GET entities list API call for a list of actual entities in your environment and their properties.

   • Entity properties and values filter the entity list that your rule applies to. For example:

     • entityName.startsWith("Book") filters for entities whose name starts with Book.
     • serviceType(WEB_REQUEST_SERVICE) filters for web request services.

     You can run the GET entity type API call for any entity type (for example, service) to get a list of all its properties (for example, serviceType). You can also run the GET entities list API call for a list of actual entities in your environment with their property values (for example, WEB_REQUEST_SERVICE).

   • Relationships further refine entity selection by defining an entity in terms of its relationship to another. Relationships are of two kinds.

     • A fromRelationsip implies that the direction of the relationship is from the given entity (that is, the entity being queried) to a related entity. When you query all the services that service A calls, this is a relationship “from (service A)” to other services.
     • A toRelationship implies that the direction of the relationship is from a related entity to the given entity (that is, the entity being queried). When you query all the services that call service A, this relationship is “to (service A).”

     You can run the GET entity type API call on any entity type to get a list of the entity's from/to relationships and the related entity types. You can also run the GET entities list API call to get a list of the actual entities in your environment along with their relationship values (for example, a service entity type can have a calls "from relationship" to another service).

4. Select Preview to see entities matching the rule that were active and online in the last 72 hours. (Of course, when you actually apply the management zone, all entities matching the rules for the given timeframe will be displayed.)

   

5. Save changes.

How management-zone rules are applied

• Conditions are applied using the AND logic—all conditions within a rule need to be met for the rule to apply to an entity.

• Rules are applied using the OR logic—any rule must apply for an entity to be included in a management zone.

• When creating rules for some entities, you can propagate access to related topological entities without creating an extra rule. For example, when creating a rule for services, you can opt to add underlying hosts and process groups. See Add a UI-based rule above.

  In other cases, the propagation of access to related topological entities is implicit. For example, when you grant access to a host in a management zone, any custom metrics ingested via that host are also accessible within the management zone. Note that this does not automatically include all measurements of those custom metrics but only those measurements that were sent in for your host.

  In cases where such propagation isn't available, you need to explicitly create rules for the entities you wish to add to a management zone. For example, a management-zone rule that applies to Host groups does not automatically grant access to the hosts within those groups; you need to explicitly add rules for the Hosts you wish to include in the management zone, as shown in Examples below.

• When you add an entity using tags to a management zone as part of entity creation via API, there might be a delay in management-zone assignment depending on the number and complexity of your tagging rules. See Best practices for scaling tagging and management-zone rules for best practices to speed up the time taken to assign tags and management zones within your monitoring environments.

• You cannot define management-zone rules where the entity selector for one management zone filters by another management zone. Management zone predicates such as mzID or mzName are not allowed in entity selector strings. This means, for example, that you cannot define management zone A as containing hosts belonging to management zone B. Management-zone rules based on other management zones increase the number of runs made by the conditional decision engine and can greatly delay management-zone assignment. See also Best practices for scaling tagging and management-zone rules for related information.

  As a workaround, use the same entity selector string in both management zones. For example, consider that:

  • Management zone A has the rule type(SERVICE),entityName.startsWith("myService"),tag(my:tag").
  • Management zone B is required to include services that call services in Management zone A. To do so, define the rule type(SERVICE),fromRelationships.calls(type(SERVICE),entityName.startsWith("myService"),tag(my:tag")).

Examples