Customize Heuristic Packages

This section explains the following topics:

About Heuristic Packages

Crosswork Service Health uses Heuristic Packages as the core logic to monitor and report the health of services. Heuristic Packages define a list of rules, configuration profiles, supported subservices and associated metrics for every service type.

To access the Heuristic Packages, from the Main Menu, choose Administration > Heuristic Packages. The Heuristic Packages page has two tabs - System and Custom. The default set of Heuristic packages provided with Service Health are called system packages. These packages are available in the System tab. System packages cannot be modified. To customize a package to match your preferences you need to export, modify, and then import it back as a custom package. You can view the custom packages in the Custom tab.

Expand each section in this page to get more details on the services monitored and the thresholds used to generate alerts. You can also hover your mouse over the information i icon for finer details and definitions.

  • Rules: Rules are used to structure services and the dependant sub-services and metrics within a specific service type. Dependencies within these rules help define the sub-services and the metrics that will required for generating the data to assess the health of the service. A service can depend on an individual sub-service, a list of sub-services of the same type, or sub-services of different types.

    For list of rules supported in Service Health, see Basic and Advanced Monitoring Rules.

  • Configuration Profiles: Configuration Profiles define threshold values that act as benchmarks for assessing the health of the service. By setting specific threshold values, Configuration Profiles establish the criteria for determining when a monitored parameter is within an acceptable range or deviates from the norm.

    Service Health with system heuristics package includes two configuration profiles - Silver and Gold for each of the service types (L2VPN and L3VPN). You can choose a profile option that aligns with your specific monitoring requirements. For instance, a Silver profile has more lenient thresholds compared to a Gold profile. You can create custom configuration profiles as needed.

  • Sub Services: Sub services are characterized by a list of metrics to fetch and a list of computations to apply to these metrics in order to produce a health status and associated symptoms for the service.

    For example, the sub-service subservice.evpn.health monitors EVPN health. It is dependant on the metric metric.l2vpn.xconnect.pw.state. It evaluates an expression to check if evpn_state is Up and raises a symptom if degraded.

    For list of sub-services supported in Service Health, see Reference - Supported Subservices.

  • Metrics: Metrics define the operational data that should be fetched from different device types. Service Health uses a metric engine to map device-independent metrics to device-specific implementations, supporting multiple combinations of platforms and operating systems.

    For example, fetching the metric resource.cpu depends on the device type. For Cisco IOS XR devices, it uses Model-Driven Telemetry (MDT), while for Cisco IOS XE devices, it relies on CLI scraping using the command show platform resources.

In essence, there is a hierarchical relationship between Rules, Configuration Profiles, Sub services, and Metrics. Specifically, each Rule is mapped to a type of service, and depends on a number of sub-services to compute service health, sub-services use metrics and configuration profiles set threshold values for the metrics. Based on the values defined in these files, Service Health assesses the health of the service and builds the Assurance Graph.

Here is an example that illustrates the hierarchical relationship between Rules, Sub services, and Metrics.

Customizing Heuristic Packages

The Heuristic Package (HP) bundled with Service Health functions as an assurance model for monitoring L2VPN and L3VPN services. However, the configurations of underlay and overlay networking services may vary across deployments. While the Heuristic Package can adapt automatically to certain configuration variations, other variations cannot be seamlessly absorbed. Examples of such variations include changes in the service function pack model, the introduction of a new device type in VPN service deployment, or the introduction of new network features requiring monitoring. In these scenarios, customization may be necessary for configuration profiles, rules, metrics, or sub-service class definitions.

Refer to the section Build a Custom Heuristic Package for a basic example of how you can create a custom package by customizing the configuration profile for a service. For further details and assistance in building a custom package based on rules, metrics, or sub-services, reach out to Cisco's Customer Experience (CX) team or your Cisco account team.

Build a Custom Heuristic Package

The procedure outlined below provides the steps for building a custom Heuristic Package by adjusting the threshold for acceptable CPU usage on the device (CPU_THRESHOLD_MAX) within the Gold_L2VPN_ConfigProfile of the Heuristic Package for L2VPN services.

Procedure

Step 1

From the main menu, choose Administration > Heuristic Packages. The Heuristic Packages page opens with System and Custom tabs.

Step 2

Click the System tab and then click Export.

The exportAPI.tar.gz package gets downloaded to your system.

Step 3

Untar the exportAPI.tar.gz file, and you will get a system folder.

Step 4

In the ConfigProfile folder, open the Gold_L2VPN_ConfigProfile-system.json file.

Step 5

Make the following changes in the file:

  1. Change the namespace attribute for the profile to custom.

  2. Search for CPU_THRESHOLD_MAX and update the threshold value to 80. 

{
  "name": "Gold_L2VPN_ConfigProfile",
  "namespace": "custom",
  "version": "1.0",
  "description":  "Thresholds to use for Gold L2VPN services",
  "rules": [
    {
      "name": "Rule-L2VPN-NM",
      "namespace": "system"
    },
    {
      "name": "Rule-L2VPN-NM-P2P",
      "namespace": "system"
    },
    {
      "name": "Rule-L2VPN-NM-Basic",
      "namespace": "system"
    },
    {
      "name": "Rule-L2VPN-NM-P2P-Basic",
      "namespace": "system"
    },
    {
      "name": "Rule-L2VPN-MP-Basic",
      "namespace": "system"
    },
    {
      "name": "Rule-L2VPN-MP",
      "namespace": "system"
    }
  ],
  "values": {
    "MAX_ACCEPTABLE_IN_OUT_PKT_DELTA": {
      "description": "Max allowed difference between packets received and packets transmitted",
      "type": "VAL_INT",
      "intVal": {
        "unit": "NA",
        "val":  100
      }
    },
    "VPN_INTF_PKT_ERROR_THRESHOLD": {
      "description": "Acceptable delta of in(or out) packet errors expected between polling intervals",
      "type": "VAL_INT",
      "intVal": {
        "unit": "NA",
        "val":  10
      }
    },
    "VPN_INTF_PKT_DISCARDS_THRESHOLD": {
      "description": "Acceptable delta of in(or out) packet discards expected between polling intervals",
      "type": "VAL_INT",
      "intVal": {
        "unit": "NA",
        "val":  10
      }
    },
    "LATENCY_RT_THRESHOLD": {
      "description": "High Threshold for latency health checks",
      "type": "VAL_INT",
      "intVal": {
        "unit": "MSEC",
        "val":  500
      }
    },
    "JITTER_RT_THRESHOLD": {
      "description": "Threshold for acceptable jitter",
      "type": "VAL_FLOAT",
      "floatVal": {
        "unit": "MSEC",
        "val":  80
      }
    },
    "PACKET_LOSS_THRESHOLD": {
      "description": "Threshold for acceptable packet loss rate",
      "type": "VAL_FLOAT",
      "floatVal": {
        "unit": "PERCENT",
        "val":  1
      }
    },
    "SRPM_DELAY_THRESHOLD": {
      "description": "High Threshold for SR-PM latency health checks",
      "type": "VAL_INT",
      "intVal": {
        "unit": "MSEC",
        "val":  200
   
      }
    },
    "CPU_THRESHOLD_MAX": {
      "description": "Threshold for acceptable CPU usage on the device.",
      "type": "VAL_FLOAT",
      "floatVal": {
        "unit": "PERCENT",
        "val":  80
      }
    },
    "MEMFREE_THRESHOLD_MIN": {
      "description": "Threshold for minimum free memory to be available on the device.",
      "type": "VAL_FLOAT",
      "floatVal": {
        "unit": "BYTES",
        "val":  2000000000
      }
    }
  }
}

Step 6

Save the file once you have finished making the changes.

Step 7

Create a compressed tar.gz file from the system folder.

What to do next

Import the custom Heuristic Package in Crosswork Network Controller. See Import Custom Heuristic Packages.

Import Custom Heuristic Packages

Follow this procedure to import the custom heuristic package in Crosswork Network Controller.

Procedure

Step 1

From the main menu, choose Administration > Heuristic Packages. The Heuristic Packages page opens with System and Custom tabs.

Step 2

Click the Custom tab and then click Import. The Import Heuristic Packages dialog box appears.

Step 3

Click Browse to locate the custom package (*.tar.gz file) on your system.

Step 4

Select your custom package and click Preview to review the details of the package to be imported. Further information on the package’s Rules, Configuration Profiles, Sub Services, and Metrics appears.

Note

 
Your system performance might be impacted during heuristic package import due to high server resource consumption.

Select each option to preview the details of the custom package. Crosswork Network Controller will validate the package and display an error message if any issues exist. If there are no validation errors, Crosswork Network Controller will display a success message.

Step 5

Select the check box to acknowledge the warning and click Import. The package gets imported in Crosswork Network Controller and appears in the Custom tab in the Configuration Profiles section.

What to do next

To monitor services with custom heuristic packages, stop monitoring the service first. Start monitoring the service again by selecting the custom package and click Start Monitoring. See Step 4 in the procedure Start Service Health Monitoring for more information.