RCA Availability Engine Rules

RCA Availability Engine rules are JSON files that define how the RCA Availability Engine interprets collected availability states and determines which events to generate. They let you extend RCA behavior for newly supported availability instance types, provided that the required availability data is already being collected and available to the RCA Availability Engine.

The RCA Availability Engine uses these rule files to evaluate availability messages from the SNMP and Ping pollers, correlate them to devices and instances, and send the resulting events to the Event pipeline. See RCA Availability Engine and Understanding the Event Pipeline for more information.

With RCA rule files, you can:

Add support for additional instance types
Interpret vendor-specific availability fields
Define whether a state is administrative or operational
Map raw values to healthy or unhealthy RCA meaning
Control event priority by using weights

Note:

RCA rule files extend RCA behavior only when the required availability data is already being collected. If the required data is not being collected, first add or correct the supporting ACOM and discovery configuration.

You can review the default RCA rule files in the Rules UI by expanding the following path:

Core Rules (core)/Default read-write branch (default)/processing/event/rca/_objects

After you create or update an RCA rule file, restart or redeploy the RCA Availability Engine microservice so that the new rules are loaded.

Users typically create or update RCA rule files when they need to extend RCA interpretation to newly discovered instance types or vendor-specific availability states.

The default RCA rules support the following instance types:

Interface
BGP Peer
OSPF Neighbor
Entity
Vendor-specific types such as HwInterface and Sonus Ethernet port types

RCA Rule File Format

The following is the expected RCA rule format:

{
  "objects": [
    {
      "@objectName": "<object_name>",
      "instanceType": "<instance_type>",
      "description": "",
      "_type": "availabilityStates",
      "availabilityStates": [
        {
          "stateName": "<state_name>",
          "stateCategory": "<admin_or_operational>",
          "triggeredEvent": "<event_name>",
          "stateDescription": "<state_description>",
          "weight": <weight>,
          "fieldIdentifier": "<field_name>",
          "mapping": {
            "<raw_value>": {
              "status": "<status_text>",
              "value": "<true_or_false>"
            }
          }
        }
      ]
    }
  ]
}

RCA Rule Object Properties

The following table describes the properties supported for each object in an RCA rule file.

Property	Requirement	Supported Values	Description
objects	Required	Array	Contains one or more RCA rule objects.
@objectName	Required	Text	Specifies the object or table to which the rule applies, such as an MIB table.
instanceType	Required	Text	Specifies the instance type to which the rule applies, such as interface, BGPPeer, OSPFNeighbor, entity, or a custom type.
description	Optional	Text	Provides a description of the RCA rule object.
_type	Required	availabilityStates	Specifies the type of rule content.
availabilityStates	Required	Array	Contains the availability state definitions for the object.

The availabilityStates property is described in detail in the following section.

RCA Availability State Properties

The following table describes the properties supported for each availability state in an RCA rule file.

Property	Requirement	Supported Values or Types	Description
stateName	Required	Text	Specifies the name of the availability state.
stateCategory	Required	admin or operational	Specifies whether the state represents an administrative or operational condition.
triggeredEvent	Required	Text	Specifies the RCA event generated when the state indicates a problem.
stateDescription	Optional	Text	Provides a description of the availability state.
weight	Required	Integer	Specifies the priority of the state when multiple states could apply. States with higher weights take precedence.
fieldIdentifier	Required	Text	Specifies the availability field to evaluate. This value must exactly match the collected availability field name.
mapping	Required	Object	Defines the mapping between collected field values and the corresponding availability state.

The mapping property is described in detail in the following section.

RCA Mapping Properties

Each entry in the mapping object uses the properties described in the following table.

Property	Requirement	Supported Values or Types	Description
status	Required	Text	Specifies a human-readable label for the raw value.
value	Required	"true" or "false"	Specifies whether the raw value represents a healthy ("true") or unhealthy ("false") state. Represent these values as the strings "true" and "false" in the JSON rule file.

When creating mappings, note the following:

Use "true" when the raw value represents a healthy or available state.
Use "false" when the raw value represents a down, unavailable, disabled, or otherwise unhealthy state.
Use higher weight values for states that should take precedence. For example, an administrative disabled state typically takes precedence over an operational down state.
Use integer-formatted strings for mapping keys, represented by , such as "1", "2", or "100".

Consistency Requirements Across Files

RCA rule files must remain consistent with the corresponding ACOM definitions. The RCA Availability Engine can apply rules correctly only when the RCA fields reference the values produced by ACOM.

RCA Field	Corresponding ACOM Field	Description
instanceType	snmp.instance.type	Specifies the availability instance type to which the RCA rule applies.
fieldIdentifier	Final collected availability field name	Specifies the availability field evaluated by the RCA rule. This value must match the final field name produced by ACOM.
@objectName	@objectName	Specifies the monitored object or table to which the RCA rule applies.

The instanceType value determines which RCA rule applies to a discovered instance. For example, if ACOM produces SonusEthernetPacketPort, the RCA instanceType must also be SonusEthernetPacketPort.

The fieldIdentifier value must match the final availability field name that reaches the RCA Availability Engine. If ACOM processors rename a field or create a derived field, RCA must reference the final field name rather than the original source field.

The @objectName value should identify the same monitored object or table as the related ACOM definition so that the RCA rule applies to the correct availability object.

Creating or Updating an RCA Rule File

To create or update an RCA rule file:

Identify the object or table the rule should apply to.
Identify the instance type to monitor.
Identify the collected availability field that should be evaluated.
Decide whether the field is an admin state or an operational state.
Decide which RCA event should be raised when the state indicates a problem.
Define the raw value mappings using integer-formatted string keys::
- Use "true" for values that represent a healthy state.
- Use "false" for values that represent a problem state.
Assign a weight.

Use a higher weight for the state that should take precedence if more than one state applies.
Save the file in the RCA rules location and restart the RCA Availability Engine microservice.

Example RCA Rule File

The following example shows an RCA rule for interface operational and administrative states:

Note:

RCA rule file names must end with the -RCA.json suffix, for example, ExamplePort-RCA.json.

{
    "objects": [
        {
            "@objectName": "IF-MIB::ifTable",
            "instanceType": "interface",
            "description": "Operational and admin status of Interface",
            "_type": "availabilityStates",
            "availabilityStates": [
                {
                    "stateName": "InterfaceOperationalState",
                    "stateCategory": "operational",
                    "triggeredEvent": "InterfaceDown",
                    "stateDescription": "Operational status of an interface",
                    "weight": 1,
                    "fieldIdentifier": "IfOperStatus",
                    "mapping": {
                        "1": {
                            "status": "up",
                            "value": "true"
                        },
                        "2": {
                            "status": "down",
                            "value": "false"
                        }
                    }
                },
                {
                    "stateName": "InterfaceAdminState",
                    "stateCategory": "admin",
                    "triggeredEvent": "InterfaceDisabled",
                    "stateDescription": "Admin status of an interface",
                    "weight": 2,
                    "fieldIdentifier": "IfAdminStatus",
                    "mapping": {
                        "1": {
                            "status": "up",
                            "value": "true"
                        },
                        "2": {
                            "status": "down",
                            "value": "false"
                        }
                    }
                }
            ]
        }
    ]
}

In this example:

IfOperStatus raises InterfaceDown when the value indicates the interface is not up.
IfAdminStatus raises InterfaceDisabled when the value indicates the interface is administratively down.
The administrative state uses a higher weight, so it takes precedence over the operational state if both conditions apply.

Use the following definitions in the default RCA rule files from the Rules UI as reference examples when creating custom RCA rules.

Interface rules that map interface operational and administrative status fields to InterfaceDown and InterfaceDisabled events.
BGP Peer rules that map BGP peer state fields to BGPSessionDown events.
OSPF Neighbor rules that map OSPF neighbor state fields to OSPFNeighborStateDown events.
Entity rules that map multiple vendor-specific entity state fields to EntityDown events.

Note:

When creating RCA rule files, keep the following in mind:

If multiple vendor-specific objects apply to the same instance type, you can include them in the same file or in separate files, as long as the definitions remain clear and consistent.
fieldIdentifier must be unique across all RCA rule files, because definitions using the same identifier can overwrite each other at runtime.
Test new rules in a non-production environment before using them in production.

RCA rule files provide a flexible way to extend RCA support, but they can interpret only the availability data that is already being collected and made available to the RCA Availability Engine. If the required data is not available, you may need to add or update the supporting ACOM configuration, Graph metadata, or other platform configurations before the RCA rule can work correctly. For information about the complete workflow for adding support for a new instance type, see About Supporting New Availability Instance Types.

Title and Copyright Information

Implementation Guide

G49441-03