Health Rules Schema and Expression Language

To create a health rule for your domain entities, you need to understand the schema of a health rule. Any health rule that you create must follow the specified schema.

The Health Rule platform component provides you with two types of schemas:

• healthrule:healthRuleTemplate: Use this schema to create a health rule object file.

• healthrule:healthRuleScopeOverrides: Use this schema to create a health rule override object file where you can specify the entity types that you want to override and customize the rollup paths that you want to monitor.

Expression Language

The health rule expression language helps you to define:

• the entities to be evaluated.
• the conditions to evaluate the entities.
• the roll-up relationship for the entities, which controls the health of the parent entities based on the child entities.

Note: The health rule expression language mentioned in this document is version 2 (v2). The version 1 (v1) is no longer supported.

Evaluation Expression

In the topologyExpression field of the health rule template, you can define conditions to filter the specific entities that a health rule evaluates. The conditions are a subset of the Unified Query Language (UQL). For information about the UQL, see Unified Query Language User Guide.

The following table illustrates a few examples:

The following sample shows how to define an evaluation expression in your health rule object file:

Copy"evaluationObjects":  {
  "topologyExpression": "entities('spacefleet:starship').out.to('spacefleet:torpedo_tube)",
  "evaluationEntityType": "spacefleet:torpedo_tube"
}

Dynamic Grouping in Evaluation Expression

In the evaluation condition, you can add filters to monitor the entity types based on the filter criteria. For example, if you want to monitor a specific torpedo that has the name Black Shark, use the following condition in the topologyExpression field:

Copy"evaluationObjects":  {
    "topologyExpression": "entities('spacefleet:starship').out.to('spacefleet:torpedo_tube)[attributes("name")='Black Shark']",
    "evaluationEntityType": "spacefleet:starship"
}

Note: Dynamics grouping is supported only for metrics expressions.

Rollup Expression

A child entity can define the health of the parent entity by rollup relationship. The health of a parent entity can be rolled up based on the child entity. The path of the child entity is defined in the evaluation expression.

For example, in the following topologyExpression:

entities(k8s:cluster)[attributes("k8s.cluster.name")='appd-cluster'].out.to(k8s:namespace).out.to(k8s:workload).out.to(k8s:pod

The relationship among the entities can be defined as:

• k8s:cluster is the parent entity of k8s:namespace
• k8s:namespace is the parent entity of k8s:workload
• k8s:workload is the parent entity of k8s:pod

Alternatively, you can read the entity relationship as:

• k8s:pod is the child entity of k8s:workload
• k8s:workload is the child entity of k8s:namespace
• k8s:namespace is the child entity of k8s:cluster

To define the health rollup relationship among the entities, you need to use the following format in your health rule object file:

Copy{
   "rollupHealthConfig":{
      "rollupTo":"k8s:workload",
      "criteria":{
         "threshold":50,
         "thresholdType":"PERCENTAGE"
      },
      "rollupHealthConfig":{
         "rollupTo":"k8s:namespace",
         "criteria":{
            "threshold":40,
            "thresholdType":"PERCENTAGE"
         },
         "rollupHealthConfig":{
            "rollupTo":"k8s:cluster",
            "criteria":{
               "threshold":2,
               "thresholdType":"COUNT"
            }
         }
      }
   }
}

The preceding sample indicates the following health rollup relationship:

• If 50% of k8s:pod is unhealthy, then k8s:workload is unhealthy.
• If 40% of k8s:workload is unhealthy, then k8s:namespace is unhealthy.
• If two k8s:namespace entities are unhealthy, then k8s:cluster is unhealthy.

Boolean Condition Expression

A condition consists of a single or multiple statements that evaluate different metrics, events, and logs. When you define multiple conditions, you may want to define evaluation criteria using a boolean expression.

The advantages of using a boolean expression are:

• eliminates the need to create multiple health rules to monitor various performance metrics. Using a boolean expression allows you to evaluate complex criteria for multiple conditions in one go.

• well-calibrated boolean expression ensures reduced false alerts.

• easy to create and maintain health rules with complex evaluation criteria using simple condition names. Conditions are named as A, B, C, and so on. allows the use of and or operators to define a highly complex boolean expression.

The following sample illustrates how to use a boolean expression in the criteriaExpression field:

Boolean "(A or B)":

Copy"criticalCriteria": {
    "conditions": [
      {
        "name": "matter level",
        "conditionExpression": "metrics('${manifest.name & manifest.tag}:matter.utilization', 'space')[timestamp > now - 1m].value() < 10",
        "label": "A",
        "evaluateToTrueOnNoData": false
      },
      {
        "name": "anti matter level",
        "conditionExpression": "metrics('${manifest.name & manifest.tag}:anti_matter.utilization', 'space')[timestamp > now - 1m].value() < 10",
        "label": "B",
        "evaluateToTrueOnNoData": false
      }
    ],
    "criteriaExpression": "(A or B)"
  }

Boolean with condition:

Copy{
    "name": "Events-pod-filter",
    "description": "",
    "enabled": true,
    "scheduleName": "Always",
    "waitTimeAfterViolation": "5m",
    "evaluationObjects": {
        "topologyExpression": "entities(k8s:pod)[attributes(k8s.cluster.id)='events-UUID-alerting-test']",
        "evaluationEntityType": "k8s:pod"
    },
    "criticalCriteria": {
        "criteriaExpression": "A",
        "conditions": [
            {
                "name": "Condition 1",
                "label": "A",
                "conditionExpression": "(events(\"k8s:native_event\")[source = 'infra-agent'])[timestamp > (now - 30m)] < 1000",
                "evaluateToTrueOnNoData": false
            }
        ]
    },
    "entityType": "k8s:pod",
    "createdAt": "2023-10-17T07:03:54Z",
    "updatedAt": "2023-10-17T08:19:36Z",
    "id": "4bef91a3-669b-4859-b4d5-37e3630ea455"
}

Leaf Condition

The leaf condition of a health rule configuration represents one of the conditions that must be evaluated. You can create leaf conditions for metrics, events, and logs.

The output of a leaf condition is:

• 0 if the condition evaluates to true

• 1 if the condition evaluates to false

If the required data is not available, then the unknown result is represented by -1.

Example:

Consider the following leaf conditions for metrics and their specified labels:

You can form a boolean expression by combining conditions such as (A and (B or C)).

Points to Consider:

• You can form a boolean expression by combining multiple leaf conditions of the same type such as multiple metric-based conditions, event-based conditions, or log-based conditions. However, a boolean expression formed by combining an event-based condition, a metric-based condition, and a log-based condition is not supported.

• You can't configure an event-based condition to trigger when a violation occurs x times in the last y minutes.

Supported Functions

You can use the following functions in your expressions:

Supported Operators

You can use the following operators in your expressions:

Sample Condition Expressions

The following table illustrates a few sample condition expressions: